ncode

CLI docs Providers and models

ncode CLI Configure

Providers and models

Providers#

ncode talks to the model endpoints you add. It ships with no key of its own: you bring yours.

A provider has:

  • a kind: Anthropic (the Messages API) or OpenAI-compatible (any endpoint that speaks the OpenAI chat API: OpenAI itself, OpenRouter, DeepSeek, or a local server such as Ollama or LM Studio);
  • a base URL, for example https://api.anthropic.com or https://api.openai.com/v1;
  • an API key (a local server may not need one);
  • its models, typed in or fetched from the endpoint's model list, and a default model.

Models per role#

Different kinds of work can use different models. Each role has its own default, and a conversation can still pick its own chat model and the model for the agents it starts (the helper agents are the Worker model):

RoleUsed for
Chatthe assistant's turns
Worker (called Sub-agent before 0.2.0)the agents a swarm, a mission or the assistant starts
Validatorthe validators that check each milestone of an Ultra mission in the ncode app; unset, it uses the Chat model
Scheduledtasks that run on a schedule
Workflowagents inside workflow runs
Implementerthe agent that carries out a judged plan
Judgethe reviewer in a judged (consensus) turn; it falls back to the Worker model
Research lead, worker and reporterthe three roles of a deep research

Reasoning effort#

Effort is how hard a model thinks before it answers. The built-in levels are:

LevelMeaning
lowfastest
mediumbalanced
highdeeper reasoning
xhighcoding and agentic work
maxmaximum thinking

A provider, and each of its models, can carry its own list of levels, so the levels you see are the ones your provider offers.

Pricing and budget#

You can enter a price per million input and output tokens (and cache reads and writes) for each model, so every run shows what it cost. A monthly budget is a spend target you watch; nothing is blocked when it runs out.

Adding a provider in the terminal#

Open Settings at Providers (ncode settings providers, or F2 in a session) and add one from a preset. The preset fills in the kind and the base URL:

PresetKindBase URL
AnthropicAnthropichttps://api.anthropic.com
OpenAIOpenAI-compatiblehttps://api.openai.com/v1
OpenRouterOpenAI-compatiblehttps://openrouter.ai/api/v1
DeepSeekOpenAI-compatiblehttps://api.deepseek.com/v1
OllamaOpenAI-compatiblehttp://localhost:11434/v1
LM StudioOpenAI-compatiblehttp://localhost:1234/v1
OtherOpenAI-compatiblethe URL you enter

The new provider starts as a draft. Paste the key, then press Ctrl+S: ncode creates it and tests the key against the endpoint. A provider on your own machine or private network (Ollama, LM Studio, a server on your LAN) needs no key.

Then fetch models: ncode reads the endpoint's model list and saves it, and the screen where you started the fetch says what happened, for example 12 models · 3 new · 2 removed, or the error in a sentence, with nothing changed. The saved list replaces the old one, so a model the endpoint renamed (to an id such as ms/glm-5.2, slash included) appears under its new id and the old id is gone; a conversation that still names a removed model keeps sending it until you pick another. Fetch every provider's models does the same for every provider and lists one line per provider. A list of more than 2,000 models is only added to, never replaced, and says how many were kept. Each provider also has its own list of effort levels.

From a shell, the same steps are:

sh
ncode config record add provider --preset openrouter
printf '%s' "$OPENROUTER_API_KEY" | ncode config secret provider:OpenRouter --stdin
ncode config set models.chat OpenRouter/<model-id>

The record takes the preset's name (Anthropic, OpenRouter, …) unless you give --name. The preset can be named by id or by display name, in any case; --base-url and --kind anthropic|openai override what the preset fills in. See ncode config.

OpenRouter provider settings with a masked API key, model settings and the fetched model list.

Choosing models#

WhereSetting or commandScope
Default chat modelChat model (models.chat) in Models & effortevery new conversation
Default worker modelWorker model (models.sub_agent)agents started from now on
Validator modelValidator model (models.validator); the setting reads "the main model" until you choosechecking a mission's work in the ncode app; the CLI's Ultra runs workflows and does not use it
Other rolesmodels.scheduled, models.workflow, models.implementertheir runs
This conversation/model, /worker_modelthis conversation, saved
This session onlyncode --model <model> or --model provider/modeluntil you quit or use /model; nothing is saved

Until you choose, the chat and worker models are those of the first provider with a key. Effort works the same way: Default effort, Worker effort and Validator effort in Settings, /effort and /worker_effort in a conversation (see Modes and run types).

Cost and budget#

  • /cost shows the tokens and cost of this conversation, by model.
  • Usage in the Ctrl+P palette opens the usage view.
  • Settings → Pricing holds the price per million tokens of each model and its context window.

Context window#

A model with no context window of its own gets 1,000,000 tokens, and the status line shows what is used against it (ctx 8k/1M). ncode keeps the history it sends to 75 % of the window. Set a model's own window, from 8,000 to 2,000,000 tokens, in Settings → Models & effort under context windows (one row for each model the conversation uses; R puts a row back to the default) or in Pricing; the Mac app's Pricing page edits the same value. A model that has no price row yet opens its price draft first, because a window is stored on the price row. If a provider's real window is smaller than the one ncode assumes and it refuses a long history, ncode trims under what the provider named, keeps that smaller budget for the rest of the run and carries on.

  • Settings → Budget & usage sets the monthly budget (budget.monthly_usd).

Setting a provider from the environment#

On a Mac where the database has no usable provider yet, the first launch can create one from NCODE_PROVIDER, NCODE_MODEL, NCODE_BASE_URL and NCODE_API_KEY (the model is required; ANTHROPIC_API_KEY or OPENAI_API_KEY alone also default the endpoint). The provider is named after the matching preset, or after the host, and Settings says that the model came from env NCODE_MODEL · first run. After that, environment variables never add providers or change a conversation's model. See the Quickstart.