The gateway

The gateway is the request path. It's a local reverse proxy that speaks the providers' own API wire formats, so any agent that lets you override its model endpoint can sit behind it transparently. Your agent talks to localhost; the gateway classifies, routes, and forwards upstream.

Wire formats

The gateway speaks the two formats coding agents use, which is what lets it wrap them without any change to the agent:

• Anthropic Messages API, for Claude Code.
• OpenAI / Responses API, for Codex (CLI and Desktop).

An agent is wired by pointing its endpoint override at the gateway: ANTHROPIC_BASE_URL for Claude Code, or a custom model_provider in ~/.codex/config.toml for Codex. See Connect your agents for the per-agent setup.

What the gateway does

For each request the gateway:

• Classifies the task with the local router (see Routing).
• Selects a provider, model tier, and reasoning effort from your policy.
• Forwards the request upstream, rewriting the model and streaming the response back unchanged.
• Logs per-request stats (model, tier, token usage, cost) that power the spawn stats dashboard.

agent  ↔  spawn gateway (localhost:8787)  ↔  provider API
            ├─ router (local ONNX classifier)
            ├─ policy (prediction → provider + tier + effort)
            └─ forwarder (your credentials, upstream wire format)

Authentication

The endpoint override works at the transport layer and is auth-agnostic: the gateway forwards whatever credentials your agent already sends. That gives you two first-class modes; pick whichever fits, on either provider.

• Subscription (default). Plain spawn enable rides your agent's own login. This forwards a Claude Pro/Max session to Anthropic, or a ChatGPT session to the Codex backend, so your tasks run against the flat-rate plan you already pay for. This is the rate-limit win: no metered API spend, and routing still happens behind the scenes.
• API key. Run spawn enable --api-keys to use your agent's own key (ANTHROPIC_API_KEY or OPENAI_API_KEY) instead. It flows straight through to the standard provider API. The gateway never touches it; your key pays. Best when you want per-request metering or are already on usage-based billing.

Both modes carry open weights, your own credentials, and multiple providers. spawn enable records your choice as auth.mode in the config; switch any time by re-running enable with --subscription or --api-keys.

Configuration

The gateway reads a single JSON config file at ~/.spawn/config.json, written on first spawn enable. It holds the per-provider tier maps and routing rules up front, plus the port, router settings, effort and confidence knobs, and the auth mode underneath as overridable defaults. Everything the policy reads is in that one file, so the routing decisions are entirely yours to tune. See Configuration for the full schema and an example.