Quickstart
Five steps from a built clone to a routed chat completion: write the smallest config the loader will accept, validate it, start the router, and send one request. Everything here runs on loopback.
Before you start
This page assumes you have already done Install: a clone of the
private repository, built, with dist/switchback-cli.js on disk. Every command
below is run from the root of that clone.
You also need a real API key for a provider you have an account with. Every request in
this guide goes to a live upstream and bills your provider account; nothing here is a dry
run. To exercise a route config without a key or a network, replay a request against
fixtures with the sim subcommand instead.
Warning
Run dist/switchback-cli.js, not the
dist/switchback-cli.cjs twin next to it. The CJS artifact is not recognised
by the self-run guard, so it loads, prints nothing, and exits 0, which looks exactly
like a silent hang.
1. Write the smallest config that loads
Save this as switchback.config.json in the clone root. That filename is the
CLI default, so you can drop --config once it is in place. The flag is
spelled out below anyway, because being explicit is cheap.
{
"route": {
"listen": { "host": "127.0.0.1", "port": 4011 },
"upstreams": {
"openai-direct": {
"baseURL": "https://api.openai.com/v1",
"dialect": "openai-compat",
"profile": "openai",
"auth": { "env": "OPENAI_API_KEY" }
}
},
"models": {
"gpt-4o": { "openai-direct": "gpt-4o" }
},
"routes": {
"chat-default": {
"match": {},
"chain": ["gpt-4o"],
"policy": { "advanceOn": ["rate_limited", "server_error"] }
}
}
}
}
That is not an abridged example. It is the floor. Four things are mandatory:
The router reads exactly one top-level key. A file without route is not
a partial config: the loader returns nothing and the CLI exits 1.
There is no default port, and omitting the whole listen block is a hard
error. listen.host does default to 127.0.0.1; a
non-loopback host is honored but logs a warning naming the exposure.
Each upstream needs a baseURL and a dialect. Its
credential is a reference, either { "env": "VAR" } or
{ "file": "path" }, never an inline value. route.models,
by contrast, is optional.
Every route needs a policy, and every policy needs an
advanceOn array, the failure classes that move the chain to its next
candidate. An empty array is a valid answer ("never advance"); a missing key is not.
match: {} makes this route the catch-all, and chain holds a
single candidate, so there is nothing to fail over to yet. That is deliberate: get one leg
working, then read Routing to add the second.
2. Set the key, then validate
The variable named by auth.env is read once, at load. Export it first, then
let the CLI tell you whether the file is sound before you try to serve traffic.
$ export OPENAI_API_KEY=your-openai-api-key
$ node dist/switchback-cli.js config check --config switchback.config.json
A sound config prints one line and exits 0:
Config check passed: /abs/path/switchback.config.json is valid and all referenced env vars are set.
Danger
your-openai-api-key above is a placeholder. Substitute your own key at the
shell and keep it out of the config file, out of your shell history, and out of version
control. The config grammar enforces half of this for you: an inline secret, a
credential-shaped header value, or userinfo embedded in a baseURL is
refused at load rather than quietly accepted.
3. Start the router
$ node dist/switchback-cli.js --config switchback.config.json
Three lines, in this order, and then it is listening:
[switchback] EXPERIMENTAL: the self-hosted router is under active development; config shape and behavior may change without notice (§13.9).
[switchback] auth: default mode — keys held in memory; SIGHUP re-reads keys from env
[switchback] router listening on http://127.0.0.1:4011
The experimental notice is printed on every start, and it means what it says: treat the
config shape as unstable. The second line is the key posture: credentials live in this
process's memory only, and SIGHUP re-reads them from the environment without
a restart.
4. Send the first request
The OpenAI Chat Completions surface is /v1/chat/completions. Leave the router
running and use a second terminal.
$ curl -i http://127.0.0.1:4011/v1/chat/completions \
-H 'content-type: application/json' \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}]}'
A success is a normal Chat Completions body plus four x-switchback-* headers
that say who served it and how many attempts it took:
HTTP/1.1 200 OK
content-type: application/json
x-switchback-upstream: stub
x-switchback-dialect: openai-compat
x-switchback-attempts: 1
x-switchback-budget-remaining: global=4.999977
{"id":"chatcmpl-x","object":"chat.completion","created":1,"model":"gpt-4o","choices":[{"index":0,"message":{"role":"assistant","content":"pong"},"finish_reason":"stop","native_finish_reason":"stop"}],"usage":{"prompt_tokens":5,"completion_tokens":1,"total_tokens":6},"provider":"openai"}
Note
That transcript was captured against a local stub upstream named stub,
standing in for OpenAI, with a global dollar cap configured. With the config on this
page you will see x-switchback-upstream: openai-direct, real token counts,
and a real completion. The x-switchback-budget-remaining line reports what
is left under a configured cap (see Budgets), and
Observability covers the header set in full.
The OpenRouter-shaped surface
The same request sent to /api/v1/chat/completions comes back in the
OpenRouter envelope instead: a gen- id, reasoning on each
choice, and system_fingerprint / service_tier present as nulls.
Same bytes from the upstream, one post-pass.
{"id":"gen-x","object":"chat.completion",...,"choices":[{"index":0,"message":{"role":"assistant","content":"pong","reasoning":null},"finish_reason":"stop","native_finish_reason":"stop"}],...,"provider":"openai","system_fingerprint":null,"service_tier":null}
If you are pointing an existing OpenRouter client at the router, that is the surface you want; OpenRouter migration covers what else carries over.
Streaming
Add "stream": true to the body. The routing headers arrive with the SSE head,
before the first token, followed by chat.completion.chunk frames and a final
data: [DONE].
HTTP/1.1 200 OK
content-type: text/event-stream; charset=utf-8
cache-control: no-cache
connection: keep-alive
x-switchback-upstream: stub
x-switchback-dialect: openai-compat
x-switchback-attempts: 1
x-switchback-budget-remaining: global=5.000000
5. Read what it decided
Every request leaves one routing report behind, retained in memory and served at
GET /route/reports. This is the thing to reach for when a response surprises
you: it names each leg tried, its verdict, and what it cost.
$ curl -s http://127.0.0.1:4011/route/reports | jq '.reports[0]'
{
"id": "rt-e0d276c4f3ee",
"surface": "/v1/chat/completions",
"requested_model": "gpt-4o",
"candidates": ["gpt-4o"],
"legs": [{
"candidate": "gpt-4o", "upstream": "stub", "dialect": "openai-compat",
"verdict": "success", "status": 200, "connect_ms": 1,
"usage": { "prompt_tokens": 5, "completion_tokens": 1 },
"budget": { "settlement": "committed_actuals", "amount": "0.000023" },
"cost": { "amount": "0.000023", "source": "catalog" }
}],
"client": { "aborted": false, "committed_at_ms": 1 },
"winner": { "candidate": "gpt-4o", "upstream": "stub", "provider": "openai" },
"budget": { "scope": "global", "remaining": "4.999954" }
}
One leg, one verdict, one winner. When a chain has several candidates the
legs array grows an entry per attempt, each with the verdict that ended it,
which is how you tell a failover from a retry.
If it will not start
The failure you are most likely to hit is a declared credential that is not in the
environment. A referenced variable that is unset or empty is a hard load error,
not a warning, and it stops both config check and the server with exit 1:
Invalid route config in /abs/path/switchback.config.json: upstream "openai-direct": auth.env references environment variable "OPENAI_API_KEY" which is unset or empty — a declared key must be present at load, otherwise the upstream is silently keyless and every request 401s
The fix is the export from step 2, in the same shell that starts the router.
Note what the message does not contain: the loader prints the variable's name,
never its value. Two consequences worth internalising. Declare only the keys you have,
because an upstream you are not using yet still fails startup if its variable is missing.
And the loader stops at the first unset variable, so fixing one can reveal the next.
The other common first-run error is a config whose keys sit at the top level. Everything
belongs under route, or you get:
Config in /abs/path/switchback.config.json has no "route" section — nothing to serve.
Two things that will surprise you
Both are consequences of the router being chain-driven rather than model-driven. Better to meet them here than in an incident.
The request's model does not pick the candidate
With no models array in the request body, the engine routes the matched
route's chain, whatever model says. Against the config on this
page, a request for "model":"nope" is served successfully by
gpt-4o. The model field is used for exactly two things: choosing
a route via match.models globs, and populating
requested_model in the report.
Send a models array to override the chain instead. A slug in there that maps
to no upstream is a clean 404 rather than a silent substitution:
{"error":{"message":"no upstream mapping for candidates: nope","type":"no_route_configured","code":404}}
Only Chat Completions is served
Legacy /v1/completions is a permanent 404 with a message that says so, and
any unknown path is a structured 404 too. Nothing is proxied through by accident.
{"error":{"message":"no such endpoint: GET /nope","type":"not_found","code":404}}
Where to go next
You now have one upstream, one candidate, and no caps. Each of the next three pages removes one of those limits.
-
Configuration
Every field of the
routeblock, key by key, with what happens when you omit it. - Routing Add a second candidate and decide which failure classes advance the chain.
- Budgets Dollar and token caps, reserved before dispatch, so an overrun is refused rather than reported.
- CLI reference Every flag and subcommand, the exit codes, and the signals the process honors.