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

# Codex

> Route the OpenAI Codex CLI through Valar, and what the CLI writes to ~/.codex/config.toml

ValarCode routes the OpenAI Codex CLI through Valar by editing its `config.toml`. Codex keeps speaking the OpenAI Responses 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.

## Prerequisites

* The OpenAI Codex CLI installed, with a `~/.codex` config directory. Run Codex once so the directory exists.
* 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 codex on --api-key <your-coding-key>
```

The routing lives entirely in `config.toml`, so a new Codex 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 codex status
```

## What gets written

`valar codex on` edits `~/.codex/config.toml`. It sets the root provider to Valar and adds a provider block that points at the gateway and carries your credentials in request headers:

```toml theme={"system"}
model_provider = "valar"

[model_providers.valar]
name = "Valar"
base_url = "https://api.valarhq.ai/v1"
wire_api = "responses"
experimental_bearer_token = "vlrcode_…"
http_headers = { "X-Valar-Client-Id" = "jdoe", "X-Valar-Harness" = "codex", "X-Valar-Cli-Version" = "1.4.2" }
```

In detail, enabling:

* Sets the root `model_provider` to `valar` so Codex uses the Valar provider block.
* Writes `base_url` with the `/v1` surface. Codex speaks the OpenAI Responses API (`wire_api = "responses"`) and appends `/responses`, so requests land on `https://api.valarhq.ai/v1/responses`.
* Puts the coding key on `experimental_bearer_token`, which Codex renders as `Authorization: Bearer` on the wire. It must **not** be an `Authorization` entry in `http_headers` — Codex treats that name as reserved and drops it (confirmed from codex-cli 0.145), which sends requests with no credential at all.
* 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.

Your comments, layout, and any other tables pass through byte-for-byte. The file is written user-only (`0600`), since it now holds a bearer token, and the original `config.toml` is snapshotted under `~/.valar/codex/` before the first change so `off` restores it exactly.

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

## Route a single session

To try Valar without changing anything in your Codex setup, or to run one routed session beside it, open a single Valar-routed session instead of enabling globally:

```bash theme={"system"}
valar codex on --single-session
```

This starts one `codex` pinned to its own data dir (`~/.valar/codex/session-home`), routed through Valar. Your real `~/.codex` config, and every other Codex session, stay untouched, and `valar codex status` stays `off`. Session history persists in that data dir across single-session runs.

## Turn off routing

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

This restores the pre-enable `config.toml` byte-for-byte. Start a new Codex session 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>