A Complete Example
Routers
Each key underrouters is a router id. default serves /v1/.... Any other router serves /<id>/v1/..., so local above serves /local/v1/.... Ids may use letters, digits, -, and _.
Models And Thinking Levels
A model id isprovider/model, the same form dari/model/<id> uses. The Models page lists them.
thinkinglimits the levels offered. Valid levels areoff,minimal,low,medium,high,xhigh, andmax. Leave it out to offer every level the model supports.GET /v1/models?detail=1lists the levels each model accepts.mediumandhighwork for every model on the Models page.- A model can appear once per router. To offer it at several levels, list it once with those levels.
Models Per Coding Agent
Each coding agent is offeredmodels, less the ones no credential can serve it. A Claude Code or Muse Code subscription serves only its own agent. Without an API key for that provider, its models are listed only for that agent.
To give one agent a different list, add it under agentModels:
claude_code, codex, muse_code, opencode, pi, openclaw, and hermes. An agent’s list replaces models for that agent. It is what the agent’s picker shows, what dari/routing chooses among, and what dari/model/<id> accepts. The list need not be a subset of models, and entries take thinking as usual. Agents without a list, and every other client, get models.
Change Models From The CLI
dari setup <agent> opens the model picker on the gateway’s default router, the same picker a hosted router has. It works against a gateway on your machine or on a server, and needs only its URL and one of its keys.
Router Spec Files
A router spec is a whole router in one YAML file, the same format hosted Dari uses. The gateway runs one beside its config file’s routers, served at/<name>/v1/... as soon as it is saved, with no restart.
dari router acts on the gateway while agents route through one; --hosted acts on your hosted org instead. pull needs a hosted sign-in. dari setup <agent> --router <name> pulls or applies the router and points the agent at it; --default keeps it for later launches on a local gateway.
When a router’s model has no subscription or API key behind it yet, a launch in a terminal shows what each model needs and connects it there: a plan to sign in to, or on a local gateway an API key to paste. Without a terminal, it names the command for each.
The gateway pays with its own subscriptions and API keys, so payment.allow only decides whether subscriptions serve the router; Dari credits don’t apply. Settings under hosted and routing.rules run only on hosted Dari: the gateway ignores hosted and refuses rules. A model’s provider may be fireworks or opencode-go, so a spec can run DeepSeek on an OpenCode Go plan.
To load specs at startup instead, set DARI_GATEWAY_ROUTERS_DIR to a directory of *.yaml files; each file’s name is its router’s name. A spec saved through the CLI replaces a file or config router with the same name until it is deleted.
Choosing A Model Per Request
Clients choose how a router picks a model with themodel field:
dari/routinglets the router choose. WithDARI_AUTO_ROUTING_API_KEYset, Dari Auto Routing picks among the router’s models for each request. Without it, the router serves its first model that has a credential, and moves down the list when a provider fails.dari/model/<id>serves exactly that model. The model must be in the list the router serves that client (models, or the sending agent’sagentModelslist), or the request fails withmodel_not_enabled. The client’s thinking level is used when the model supports it.
Custom Provider Endpoints
Built-in providers need no entry. Their endpoints and keys come from the model catalog and each provider’s standard variable. Add one for any other server, such as vLLM, Ollama, or another OpenAI-compatible endpoint:
Models with the provider’s prefix use the endpoint. The provider id is the part before the first slash, so
local/qwen3-coder above uses this one. Ids may use lowercase letters, digits, ., and -.
Validation
The gateway refuses to start on an invalid file and reports the first problem it finds, for example:- No
routersmap, or no routers in it. - A router with an empty or missing
modelslist. - A model id that is not
provider/model, or a model listed twice in one list. - An
agentModelsentry for an unknown coding agent, or with an empty list. - A
thinkinglevel outside the list above. retriesoutside0to5, or a boolean setting that is nottrueorfalse.- A
providersentry without abaseUrl.
Details
Saved model lists
Saved model lists
The model picker saves the list in the gateway database, and the gateway serves it from the next request with no restart. A saved list replaces the config file’s list for that router, and the file is never rewritten. Startup logs routers with saved lists as
saved_model_lists.How the gateway recognizes an agent
How the gateway recognizes an agent
Claude Code, Codex, Muse Code, and OpenCode send headers that name them, and Pi sends them through the extension
dari pi installs. OpenClaw and Hermes name themselves in an x-dari-client-harness header once dari openclaw or dari hermes sets them up, so run the launcher again after upgrading the CLI. Other clients can name an agent in that header, except claude_code and muse_code: their subscriptions serve only that agent, so the gateway takes those two only from the agent’s own headers.