How it works
How a task travels from your agent through the spawn gateway to a routed model streaming back.
spawn is a local reverse proxy. Your agent thinks it's talking to its normal provider; in reality it's talking to spawn on localhost. spawn classifies the task, decides which model should handle it, and forwards the request upstream with your own credentials. The response streams straight back, so nothing about your agent's behaviour changes except which model answers.
The request path
your agent (Claude Code / Codex / Codex Desktop)
│ base-URL override → http://localhost:8787
▼
spawn gateway
├─ classify spawn-router reads the task (local ONNX, ~10–50ms, once at kickoff)
├─ route policy maps prediction → provider + model tier + effort
└─ forward upstream with your own credentials
▼
provider API (Anthropic Messages / OpenAI Responses)
│ response streams back unchanged
▼
your agentBecause spawn speaks the providers' own wire formats, no part of your agent has to know it's there. The only change is a one-time endpoint override, which the spawn enable command sets up for you (see Connect your agents).
The lifecycle of a task
You prompt your agent as you normally would. The request leaves the agent pointed at spawn instead of the provider.
spawn classifies the task once at kickoff, reading its type, complexity, and risk using the local router. Classification is fast and runs on CPU, so it doesn't bottleneck the request.
The policy picks a model. The classification maps through a policy you control to a concrete provider, model tier, and reasoning effort.
spawn forwards the request upstream with your own credentials, then streams the response back to your agent unchanged.
Classify once, not per turn
The router runs once, at the start of a task, and the model it picks is locked for the whole task. spawn deliberately does not reclassify on every turn:
- No routing thrash. Switching models mid-task corrupts context and reasoning continuity. One task, one model, start to finish.
- It nudges a better habit. Rather than piling unrelated asks into one bloated session, start a fresh task instead. It gets a correctly-routed model and a clean context window; a continuation stays on the model already chosen.
For how the router decides, see Routing. For the wire formats and how credentials are forwarded, see the gateway.