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

# Cursor

> Route Cursor through Valar, and what the CLI writes to Cursor's settings store

ValarCode routes Cursor through Valar by pointing its OpenAI-compatible override at the gateway. Cursor keeps speaking the OpenAI Chat Completions API; the gateway maps whatever model 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

* Cursor installed and signed in, on a paid plan (Pro, Business, or Enterprise). `valar cursor on` fails on the free plan or when Cursor is not signed in.
* A Valar coding key (`vlrcode_…`) and the `valar` CLI ([install](/valarcode/setup#install-the-cli)).

## Enable routing

**Quit Cursor first**, or let valar do it for you. Cursor keeps its settings in memory and flushes them on exit, so a change written while it runs would be silently reverted. Run once per machine:

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

If Cursor is running, valar offers to quit it, apply the change, and relaunch it — pass `--force` to pre-answer that prompt, which scripts need since a non-interactive run fails rather than ask. If you quit Cursor yourself, restart it to pick up the change. Check the state any time:

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

## What gets written

Cursor stores its settings in a SQLite database, `state.vscdb`. `valar cursor on` sets:

| Key                    | Value                       |
| ---------------------- | --------------------------- |
| `openAIBaseUrl`        | `https://api.valarhq.ai/v1` |
| `useOpenAIKey`         | `true`                      |
| *(the OpenAI key row)* | `vlrcode_…~jdoe`            |
| `userAddedModels`      | adds `Valar-Coding-Auto`    |

Cursor appends `/chat/completions` to the base URL, so the endpoint is written with the `/v1` suffix. Cursor's built-in catalog is left as-is, but enabling adds a `Valar-Coding-Auto` entry to your model list, turns it on, and selects it as the active model — including in chats you already had open.

Before the first change, the touched rows are snapshotted under `~/.valar/cursor/` (keyed by a hash of the `state.vscdb` path, so separate installs never collide), and `off` restores them.

<Note>
  Cursor cannot set custom request headers, so the client id rides as a **token suffix** (`<coding-key>~<client-id>`) rather than an `X-Valar-Client-Id` header. The gateway splits on the last `~`, authenticates the base key, and routes on the id. By default the id is your OS username; use `--user-id RANDOM` for an opaque one. See [per-engineer attribution](/valarcode/setup#per-engineer-attribution).
</Note>

<Warning>
  Cursor keeps `state.vscdb` values as SQLite **TEXT** and silently discards any row whose value is a BLOB on launch. The CLI writes the values as TEXT for this reason; a raw byte write would be wiped on the next restart.
</Warning>

## Turn off routing

Quit Cursor first (or pass `--force`), then:

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

This restores the pre-enable rows. Restart Cursor 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>