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 and sub-agent model:
| Role | Used for |
|---|---|
| Chat | the assistant's turns |
| Sub-agent | the agents a swarm or the assistant starts |
| 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 sub-agent 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 shows what is new or gone before it changes anything. 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. See ncode config.
Choosing models#
| Where | Setting or command | Scope |
|---|---|---|
| Default chat model | Chat model (models.chat) in Models & effort | every new conversation |
| Default sub-agent model | Sub-agent model (models.sub_agent) | agents started from now on |
| Other roles | models.scheduled, models.workflow, models.implementer | their runs |
| This conversation | /model, /swarm_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 sub-agent models are those of the first provider with a key. Effort works the same way: Default effort and Sub-agent effort in Settings, /effort and /swarm_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.
- 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. After that, environment variables never add providers or change a conversation's model. See the Quickstart.