Gateway keys and connect

Add upstream provider keys to the local gateway's rotation ring, then point agent CLIs at it.

Goal#

Give orch's local gateway upstream provider API keys (with automatic failover on rate limits), then connect agent CLIs — OpenCode, Command Code, plain OpenAI-compat tools, or Claude Code — to route their model traffic through it.

Steps#

  1. Add a key to a provider's rotation ring:

    orch gateway keys add openai sk-...

    Omit the key to be prompted for it. The key is probed against the provider before being saved — a failed probe prints why and saves nothing. Keys live in the machine-home vault (keys.env), one env var per provider; several comma-separated keys form a ring the gateway already knows how to rotate through on 429s.

  2. List configured keys (hints only — a full key is never printed):

    orch gateway keys list [provider]

    Prints <provider> tier=<tier> keys=<n> <hints...>.

  3. Remove a key by its hint:

    orch gateway keys remove openai sk-…abcd

  4. Start the gateway:

    orch gateway

  5. Connect an agent to it:

    orch gateway connect opencode      # writes ~/.config/opencode/opencode.json automatically
orch gateway connect commandcode   # prints env for Command Code
orch gateway connect openai        # prints env + an OpenCode config snippet
orch gateway connect claude        # prints Anthropic env vars

    OpenCode is the one target orch edits for you; the others print ORCH_GATEWAY_BASE / ORCH_GATEWAY_KEY (and, for openai/claude, the matching OPENAI_* / ANTHROPIC_* variables) for you to export or paste into the tool's settings.

Plan-billed seats keep their login#

If a preset's agents.auth is account (the default for codex, cursor, and claude without a passthrough key — see configure-agents.md), orch gateway connect only prints ORCH_GATEWAY_* and a warning:

# warning: claude keeps its own plan login; orch injects only ORCH_GATEWAY_*;
# set agents.auth.claude: gateway to route model traffic through orch

Provider env vars are withheld on purpose — printing OPENAI_API_KEY or ANTHROPIC_AUTH_TOKEN on top of a plan login would silently replace that login and drop its connectors. Set agents.auth.<preset>: gateway explicitly first if that's what you want.

Verify#

orch gateway status

Reads /v1/providers/stats from the running gateway: per-provider live/cooldown state, key-ring position (2/3), rotation and cooldown counts since the gateway started. Counters reset on gateway restart — for a historical record use orch gateway usage / orch usage.

Undo#

orch gateway keys remove <provider> <hint>

To stop routing an agent through the gateway, unset its agents.auth.<preset> (or set it to account) and re-export the CLI's own login/env.

  • configure-agents.md — agents.auth and agents.transport per preset.
  • troubleshooting.md — orch usage and plan-seat token accounting.