> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dari.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Routers

> Reference for dari-gateway.yaml: routers, their models and thinking levels, and custom provider endpoints.

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

```yaml theme={null}
routers:
  default:                       # serves /v1/...
    models:
      - anthropic/claude-sonnet-5-5
      - anthropic/claude-opus-5-5
      - id: openai/gpt-6.2-sol
        thinking: [medium, high]
    agentModels:                 # a coding agent's own list, in place of models
      codex:
        - openai/gpt-6.2-sol
        - openai/gpt-6.1-terra
    subscriptions: true          # serve from connected plans before API keys
    sessionPinning: false        # route each session once, then keep its model
    nativeCompaction: false      # let Codex compact with the provider's native compaction
    retries: 1                   # same-model retries before failing over
    zdr: false                   # zero data retention

  local:                         # serves /local/v1/...
    models: [local/qwen3-coder]

providers:                       # endpoints outside the built-in catalog
  local:
    baseUrl: http://localhost:8000/v1
    apiKeyEnv: LOCAL_API_KEY
```

## 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 `_`.

| Setting | Default | Meaning |
| - | - | - |
| `models` | Required | Non-empty list of models the router serves. Each entry is a model id, or an object with `id` and `thinking`. |
| `agentModels` | None | A model list for one coding agent, served to it in place of `models`. See [Models Per Coding Agent](#models-per-coding-agent). |
| `subscriptions` | `true` | Serve with connected plans before API keys, each model trying every plan that serves it. See [Subscriptions](https://docs.dari.dev/gateway/subscriptions.md#one-model-several-plans). Set `false` to use only API keys. |
| `sessionPinning` | `false` | Route each session's first turn, then keep that model for the whole session. Each subagent is routed once on its own. |
| `nativeCompaction` | `false` | Let Codex compact context server-side with the provider's native compaction. Requests carrying compaction state are routed only to models that support it. |
| `retries` | `1` | Same-model retries on a failing provider call, from `0` to `5`. After the retries, the router moves to its next model. |
| `zdr` | `false` | Zero data retention. See [Data Handling](https://docs.dari.dev/gateway/operations.md#data-handling). |

### Models And Thinking Levels

A model id is `provider/model`, the same form `dari/model/<id>` uses. The [Models](https://docs.dari.dev/gateway/models.md) page lists them.

```yaml theme={null}
models:
  - anthropic/claude-sonnet-5-5          # every thinking level the model supports
  - id: openai/gpt-6.2-sol
    thinking: [medium, high]             # only these levels are offered
```

* `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](https://docs.dari.dev/gateway/models.md) 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`:

```yaml theme={null}
routers:
  default:
    models:
      - anthropic/claude-sonnet-5-5
      - openai/gpt-6.2-sol
    agentModels:
      claude_code:
        - anthropic/claude-fable-5-2
        - anthropic/claude-sonnet-5-5
      codex:
        - id: openai/gpt-6.2-sol
          thinking: [high]
```

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](https://docs.dari.dev/router/create-a-router.md#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.

```bash theme={null}
dari router apply ./opus-deepseek.yaml       # saved as the router opus-deepseek
dari router pull opus-5-5-deepseek-subagents # a published template, from hosted Dari
dari router list
dari router get opus-deepseek
dari router delete opus-deepseek
dari setup claude --router opus-deepseek --default
```

`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](https://docs.dari.dev/gateway/operations.md#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:

```yaml theme={null}
providers:
  local:
    baseUrl: http://localhost:8000/v1    # required
    api: openai-completions              # optional; the default
    apiKeyEnv: LOCAL_API_KEY             # optional; names the variable holding the key
```

| Setting | Default | Meaning |
| - | - | - |
| `baseUrl` | Required | The endpoint's base URL. |
| `api` | `openai-completions` | The wire API the endpoint speaks: `openai-completions`, `anthropic-messages`, or `openai-responses`. |
| `apiKeyEnv` | None | The environment variable that holds the endpoint's API key. Omit it for an endpoint that takes no key. |

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

> [accordion] 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`.

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.