# Install Rauta in your editor

Agents drive your AI to models and metal you own. Attach Rauta once and your
coding agent can pick the model, rent the machine or use one of yours, deploy
it, and file a receipt for every dollar.

One remote MCP connector carries all of it. Market and advisor tools answer
from live measured data before you sign in. Account tools (spend, keys,
routing, compute) work on the same URL once you have an account.

Already on `infra-arena` / `infra-arena-gateway` MCP names or `npx infra-arena`?
Rename editor config keys to `rauta-gateway` (and prefer `npx rauta-ai`).
Legacy `*.infra-arena.ai` hosts stay until **2026-08-10** then detach (no 301).
Copy-paste: `docs/runbooks/rauta-client-migration.md`.

- MCP endpoint: `https://gateway.rauta.ai/mcp` (Streamable HTTP)
- Skill catalog: `https://rauta.ai/.well-known/skills/index.json`

There is one supported Rauta connector. Call `identify_rauta` when a session
looks disconnected or reports a missing scope. It must return
`server: rauta-gateway`, `status: active`, and the canonical URL above. A tool
whose prefix starts `mcp__claude_ai_Rauta__` came from the deprecated connector,
not Rauta Gateway. Remove that old connector rather than authorizing it again.

Account tools need OAuth, the `signup` tool on the same server, or -- best --
`npx rauta-ai init`, which does sign-in and setup in one command and never
shows anyone a key.

## Guardrail for the agent

Never assert a GPU price, benchmark score, latency, or availability from
training data. Call a tool. Surface real failure rates rather than hiding
providers. Return a recommendation with specific numbers and caveats, not a
dump. Before any provisioning spend, show the price and get explicit user
approval.

## Claude Code

```
npx rauta-ai init
npx rauta-ai mcp install
```

Claude Code must be installed and signed in (`claude auth login`) before this.
Rauta routes and meters the claude.ai credential the user already has, so `init`
refuses with `claude code not logged in` when it cannot find one. Check that
first rather than sending someone into a command that will stop.

`init` signs you in and wires the editor. Open a new terminal after it: the
gateway URL is a shell export, so an already-open shell never picks it up.

`mcp install` registers the connector. Then run `/mcp` inside Claude Code and
authorize it. Registering is not authorizing: `claude mcp add` never runs OAuth,
so until you approve, the server connects and serves only the anonymous market
tools. That state looks broken and is not.

Check any time with `npx rauta-ai doctor`. If gateway routing ever blocks Claude,
`npx rauta-ai recover` parks routing, keeps Claude direct available in a new
terminal, and offers to send redacted diagnostics. Pause normally with
`rauta-ai off` / `on`; remove with `rauta-ai disconnect`.

Raw equivalent, if you would rather not use the CLI:

```
claude mcp add --transport http rauta-gateway https://gateway.rauta.ai/mcp
```

Optional skill (adds the workflow), and the plugin, whose npm name is still the
pre-rename one:

```
npx skills add https://rauta.ai
claude plugin marketplace add rauta-labs/rauta && claude plugin install infra-arena
```

## Claude app (desktop and claude.ai)

Settings, then Connectors, then Add custom connector:

```
https://gateway.rauta.ai/mcp
```

Approve in the browser window that opens. The app pins its own model calls to
Anthropic, so Rauta gives you tools there, not routing. Routing lives in Claude
Code. Hosts cache the tool list at handshake, so after any change to your
connector, disconnect and reconnect before expecting new tools. Keep only the
connector named Rauta Gateway at `https://gateway.rauta.ai/mcp`; remove an older
connector named Rauta that points at `mcp.rauta.ai`.

## Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "rauta-gateway": {
      "url": "https://gateway.rauta.ai/mcp"
    }
  }
}
```

Or one-click deeplink:
`cursor://anysphere.cursor-deeplink/mcp/install?name=rauta-gateway&config=eyJ1cmwiOiJodHRwczovL2dhdGV3YXkucmF1dGEuYWkvbWNwIn0=`

## Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.rauta-gateway]
url = "https://gateway.rauta.ai/mcp"
```

## Private Coverage

For entitled accounts, the signed Coverage companion captures each endpoint
independently: Claude Code, Codex, Cursor and Grok Build. Grok's agent-facing
entry is `connect_grok_coverage`; use its single-use pairing command rather
than passing a key in chat. Hooks belong in `~/.grok/settings.json`, never the
Claude settings file. Reasoning blocks are excluded by the shared capture
policy. Reported usage is not a count of unique training tokens.

`rauta-ai coverage status` reports local capture state. A recent successful sync
does not certify historical completeness. Corpus reads require the separate
internal job-authenticated reader documented in `cli/README.md`; the installed
Coverage launcher cannot read with its upload-only credential. Offline release
does not start training.
`rauta-ai coverage corpus release --dir PATH --bundle` produces one
`.corpus.tar` for the existing training-data upload flow. The pretraining
reader verifies its tenant, artifacts and three frozen splits; do not upload
an individual manifest or shard as training text.

## Skills only (any agent)

```
npx skills add https://rauta.ai
```

Writes every skill in the catalog -- `infra-advisor`, `rauta-gateway`,
`training`, `org-admin`, `spend-economics`, `ops` -- into `.claude/skills/`
(Claude Code) and the shared `.agents/skills/` (Cursor + Codex). Full list:
`https://rauta.ai/.well-known/skills/index.json`.

