Use RouteKit Cloud from a coding agent

This is the direct Cloud gateway path. It does not start or require a local RouteKit daemon. The local routekit codex and routekit claude launchers use your local gateway by default; routekit remote manages a separate SSH-backed gateway. Cloud provider Sources supply model capacity, while routekit cloud install configures a client that consumes it. Cloud sidekick delegation is a separate, gated MCP workflow, not part of this install.

Sign in and check capacity

routekit cloud login
routekit cloud account list

Login defaults to production at https://cloud.velum-labs.com, even if a previous login selected staging. For staging or a self-hosted Cloud instance, pass its origin explicitly with routekit cloud login --url <cloud-origin>.

Approve the device code in your browser for the intended organization. Cloud login is a CLI OAuth session. Installation creates a separate user API key bound to that organization; the native agent retrieves it from RouteKit's private local secret store through a credential helper. Do not paste either credential into the agent's settings or a chat.

An organization administrator can connect API-provider Sources in Cloud. A Vercel AI Gateway connection can begin in Sources and finish with routekit cloud source connect using the official Vercel CLI; that setup is separate from native-client installation. See the source connection steps. You can also enroll a new Codex or Claude Code subscription privately and then explicitly share a healthy account with the organization:

routekit cloud account login codex --name personal
routekit cloud account show codex --name personal --refresh
routekit cloud account pool codex --name personal

This does not copy the official client's existing login. Private enrollment alone does not add that subscription to the shared inference pool. A model request can consume the organization's provider allowance or billable API capacity; setup and authenticated model listing do not make an inference call. You do not need to enroll your own subscription if the organization already has an eligible Source.

Install a native client

The commands below install an unbound Cloud client. They do not infer a repository from your current working directory:

routekit cloud install --agent codex
codex --profile routekit-cloud

Codex's Cloud profile is separate from its local routekit profile. To select a published compositional activation for a particular repository at startup, use its exact advertised model ID:

routekit cloud install --agent codex --default-model auto:owner/repository

The install fails if that model is absent from the authenticated Cloud catalog. If the catalog cannot confirm any Codex-compatible startup model, installation requires an explicit --default-model selection. An advertised but compatibility-unknown model is an explicit choice, not a guarantee of a working Responses turn; verify it with your account before relying on it. Installation does not invent or publish a routing activation. For Claude Code:

routekit cloud install --agent claude
claude

Claude Code's default settings directory can point to one gateway helper and base URL at a time. If a local RouteKit integration or another gateway already owns those settings, use a separate configuration directory instead:

routekit cloud install --agent claude \
  --claude-config-dir "$HOME/.config/routekit/claude-cloud"
CLAUDE_CONFIG_DIR="$HOME/.config/routekit/claude-cloud" claude

That isolated directory also isolates Claude's other settings and history. Launch with the same CLAUDE_CONFIG_DIR each time. Both cloud install and cloud sync refuse Claude configuration if ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY is set in the invoking process or configured in Claude settings: Claude Code gives those variables precedence over apiKeyHelper. Ensure they are also unset when launching Claude Code, which may happen from a different shell or supervisor. The error identifies variable names, never their values; do not put credentials in native settings. Cloud installation is intentionally refused against deployment-protected staging because native inference does not forward the protection credential.

Bind a repository policy to an isolated client

Use this path when you want the repository's bare auto policy, rather than a published auto:owner/repository activation. Before installing:

1. Sign in to the intended Cloud organization and confirm it has a healthy provider Source for the candidate models. You need organization access to the repository connection, and the connection must retain repository coverage.
2. Ask an owner or administrator to enable the organization's routing product flag and an active commercial entitlement with the routingAuto capability and routing.request meter. On Routing, enable this repository's policy with eligible candidates. The policy is initially disabled.
3. Open that repository's Routing page and copy the repository connection UUID from its URL. This is not a GitHub owner/repository name and is not an API key.

Use a separate Codex home so an existing Codex profile is untouched:

export CODEX_HOME="$HOME/.config/routekit/codex-cloud-repository"
routekit cloud install --agent codex \
  --codex-home "$CODEX_HOME" \
  --repository-connection-id "<repository-connection-uuid>"
codex --profile routekit-cloud

The installer requires Cloud to advertise bare auto from authenticated model discovery with that connection selected. It configures the managed provider's repository header and Codex's startup model as bare auto. If discovery lacks auto, fix connection coverage, policy, flag, or entitlement instead of treating a reachable catalog as proof of routing.

For Claude Code, use version 2.1.227 or newer and an isolated configuration directory if another integration owns your default settings:

routekit cloud install --agent claude \
  --claude-config-dir "$HOME/.config/routekit/claude-cloud-repository" \
  --repository-connection-id "<repository-connection-uuid>"
CLAUDE_CONFIG_DIR="$HOME/.config/routekit/claude-cloud-repository" claude

The bound installer configures ANTHROPIC_CUSTOM_MODEL_OPTION so anthropic.routekit.auto appears in Claude Code's /model picker; select it for the policy. This Claude-compatible name reaches the same repository-policy auto route, not a separate policy. A detected older Claude Code is rejected. If claude is not installed when you configure the integration, installation can only warn; install a compatible version before launching. Launch from a terminal with the same CLAUDE_CONFIG_DIR each time, and keep ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY unset. Desktop, remote, and separately supervised launches may not inherit this terminal environment and are not covered by this example. Neither agent stores its API key in native settings. The connection UUID is a selector, not authorization: Cloud still checks the authenticated organization's access and current coverage.

