> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weaveos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get started with Weave Router
> Connect your organization, issue router keys, and install the router in Claude Code, Codex, opencode, pi, or Cursor
Setting up the managed Weave Router takes two things: a router key issued from your Weave organization, and a one-line installer on each engineer's machine. Nothing is deployed on your side.
## Prerequisites
* An org admin to connect the organization and issue keys
* Node.js 18 or later (for `npx`), plus `bash` on macOS and Linux. On Windows, Git Bash is used when present; without it, a built-in Node.js installer handles install and `--uninstall` only (no status line, hooks, or slash commands), and the other commands need Git Bash or WSL
* `jq` for the Claude Code, opencode, and pi installs and their on/off toggles, which merge those clients' JSON configs. If it isn't on PATH, the installer downloads a checksum-verified copy to `~/.weave/bin` on macOS and Linux (x86\_64 or arm64) and Windows Git Bash (x86\_64); elsewhere, install it yourself. Codex installs don't need it
* Either prepaid [router credits](/router/billing), an active Claude or ChatGPT (Codex) subscription, or your own provider keys
## Connect your organization
Go to [Organization settings → Weave Router](https://app.workweave.ai/organization/settings/weave-router) in the Weave app. If your team doesn't use the Weave analytics product, sign in at [router.workweave.ai](https://router.workweave.ai) with GitHub, Google, or SSO and open **Settings** — it is the same configuration surface.
Click **Get started**. Weave provisions the router installation for your organization and issues your first API key. Only org admins can connect, issue, rotate, or revoke keys.
The key (`rk_…`) and the ready-to-run install commands are shown **once**, at issuance. Store the key in your password manager or secret store. If you lose it, rotate the key and re-run the installer.
Issue one key per engineer (or per environment) rather than sharing one. Keys can carry an individual spend cap, and revoking a leaked key then only affects one person.
## Install on a machine
Run the copied command, which has the key inlined. The generic forms are below — the installer prompts for the key, or reads `WEAVE_ROUTER_KEY` from the environment.
```bash theme={null}
npx @weave-os/router # opens the hosted setup page in your browser
npx @weave-os/router --claude # Claude Code
npx @weave-os/router --codex # Codex CLI
npx @weave-os/router --opencode # opencode
npx @weave-os/router --pi # pi
```
Add `--scope project` to configure the current repository instead of the machine. Add `--non-interactive` for CI and provisioning scripts (it requires `WEAVE_ROUTER_KEY`).
On npm 6 and older, the bundled `npx` mis-parses the package name. Use `npx --package @weave-os/router -y -- weave-router --claude`, or upgrade with `npm i -g npm@latest`.
### What the installer writes
Patches `~/.claude/settings.json` (or `/.claude/settings.json` for project scope) with the router base URL in `ANTHROPIC_BASE_URL`, your key in `ANTHROPIC_CUSTOM_HEADERS`, a status line, and Claude Code attribution. Your normal Anthropic login is untouched, so plan-covered turns still bill to your plan. Project scope keeps the key in the gitignored `settings.local.json` so the committed settings file carries no secret.
Adds a managed `[model_providers.weave]` block plus `model_provider = "weave"` to `~/.codex/config.toml`, between begin/end markers. Everything outside the markers is preserved. Project scope writes a gitignored `/.codex/config.toml`; run Codex from the repo with `CODEX_HOME=.codex codex`.
Merges a `provider.weave` entry into `~/.config/opencode/opencode.json` (or a gitignored `/opencode.json`). The installer makes `weave/auto` the active model and parks your previous default so `off` and uninstall can restore it; the router chooses the upstream model for each turn. Requires OpenCode 2. Your other providers and settings are left alone.
Registers a `weave` provider in `~/.pi/agent/models.json` and installs the router extension, which adds the persistent route and savings display and the `/fm` and `/ufm` model-pin commands. Project scope writes a gitignored `.pi/`; launch with `PI_CODING_AGENT_DIR=.pi pi`.
Cursor has no config file the installer owns. In **Settings → Models**, add a model named `weave-router`, enable **Override OpenAI Base URL** and set it to `https://router.workweave.ai/v1`, then paste your `rk_…` key into the **OpenAI API key** field. Cursor support is early beta.
Claude Code [Remote Control](https://code.claude.com/docs/en/remote-control) is unavailable while Claude Code uses Weave Router's custom `ANTHROPIC_BASE_URL`: it requires direct access to the Anthropic API. Your claude.ai subscription login can remain configured for ordinary routed requests, but it does not remove this restriction. To use Remote Control, turn routing off for Claude Code, fully quit and reopen it, and use your eligible claude.ai sign-in. Turn routing back on and restart Claude Code to resume routed requests. See the [scope-specific commands and troubleshooting](/router/troubleshooting#claude-code-remote-control).
## Verify the install
**Claude Code** — start a session and issue one turn. The status line shows `WEAVE ROUTER · response model: · selected: `, and adds `· est. cost difference $X` once the router can estimate the session's cost difference. `/router-status` reports whether the client is on the router.
**Codex** — confirm the `# >>> weave-router managed (do not edit between markers) >>>` block exists in your config, run a turn, and check that the provider is `Weave Router`.
**opencode** — confirm `provider.weave` exists in your config and `weave/auto` is the selected model, then run a turn.
The first routed response in a session, and any response where the serving model changes, also carries an in-band marker (`✦ Weave Router → `) unless the client suppresses it. Every decision appears in the [Router report](/router/reporting) within about an hour.
## Roll out to your team
* **Per-machine install.** Each engineer runs the installer once with their own key. That's what makes per-engineer cost and spend limits work.
* **Per-repo install.** `--scope project` in a shared repo configures the client for that repo; teammates still run the installer for their own key.
* **Set guardrails first.** Configure [spend limits and credits](/router/billing) and your [enabled models](/router/models-and-routing) before a wide rollout, so nobody discovers a model or a bill you didn't intend.
## Turn it off, or uninstall
Toggle a client between the router and its provider without discarding the config:
```bash theme={null}
npx @weave-os/router off --claude # straight to Anthropic again
npx @weave-os/router on --claude # back through the router
npx @weave-os/router status --claude # which way is it pointing?
```
Inside Claude Code, `/router-off`, `/router-on`, and `/router-status` do the same. Claude Code reads its router setting at launch, so quit and reopen it after a toggle. Codex and opencode pick it up on the next run.
To remove the router config entirely:
```bash theme={null}
npx @weave-os/router --uninstall # Claude Code, user scope
npx @weave-os/router --uninstall --codex # Codex
npx @weave-os/router --uninstall --opencode # opencode
npx @weave-os/router --uninstall --pi # pi
npx @weave-os/router --uninstall --scope project # inside the repo
```
The uninstaller removes only what the installer added. To cut off access for everyone at once, revoke the keys in router settings — the tokens stop working immediately.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.