Skip to main content
The gateway reads one YAML (or JSON) file that defines its routers and any custom provider endpoints. The file holds no secrets. Gateway keys, provider keys, and subscriptions live in the environment and the gateway database.

A Complete Example

Routers

Each key under routers 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 is provider/model, the same form dari/model/<id> uses. The Models page lists them.
  • thinking limits the levels offered. Valid levels are off, minimal, low, medium, high, xhigh, and max. Leave it out to offer every level the model supports.
  • GET /v1/models?detail=1 lists the levels each model accepts. medium and high work 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 offered models, 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:
The agents are 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 the model field:
  • dari/routing lets the router choose. With DARI_AUTO_ROUTING_API_KEY set, 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’s agentModels list), or the request fails with model_not_enabled. The client’s thinking level is used when the model supports it.
Auto Routing sends the conversation context to Dari for each selection. See Data Handling.

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 routers map, or no routers in it.
  • A router with an empty or missing models list.
  • A model id that is not provider/model, or a model listed twice in one list.
  • An agentModels entry for an unknown coding agent, or with an empty list.
  • A thinking level outside the list above.
  • retries outside 0 to 5, or a boolean setting that is not true or false.
  • A providers entry without a baseUrl.

Details

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.
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.