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

# opencode

> Route the opencode CLI, desktop app, and mobile clients through Valar by editing ~/.opencode/opencode.jsonc

ValarCode routes [opencode](https://opencode.ai) through Valar by editing its `opencode.jsonc`. opencode keeps speaking the Anthropic Messages API and you keep picking your model; the gateway maps whatever it sends to the target your routing resolves to. See [Set up ValarCode](/valarcode/setup) for the shared setup and the client-id model.

One command covers every way opencode runs — the terminal UI, the desktop app, and a phone driving a session over `opencode serve` — because all three read the same config file. There is nothing extra to enable per surface.

## Prerequisites

* opencode installed, by any method — the install script, Homebrew (`brew install opencode`), or the desktop app (`brew install --cask opencode-desktop`).
* A Valar coding key (`vlrcode_…`) and the `valar` CLI ([install](/valarcode/setup#install-the-cli)).

## Enable routing

Run once per machine:

```bash theme={"system"}
valar opencode on --api-key <your-coding-key>
```

The routing lives entirely in `opencode.jsonc`, so a new opencode session picks it up on start with no env var, shell-rc edit, or new-terminal step. Check the state any time:

```bash theme={"system"}
valar opencode status
```

<Note>
  **Restart opencode to apply a change.** opencode reads its config once when it starts and caches it for the life of the process. If you run `valar opencode on` or `off` while the terminal UI, the desktop app, or a `serve` process is already open, quit and reopen it to pick up the change.
</Note>

## What gets written

`valar opencode on` edits `~/.opencode/opencode.jsonc`. It adds a Valar provider that points at the gateway and carries your credentials, and pins both model slots to the Valar auto-router:

```jsonc theme={"system"}
{
  "provider": {
    "valar": {
      "name": "Valar",
      "options": {
        "baseURL": "https://api.valarhq.ai/v1",
        "apiKey": "vlrcode_…",
        "headers": {
          "X-Valar-Client-Id": "jdoe",
          "X-Valar-Harness": "opencode",
          "X-Valar-Cli-Version": "0.9.32"
        }
      },
      "models": { "…": "the Valar catalog" }
    }
  },
  "model": "valar/valar-auto",
  "small_model": "valar/valar-auto"
}
```

In detail, enabling:

* Adds a `valar` provider whose `baseURL` is the `/v1` surface. opencode's `@ai-sdk/anthropic` dialect appends `/messages`, so requests land on `https://api.valarhq.ai/v1/messages`.
* Puts the coding key on `options.apiKey`. In config it wins over opencode's own auth store, so there is no login conflict.
* Adds the `X-Valar-Client-Id`, `X-Valar-Harness` and `X-Valar-Cli-Version` request headers. The client-id header is omitted entirely when there is no client id, rather than written blank.
* Writes the full Valar model catalog under the provider's `models`. opencode has no public entry for these models, so what Valar writes here **is** the model picker you see in the app.
* Pins **both** `model` and `small_model` to `valar/valar-auto`. The small slot matters: left unset, opencode picks its own model for the quick "name this session" call, which would route outside Valar.

Your comments, layout, trailing commas, and any other providers pass through byte-for-byte. The original `opencode.jsonc` is snapshotted under `~/.valar/opencode/` before the first change, so `off` restores it exactly — including any edits you made while routing was on.

<Note>
  The client id defaults to your OS username, so the header reads `X-Valar-Client-Id: jdoe`. Use `--user-id RANDOM` for an opaque `vc_…` id instead. See [per-engineer attribution](/valarcode/setup#per-engineer-attribution).
</Note>

## The desktop app and mobile

The opencode desktop app and the phone clients (which drive a session over `opencode serve`) run the **same engine** as the terminal, and read the same `~/.opencode/opencode.jsonc`. So `valar opencode on` routes them too — there is no separate desktop or mobile command.

* **Desktop app** — enable routing, then open (or restart) the app. It shows the Valar models in its picker with **Valar Auto** selected.
* **Remote / mobile** — start the server with `opencode serve`, connect your phone client to it on your network, and the server's requests route through Valar. The phone never contacts Valar directly; your machine's engine does, so usage attributes to `opencode` exactly as the terminal does. For any real remote use, set `OPENCODE_SERVER_PASSWORD` — an unsecured `serve` is open to anyone on your network.

## Turn off routing

```bash theme={"system"}
valar opencode off
```

This restores the pre-enable `opencode.jsonc`. Start a new opencode session — or restart the app — to pick up the change.

## Next steps

<CardGroup cols={2}>
  <Card title="Model routing" icon="route" href="/valarcode/routing">
    How cohorts and the split decide which model serves each request.
  </Card>

  <Card title="Models" icon="microchip" href="/valarcode/models">
    The open-weight targets and the frontier Claude tiers.
  </Card>
</CardGroup>