Understand the two automatic routes

• auto:owner/repository is a published compositional activation. When present in the Cloud catalog, choose that model in the native picker or as Codex's --default-model.
• Bare auto is a different repository policy. It requires the X-RouteKit-Repository-Connection-Id request header and an enabled, covered, commercially authorized policy. A bound cloud install configures that header explicitly; an unbound install does not infer a repository or silently choose this route.

The repository selector is not authorization: Cloud verifies organization coverage. For bare auto, Cloud also verifies the active policy, flag, entitlement, and budget. An explicit provider/model selected in a bound client carries the same repository context but does not invoke the policy or consume its routing.request meter. Explicit inference may still incur provider usage. auto:owner/repository cannot be combined with the repository header. Without an eligible automatic route, use an unbound client or repair the repository policy rather than expecting fallback.

Inspect, refresh, and disconnect

routekit cloud status
routekit cloud sync --agent codex --codex-home "$CODEX_HOME"
routekit cloud sync --agent claude \
  --claude-config-dir "$HOME/.config/routekit/claude-cloud-repository"
routekit cloud logout

cloud status checks stored login presence, installed configuration and key presence, authenticated model discovery for each installed agent, pending key revocations, and retired local credential cleanups. A pending local cleanup means a prior private key may remain on disk; the next Cloud login, install, or logout retries its removal. A reachable catalog does not prove an inference or streaming turn. For a bound agent, status reports its connection and distinguishes a missing key, native configuration drift, unreachable catalog, unavailable connection, and policy auto not being advertised. cloud sync preserves the saved repository binding, refreshes the installed picker and helper path without minting or rotating a key, and refuses a different connection ID. For an unbound Codex installation, sync requires --default-model <catalog-model> so its startup selection cannot change by accident; a bound Codex sync preserves auto without that flag. Use the matching --codex-home or --claude-config-dir again for a nondefault installation.

To deliberately rebind or return to an unbound installation, replace the specific agent installation explicitly:

routekit cloud install --agent codex --codex-home "$CODEX_HOME" \
  --replace --repository-connection-id "<new-repository-connection-uuid>"
routekit cloud install --agent codex --codex-home "$CODEX_HOME" \
  --replace --clear-repository-binding

For Claude Code, use --agent claude with the same --claude-config-dir. Plain --replace keeps the existing binding; it does not silently unbind. Sync and replacement do not change another isolated home or directory. Check status after either operation.

To verify actual routing, first confirm that a paid provider request and any repository content sent with it are authorized. Send one small native-client turn through each bound Cloud configuration, then match its time or request ID, repository connection, selected model, reasoning effort, status, and usage in Cloud Requests. If routing annotations are enabled, confirm that the notice agrees with the recorded selection; if annotations are off, no notice is expected. Also test an explicit model under the bound configuration to confirm it bypasses policy selection. A successful install or model listing alone is not that end-to-end proof.

Claude Code may ask Cloud to count tokens before a turn. For a bound auto request, Cloud returns a model-independent local approximation (using an eligible policy candidate for catalog validation); this does not choose the inference model, invoke the routing evaluator, consume routing.request, or call a provider. Do not treat token-count success as routing proof.

cloud logout removes registered agent configurations and the CLI login, then attempts remote key revocation. A network or authorization failure can leave a revocation pending; the key may remain valid until you sign in again to retry or revoke it in Cloud's API Keys page. Separately installed Cloud sidekick MCP configuration has its own lifecycle. cloud logout does not uninstall that MCP entry.

Cloud attempts to record request metadata for attribution. Prompt and response content capture is a separate, opt-in organization setting; check your organization's privacy policy before sending repository material.

Cloud sidekick is a different, gated workflow

routekit sidekick install --mode cloud adds an MCP server to an already configured Codex or Claude Code lead. It does not change the lead's model provider, install the hosted gateway above, enroll a Source, or start a local daemon. The host session is bound to one checkout, GitHub repository, Cloud origin, organization membership, and explicit lead model. A successful installation or sidekick status confirms native configuration, not that Cloud delegation is admitted or that paid work can run.

Cloud Fusion currently requires an approved Vercel staging custom environment, a healthy cloud-fusion feature-flag decision, deployment opt-in, and separately enabled admission. Production and ordinary Preview do not satisfy that boundary. Only an authorized qualification should use the Cloud sidekick commands; do not turn on admission or submit work just to verify an installation.

For an approved environment, the installation shape is:

routekit sidekick install --tool codex --mode cloud \
  --cloud-url <approved-cloud-origin> \
  --organization-id <verified-organization-id> \
  --lead-model <actual-native-lead-model>
routekit sidekick status

Use --tool claude for Claude Code. Inspect the bound session with routekit sidekick session --tool codex --json; inspect a returned patch with routekit sidekick preview --tool codex --delegation-id <id> --json. A model cannot approve its own patch. Human review requires the exact previewed generation and digest plus routekit sidekick review --approve; an ambiguous admission is recovered only against its saved operation ID and budget with routekit sidekick recover --approve. Neither installation nor result retrieval auto-applies a patch.

routekit sidekick uninstall --tool codex removes the managed MCP entry. It is separate from routekit cloud logout; do not mistake native installation status for current authentication, admission, or durable delegation state.