Rauta never overwrites installed skill files in the background. Check for a
new catalog with `npx skills check`, review your local edits, then run
`npx skills update` when you choose. Keep personal instructions in a separate
local companion skill so an explicit upstream update cannot replace them.

## Account (sign up from the terminal)

Market tools need no account. To rent compute, bring your own provider keys
(BYOK), or track spend:

```
npx rauta-ai init
```

Email, a one-time code, one click in the browser. The command wires your editor
and then verifies it really routes before telling you it worked. Nothing to
paste, no key to keep.

Already have an account? Run the same command -- it is idempotent, and it is the
repair path too.

(`rauta-ai` is the canonical npm package while unscoped `rauta` awaits npm
clearance. Package `infra-arena` is frozen and no longer updated.)

Or call the gateway MCP `signup` tool after the connector is attached. The web
dashboard (spend, keys, billing) lives at `https://gateway.rauta.ai/login`.

### Connect Claude Code (subscription users on Max or Pro)

Call the gateway MCP's `connect_claude_code` tool from inside any Claude
Code chat. **One command**, `npx rauta-ai init`, signs you in, wires the
editor and verifies it actually routes before saying it worked. No key is ever
shown, pasted, or written into `settings.json` by hand. Open a new terminal
afterwards (the gateway URL is a shell export, so an already-open shell never
picks it up) and your session routes
**through** the gateway on your own claude.ai login. Subscription billing is
unchanged; the gateway forwards your own credential untouched (the exact setup
Anthropic's gateway protocol documents). You get:

- live usage metering (`get_my_claude_usage`: 5-hour/7-day windows, burn
  rate, calibrated limit ceilings) and spend-dashboard facts;
- rate-limit hits captured at the wire, with `suggest_overflow` offering a
  fallback model (advisory only) the moment you're blocked;
- Rauta-routable models as native `/model` picker entries labeled "From
  gateway". Click one and it routes through Rauta on your own provider key.

The picker is a live composition, not a fixed CLI list: your own additions are
preserved, your company administrator may narrow the company menu, and Rauta
may append a centrally recommended model while the composed menu has fewer
than 100 entries. Recommendations never override company or personal policy
and can be withdrawn centrally without a CLI release.

To pull the current catalog, call the MCP tool `refresh_model_picker`, then run
the one-line command it returns (`npx -y rauta-ai@latest models prepare`) in the
current project. `prepare` preserves a custom status line; otherwise it adds
a Rauta model-readiness line that refreshes every three seconds. It also updates
Rauta's old one-second default, whose request budget could expire before a normal
readiness response arrived; other custom intervals are preserved. Missing or
stale lifecycle telemetry stays unknown rather than claiming the worker is ready.
If the status request fails, the line says `telemetry unavailable; readiness
unconfirmed`. This does not mean the GPU has stopped or that billing has ended.
Claude Code does not hot-reload this picker cache. Follow the printed `/exit`
and resume command. When Rauta can identify one fresh active gateway session
and its model is still advertised, the command includes `--model <selected-id>`
to keep that selection. Claude Code 2.1.257 can otherwise reset an unfamiliar
saved model to its default on resume. With multiple active sessions or a
withdrawn model, choose the conversation and model explicitly; Rauta does not
guess. `tools/list_changed` refreshes MCP tools only, not model discovery.

Refreshing the catalog and stopping compute preserve saved model defaults.
In Claude's native picker, `s` selects for this session only; Enter saves a
default for future sessions. That is a separate client choice, not a Rauta
refresh action. A startup-budget refusal means no new worker was scheduled;
it is not evidence that the displayed budget was actually charged or that a
worker is warming. The notice names any different model that answered the turn.

Already have the MCP connected? `connect_claude_code` hands back a single-use
pairing code and the same one command. It never returns a key.

Prefer not to change your base URL? `connect_claude_code {"mode": "telemetry"}`
does metering only, via Claude Code's OpenTelemetry export.

Check it any time with `rauta-ai doctor`, pause it reversibly with
`rauta-ai off` / `rauta-ai on`, and remove it with `rauta-ai disconnect`, which
asks first, backs up every file it touches, and leaves your account, credits and
keys alone. If routing itself is preventing Claude from working, use
`rauta-ai recover`: it verifies routing is parked before reporting success and
can send a redacted client/provider incident bundle without conversation text.

When a Rauta model is selected, stop its billable GPU immediately with:

```
rauta-ai models stop
```

Escape cancels only the current Claude request. Before allocation, Rauta revokes
that launch. After allocation, the response says how long the same-generation
worker remains warm. Escape never silently claims that compute or billing ended.

The stop command asks for confirmation, resolves the current model without exposing
a provider job ID, and returns both Rauta's generation-fence receipt and an
independent provider-absence receipt. In scripts, use
`rauta-ai models stop --yes`. If the stopped model is serving the current Claude
Code process, the command preserves all saved defaults and prints an
optional `/exit` + `claude --resume … --model sonnet` path for that conversation.
This launch flag does not edit the saved default. Do not send another turn
from the old process: Claude Code keeps its selected model in memory, and doing
so could wake a new worker after the five-minute stop fence expires. The stop
fence is recorded even when the model is already cold, so a queued request
cannot start billing immediately after the stop check. Teardown confirmation
is separate from this fence: if provider deletion fails, retry the stop command
and do not assume that billing ended.

Agents can use the same generation-bound contract through the gateway MCP tool
`stop_model_compute`: call `prepare`, show the exact model and generation to the
user, then pass the returned short-lived confirmation token to `commit`. A stale
token cannot stop a replacement generation. Success says `Compute off by request.`
and includes both receipts; an uncertain provider read leaves billing status
explicitly unconfirmed.

### Rauta Box: route turns to the user's own hardware

If the user asks to run models on their **own machine** (a Mac, a GPU box, a
homelab server, anything that can run an OpenAI-compatible server like vLLM,
Ollama, TGI, or mlx_lm), onboard it as a first-class routing target from this
same gateway MCP. No dashboard visit, no tokens in chat:

1. **Size the hardware.** Detect it yourself (`sysctl -n hw.memsize` +
   `uname -m` on macOS; `/proc/meminfo` + `nvidia-smi` on Linux), then call
   `plan_box_setup` with `ram_gb`, `accel`, and what you know about the user's
   work. It returns which models physically fit; you pick the right one.
2. **Register and get a pairing code.** Call `add_own_hardware` with a name,
   the capex (for honest amortized metering; box turns are metered at
   `capex/(months×730) + power`, never fake "free"), and
   `enable_local_first: true` to prefer the box on exact-model matches. With
   the default `auth: "bearer"` it returns a **single-use pairing code** and a
   one-line command:

   ```
   rauta box connect <pairing-code>
   ```

   The user runs that on the box. The box claims its token out-of-band,
   installs an auth-enforcing proxy, and self-registers, and the gateway then
   *measures* that the box rejects a bad token (`auth_enforced` in
   `list_own_hardware`). A bare tunnel URL without the pairing proxy is
   world-reachable; never register one with `auth: "none"` unless the tunnel
   is genuinely private (e.g. Tailscale ACLs).
3. **Confirm.** `list_own_hardware` should show the box `connected` with its
   model inventory. Exact-model requests now route local-first; if the box is
   down, cloud-burst fallback is automatic, so a request can never fail because
   the box is offline.

Manage later with `update_own_hardware` (capex/power changes take effect on
future receipts immediately) and `remove_own_hardware` (dry-run first; the
hardware keeps running, past receipts are kept).

## Compatibility (existing installs only)

Older installs that still point at `https://mcp.rauta.ai/mcp` keep working.
That host is not removed and does not redirect. New installs should use
`https://gateway.rauta.ai/mcp` only (it already includes the market tools).
If both servers are attached, ask before removing the old one; duplicate tool
names make selection ambiguous.

## Tools

| Tool | Use it for |
| --- | --- |
| `list_gpus` | Browse / filter the live GPU market (price, region, availability). |
| `lookup_model` | Param count, context window, VRAM at fp16/int8/int4, fitting GPUs. |
| `recommend_workload` | "What should I run X on": VRAM-aware, price-ranked shortlist. |
| `leaderboard` | Fastest / cheapest by category (cloud / hardware / inference). |
| `cold_start_stats` | Real provisioning p50/p95 + failure rates per provider+GPU. |
| `compare_providers` | Cross-provider TTFT / latency / availability over time. |
| `ask_advisor` | Rauta's own prose recommendation (may cold-start ~2 min). |

Full reference: [tools.md](https://rauta.ai/.well-known/skills/infra-advisor/references/tools.md).
Data model + honesty principles: [data-model.md](https://rauta.ai/.well-known/skills/infra-advisor/references/data-model.md).
# Startup telemetry distinguishes elapsed time from freshness

When the provider exposes runtime logs, the model status line reports real
weight-loading counts and compilation milestones. “Startup” is total elapsed
time; “last update” is the age of the latest observed milestone, not a readiness
guarantee. Unsupported or unavailable telemetry stays explicitly unknown.
During a missed update, a recent known milestone remains visible with its
original timestamp and increasing age. It does not reset the startup clock or
mean the worker is ready. Status reads share a diagnostic polling budget;
opening more terminals does not grant more frequent direct-Pod polling.

Coverage internal preview preserves captured history. `rauta-ai coverage config content off`
pauses content capture for every adapter on this machine without changing metadata or
account-wide training permission. `rauta-ai coverage uninstall <client>` removes that
adapter's hooks and scheduler while retaining history, pending uploads and recovery state.
Per-client pause is not an account-wide consent change. Deletion (`--purge` or `prune --yes`)
is unavailable during internal preview; no automatic retention or cleanup is enabled.