The CLI

spawn is the control surface. The gateway is the request path; the CLI drives setup and lifecycle so wiring an agent feels like zero-config.

Install it once and the spawn command is on your PATH:

macOS / Linux

curl -fsSL https://spawn.codes/install.sh | sh

Windows (PowerShell)

irm https://spawn.codes/install.ps1 | iex

npm distribution is planned; for now the installer above is the supported way to get the spawn binary.

Getting started

Wire your agents

Point Claude Code and Codex at the gateway. This is reversible.

Terminal

spawn enable            # ride your Pro/Max or ChatGPT login (default)
spawn enable --api-keys # use your own provider API keys instead

By default spawn rides the Claude Pro/Max and ChatGPT subscriptions you already pay for, so there's nothing to bill per request. Prefer your own provider API keys? Add --api-keys. Both are first-class. See the gateway for the tradeoffs.

spawn init still works as a legacy alias for spawn enable; new setups and docs use enable.

Start the gateway

Run the proxy. It listens on localhost:8787 and writes a pidfile so stop and status can find it.

Terminal

spawn start

Use your agent as usual

Open a new shell so the wiring takes effect, then run claude or codex exactly as you normally would. spawn routes each task behind the scenes.

Commands

Command	What it does
`spawn enable [client]`	Wire an agent (`claude-code`, `codex`, or `all`) to the gateway, reversibly.
`spawn disable [client]`	Revert an agent's wiring (`claude-code`, `codex`, or `all`).
`spawn start`	Run the gateway proxy in the foreground; writes a pidfile.
`spawn stop`	Stop a running gateway.
`spawn status`	Show the gateway and per-agent wiring state.
`spawn config`	Open `~/.spawn/config.json` in your editor.
`spawn config get [path]`	Print the effective config, or the value at a dotted path.
`spawn config set <path> <value>`	Write one config value, e.g. `routing.tiers.openai.mid`.
`spawn routing show`	Print the effective routing table: tiers, rules, and the effort axis.
`spawn routing-off`	Disable routing for the current session (passthrough) until `routing-on`.
`spawn routing-on`	Re-enable routing for the current session, or every session with `--all`.
`spawn bypass-list`	Show active per-session routing bypasses.
`spawn classify <text...>`	Classify a task prompt directly with spawn-router, for debugging.
`spawn stats`	Show a routing and cost dashboard from logged request stats.
`spawn logs`	Show recent route decisions and follow `gateway.log`.
`spawn reset`	Clear stats, sessions, and the bypass registry, and reset config to defaults.

[client] defaults to all. Pass --help to any command for its options.

Useful flags

Flag	Command	Notes
`--api-keys`	`enable`	Use your own provider API keys instead of the default subscription login. See the gateway.
`--subscription`	`enable`	Explicitly select subscription auth (the default; mutually exclusive with `--api-keys`).
`-D, --daemon`	`start`	Run headless in the background (detached); logs to `gateway.log`.
`--login`	`start` / `stop`	Register (or remove) the gateway from per-OS login autostart.
`--all`	`routing-on`	Clear every active bypass entry instead of just the current session's.
`-y, --yes`	`reset`	Skip the confirmation prompt.
`--demo`	`stats`	Render a sample dataset instead of reading your real stats.
`-n, --lines <count>`	`logs`	Number of recent log lines to inspect (default `30`).
`--raw`	`logs`	Stream raw `gateway.log` without compact route formatting.
`--no-follow`	`logs`	Print the current tail and exit instead of following.

Inspecting routing

spawn status is the quickest health check. It shows whether the gateway is running, the active auth mode, and whether each agent is wired:

spawn status

gateway:     running (pid 48213)  port 8787
auth mode:   subscription
claude-code: active
codex:       active

Once you've sent some traffic, spawn stats aggregates the per-request log into a routing and cost dashboard, showing which tiers your tasks landed on, token usage, and spend. Try spawn stats --demo to see the shape of it before you have real data.

Configuration

All tunable settings live in a single JSON file at ~/.spawn/config.json, written on first enable: the per-provider tier maps and routing rules up front, plus the port, router settings, effort and confidence knobs, and the auth mode, all mergeable over code defaults. Edit that file (or use spawn config set) to change how tasks are routed.

See Configuration for the full schema with every property, and Routing for what each knob does to a decision.

To wire specific agents and the manual fallback for each, see Connect your agents.

On this page