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.comorhttps://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):
| Role | Used for |
|---|---|
| Chat | the assistant's turns |
| Worker (called Sub-agent before 0.2.0) | the agents a swarm, a mission or the assistant starts |
| Validator | the validators that check each milestone of an Ultra mission in the ncode app; unset, it uses the Chat model |
| Scheduled | tasks that run on a schedule |
| Workflow | agents inside workflow runs |
| Implementer | the agent that carries out a judged plan |
| Judge | the reviewer in a judged (consensus) turn; it falls back to the Worker model |
| Research lead, worker and reporter | the three roles of a deep research |
Reasoning effort#
Effort is how hard a model thinks before it answers. The built-in levels are:
| Level | Meaning |
|---|---|
low | fastest |
medium | balanced |
high | deeper reasoning |
xhigh | coding and agentic work |
max | maximum 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:
| Preset | Kind | Base URL |
|---|---|---|
| Anthropic | Anthropic | https://api.anthropic.com |
| OpenAI | OpenAI-compatible | https://api.openai.com/v1 |
| OpenRouter | OpenAI-compatible | https://openrouter.ai/api/v1 |
| DeepSeek | OpenAI-compatible | https://api.deepseek.com/v1 |
| Ollama | OpenAI-compatible | http://localhost:11434/v1 |
| LM Studio | OpenAI-compatible | http://localhost:1234/v1 |
| Other | OpenAI-compatible | the 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:
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.

Choosing models#
| Where | Setting or command | Scope |
|---|---|---|
| Default chat model | Chat model (models.chat) in Models & effort | every new conversation |
| Default worker model | Worker model (models.sub_agent) | agents started from now on |
| Validator model | Validator model (models.validator); the setting reads "the main model" until you choose | checking a mission's work in the ncode app; the CLI's Ultra runs workflows and does not use it |
| Other roles | models.scheduled, models.workflow, models.implementer | their runs |
| This conversation | /model, /worker_model | this conversation, saved |
| This session only | ncode --model <model> or --model provider/model | until 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#
/costshows 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.