Configuration
One JSON file describes the whole edge: where the router listens, which upstreams exist and how each one authenticates, which model slugs map where, which routes match what, and the caps that bound spend. This page is the field-by-field reference: every key, its type, its default, and exactly what refuses to load.
How the file is read
The config is plain JSON, parsed in one shot at startup. The default path is
switchback.config.json in the working directory; --config points
elsewhere. The loader reads two top-level keys: route, which
is everything on this page, and fixtures, which only
sim reads. Anything else in the file is ignored, so a
stray sibling key is silently inert rather than an error.
Inside route, three blocks are required: listen (with at least a
port), upstreams (at least one), and routes (at least one).
models, budget, catalog and record are
optional.
{
"route": {
"listen": { "port": 4011 },
"upstreams": {
"openai-direct": {
"baseURL": "https://api.openai.com/v1",
"dialect": "openai-compat",
"auth": { "env": "OPENAI_API_KEY" }
}
},
"models": {
"gpt-4o": { "openai-direct": "gpt-4o" }
},
"routes": {
"default": {
"chain": ["gpt-4o"],
"policy": { "advanceOn": ["rate_limited", "server_error"] }
}
}
}
}
Warning
Optional fields are never coerced. A present-but-wrong-typed value is a hard load error,
not a silent fallback. "enabled": "true" (the string) fails; it does not
become false. Every rejection is reported as
Invalid route config in <path>: <message> and the process exits
1. A config with no route key exits 1 the same
way.
Declaration order in the file is significant in three places: the order of
upstreams drives the leg order for unlisted models, the order of
routes decides first-match route selection, and budget scopes are listed in
declaration order. Reordering keys changes behavior.
Check a file without starting the server. This loads it through the same loader the server uses, so anything below that is a hard failure surfaces here first.
$ switchback config check --config switchback.config.json
A complete config
Every block on this page appears below, with real values. Copy it, change the upstream names and the environment variable names, and it will load.
{
"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" },
"timeouts": { "connectMs": 2000, "ttftMs": 15000, "totalMs": 120000 }
},
"anthropic-direct": {
"baseURL": "https://api.anthropic.com",
"dialect": "anthropic-messages",
"profile": "anthropic",
"auth": { "env": "ANTHROPIC_API_KEY" },
"headers": { "anthropic-version": "2023-06-01" }
},
"ollama-local": {
"baseURL": "http://127.0.0.1:11434/v1",
"dialect": "openai-compat",
"profile": "openai",
"auth": null
},
"openrouter-fallback": {
"baseURL": "https://openrouter.ai/api/v1",
"dialect": "openai-compat",
"profile": "openrouter",
"auth": { "env": "OPENROUTER_API_KEY" },
"unlistedModels": "verbatim",
"forwardHeaders": ["HTTP-Referer", "X-Title"],
"allowCallerKeys": false
}
},
"models": {
"gpt-4o": {
"openai-direct": "gpt-4o",
"openrouter-fallback": "openai/gpt-4o"
},
"claude-sonnet-4-5": {
"anthropic-direct": "claude-sonnet-4-5",
"openrouter-fallback": "anthropic/claude-sonnet-4.5"
},
"llama-3.3-70b": {
"ollama-local": "llama3.3:70b",
"openrouter-fallback": "meta-llama/llama-3.3-70b-instruct"
}
},
"routes": {
"chat-default": {
"match": { "surface": ["/v1/chat/completions", "/api/v1/chat/completions"] },
"chain": ["gpt-4o", "claude-sonnet-4-5", "openrouter/auto"],
"provider": { "allow_fallbacks": true },
"policy": {
"advanceOn": [
"rate_limited", "auth_budget", "server_error", "connect_error",
"timeout_connect", "timeout_ttft", "silent_empty",
"stream_error_pre_token", "translated_bad_request"
],
"sameLegRetries": { "server_error": 1 },
"backoff": { "baseMs": 200, "maxMs": 2000, "jitter": true },
"respectRetryAfter": { "capMs": 5000 },
"maxTotalAttempts": 6,
"keepalive": false
}
}
},
"budget": {
"backend": { "kind": "memory", "persistPath": "./.switchback/budget.json" },
"global": { "dollars": "500.00", "tokens": 50000000, "window": "monthly" },
"perRoute": { "chat-default": { "dollars": "50.00", "window": "daily" } },
"perUpstream": { "openrouter-fallback": { "dollars": "25.00", "window": "monthly" } },
"priceMap": {
"llama3.3:70b@ollama-local": { "prompt": "0", "completion": "0" }
},
"promptSafetyFactor": 2.0,
"completionReserveFraction": 1.0,
"allowUnpriced": false,
"overflowFallback": false,
"onStoreError": "fail-closed"
},
"catalog": { "refresh": false },
"record": { "enabled": false, "dir": "./fixtures/recorded" }
}
}
Two details in that file are worth naming now, because both are easy to get wrong.
"openrouter/auto" is not in models; it reaches
openrouter-fallback only because that upstream sets
unlistedModels: "verbatim". And the priceMap key is
llama3.3:70b@ollama-local, the upstream model id, not the
llama-3.3-70b slug. See
priceMap keys.
fixtures
A list of glob patterns naming the fixture files
sim replays a request against. This is the one key
that lives beside route rather than inside it, because it describes
upstream behaviour for the whole file rather than any single route.
{
"fixtures": ["./fixtures/failure-taxonomy/*.json", "./fixtures/app/*.json"],
"route": { /* ... */ }
}
Relative patterns resolve against the config file's directory, not the working
directory, so a committed config simulates identically from anywhere in a repo. A pattern
that matches no files is a hard failure: a run against zero fixtures routes nothing and
would read as a pass. The serve path never reads this key, so a config with no
fixtures is complete for production — it simply cannot be simulated.
route.listen
Required. Where the HTTP server binds.
Interface to bind. Loopback by default, so a fresh config exposes nothing off-box.
Must be a non-negative integer. 0 is legal and means "let the OS pick",
and the chosen port is reported back on startup.
Warning
Omitting the whole listen block is a hard failure:
route.listen is required (needs at least a port). Any host other than
127.0.0.1, localhost or ::1 loads fine but logs a
warning naming the exposure. See Security for the bind posture,
and Deploy for when you actually want it.
route.upstreams
Required, at least one entry. An object keyed by upstream name, and that name is what
models, budget.perUpstream, provider.only and the
per-request headers all refer to. Declaration order matters for unlisted models.
Non-empty URL the legs are dispatched against. A URL carrying inline userinfo
(https://user:pass@host) is refused at load. Paste the provider's
documented base as it is, with or without its trailing API version: the dialect
appends its own path (/v1/chat/completions for
openai-compat), and a version segment already at the end of the base is
not repeated. So https://api.openai.com/v1 and
https://api.openai.com both dispatch to
https://api.openai.com/v1/chat/completions.
The wire format spoken to this upstream: openai-compat,
anthropic-messages, gemini-generate,
bedrock-converse or cohere-chat. Per-dialect capability
detail lives in Providers.
Host profile id, which carries the vendor's auth-header shape and quirks. Must be one of the 14 bundled ids listed below; an unknown id is a hard failure.
Exactly { "env": "VAR" }, { "file": "path" }, or
null. Nothing else. Full grammar below.
Static string headers added to every request to this upstream, for things like
anthropic-version. Any value that looks like a credential is a hard
load error; keys go through auth.
connectMs, ttftMs, totalMs. Each must be a
positive finite number. connectMs and ttftMs are what
produce the timeout_connect and timeout_ttft verdicts that
policy.advanceOn can act on.
Whether this upstream serves slugs absent from models:
"verbatim" passes the slug through, "strip-author" drops
everything up to the first /, "none" (or unset) declines.
See Routing for how these become legs.
Allowlist of caller headers to pass through to this upstream. Naming a provider-auth header here is a hard load error.
Whether a caller-supplied key may be used for this upstream. Set it to
false to force the router's own credential.
Danger
allowCallerKeys is a sibling of auth, not a field inside it.
Written as auth.allowCallerKeys it does not disable caller keys. It trips
the "unexpected key(s)" error and the config refuses to load. That failure is the
friendly outcome; the shape that would quietly leave caller keys enabled is the one to
watch for.
The auth grammar
Credentials are referenced, never written inline. The loader accepts three forms and rejects everything else.
Name of an environment variable, read once at load. Unset or empty is a
hard failure naming the variable, so a missing key is a startup error rather than a
500 mid-incident. An env name that itself looks like a credential is
refused.
Path to a key file; relative paths resolve against the config file's directory. The
file must be mode 0400 or 0600; any looser mode is a hard
failure that states the actual octal mode. Contents are trimmed.
A keyless upstream. This is the right shape for a local model server that needs no credential.
Danger
There is no way to put a secret in this file. A bare string in auth is
refused; both env and file together is refused; neither is
refused; and any extra key (value, token, key) is
refused by name. If the rejected string looks like a credential the error says so
without echoing the value. Credential-shape detection also covers
headers values and generic high-entropy strings, so an inline key smuggled
through a static header fails the same way.
Bundled profile ids
Fourteen host profiles ship with the router. openai is the fallback.
| Profile ids |
|---|
| openai · anthropic · gemini · bedrock · cohere |
| openrouter · groq · mistral · perplexity · cerebras |
| sambanova · alibaba · zai · moonshot |
route.models
Optional. A two-level map: client-facing slug, then upstream name, then that upstream's
own model id. These slug keys are exactly what /v1/models and
/api/v1/models advertise, so this block doubles as your published catalog.
The upstream's model id for this slug. Must be a non-empty string, and the upstream
name must exist; an unknown name fails with
route.models.<slug> references unknown upstream "<up>". A
slug listed here is served only by the upstreams named under it;
unlistedModels does not apply to it.
route.routes
Required, at least one entry. An object keyed by route name, evaluated in declaration
order: the first route whose match accepts the request wins, so put the
catch-all last.
match.surface is a string array of exact request paths;
match.models is a string array of *-globs against the
requested model. Both must be arrays of strings if present.
Model slugs in fallback order. Each slug expands into one leg per upstream that can serve it; the router walks that list until one succeeds.
Upstream preferences: order, only,
ignore (string arrays), allow_fallbacks (boolean),
sort. See below.
Retry and advance behavior. policy.advanceOn is itself required, so
every route states in writing which failures are allowed to move the chain.
Streaming-only keepalive for this route. Also settable inside policy.
Note
A chain entry that maps to no upstream is only a
warning at load, not an error:
chain model "<m>" maps to no upstream … it will contribute zero legs.
The config starts. If the whole chain maps nowhere, requests matching that route get a
404 at request time. Read the startup log.
provider
order front-loads named upstreams, only and
ignore filter, and allow_fallbacks: false truncates the chain to
the primary candidate. A request may narrow these further but never widen them; the
composition rules are in Routing.
Validated at load and rejected if it is anything other than those three values, and then ignored. The comparators it would need are never supplied on the live request path, so leg order is preserved exactly as expansion produced it.
Warning
Do not plan cost or latency ordering around provider.sort in this build. A
route with "sort": "price" and a priceMap making the
second-declared upstream a thousand times cheaper still sends the request to the
first-declared one. If you want a cheap upstream tried first, declare it first, or
front-load it with provider.order.
policy
Which failure classes advance to the next leg. Every entry must be a known reason; an unrecognised one is a hard failure naming the bad reason. Valid values are listed below.
Per-reason retry count against the same leg before advancing, e.g.
{ "server_error": 1 }. Non-negative integers only.
{ "baseMs", "maxMs", "jitter" }, and all three are required together if
you supply the block at all. Omit it entirely to accept the defaults.
{ "capMs": number }, and nothing else. Bounds how long a provider's
Retry-After is allowed to stall a request. There is a built-in cap even
when you omit this.
Positive integer ceiling on attempts across the whole chain, retries included. Left out, the chain is bounded only by its own length and retry counts.
Streaming keepalive, same switch as the route-level keepalive.
Valid advanceOn reasons
| Reason | Advances the chain when |
|---|---|
| rate_limited | 429, with Retry-After honored up to the cap |
| auth_budget | Provider-side permission or budget refusal (401 / 402 / 403 class) |
| server_error | 5xx from the upstream |
| connect_error | TCP, TLS or DNS failure |
| timeout_connect | timeouts.connectMs elapsed |
| timeout_ttft | Dispatched, then stalled before the first token |
| silent_empty | 200 with no content |
| stream_error_pre_token | 200 stream whose first event is an error frame |
| translated_bad_request | 400 on a translated leg, or content the dialect cannot express |
| budget_exhausted |
Accepted here but ignored; governed by budget.overflowFallback
|
route.budget
Optional as a whole block. With no budget, nothing is capped.
Budgets covers what the caps mean at runtime (reserve before
dispatch, settle from real usage, the 402 envelope). The fields are here.
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| backend.kind | memory | file | redis | Optional | memory | Where spend counters live |
| backend.persistPath | string | With file |
none | Optional snapshot for memory; required for file |
| backend.url | string | With redis |
none | Redis connection URL (redis:// or rediss://) |
| global | cap object | Optional | none | One ceiling for all traffic; scope key global |
| perUpstream | map of cap objects | Optional | none | Per-upstream ceilings; scope key upstream:<name> |
| perRoute | map of cap objects | Optional | none | Per-route ceilings; scope key route:<name> |
| priceMap | map of price objects | Optional | none | Price overlay on top of the catalog; key format matters |
| promptSafetyFactor | number ≥ 0 | Optional | 2.0 | Multiplier on the estimated prompt cost when reserving |
| completionReserveFraction | number ≥ 0 | Optional | 1.0 | Fraction of max completion tokens reserved up front |
| allowUnpriced | boolean | Optional | false | Whether a leg with no known price may run under a dollar cap |
| overflowFallback | boolean | Optional | false | Whether a reserve refusal advances the chain instead of failing the request |
| onStoreError | fail-closed | fail-open | Optional | fail-closed | What happens when the counter store is unreachable |
Warning
backend.kind: "file" without backend.persistPath is a startup
failure:
budget.backend.kind is "file" but budget.backend.persistPath is not set.
Set the path, or use memory, where persistPath is an optional
snapshot. Which backend suits which topology is covered in Deploy.
Cap objects
Every scope (global, each perUpstream entry, each
perRoute entry) takes the same three fields.
A string, not a number: digits, an optional ., and at most six
fractional digits. Parsed and range-checked at load. "1e-6",
"-1" and "abc" all fail; "50.00" is the shape
you want.
Non-negative integer token ceiling for the window. A cap may set
dollars, tokens, or both.
One of five values: hourly, daily,
weekly (Monday-anchored), monthly, total.
Anything else is a hard failure.
priceMap keys use the upstream model id
The overlay is keyed <upstreamModelId>@<upstream>, the id the
upstream knows, not the client-facing slug. Price literals follow the same
grammar as dollars: non-negative plain decimals, with scientific notation
rejected explicitly at load.
// models maps the slug "llama-3.3-70b" onto the upstream's own id:
"models": { "llama-3.3-70b": { "ollama-local": "llama3.3:70b" } }
// so the price key is built from THAT id:
"priceMap": { "llama3.3:70b@ollama-local": { "prompt": "0", "completion": "0" } }
// this one is accepted, never matches, and silently does nothing:
"priceMap": { "llama-3.3-70b@ollama-local": { "prompt": "0", "completion": "0" } }
Danger
A priceMap key that matches nothing produces no error. The
overlay is ignored and the leg falls through to the catalog. So the common intent,
pricing a local model at "0" so a keyless upstream never draws down a
dollar cap, fails in the worst direction: with no catalog row and no overlay, that leg
is refused as unpriceable under a dollar cap instead of being free. Check the key
against the id in models, character for character.
route.catalog
Optional. The router ships with a signed catalog snapshot, which is what prices legs by default. This block configures refreshing that snapshot over the network.
Master switch. Present but not a boolean is a hard failure. Refresh only arms when
this is true and both url and
intervalSec are set.
Where the signed catalog.json is fetched from. Inline userinfo in the
URL is a hard failure, and the URL is scheme- and SSRF-checked before any timer
starts.
Seconds between refresh attempts. Values of zero or less are currently accepted by the loader without complaint, which is a known defect. Pass a sensible positive interval.
Warning
Network catalog refresh does not arm in this build, even fully configured. The pinned verifying key is still the committed development key, whose private half is in the repo and therefore forgeable, and a forged catalog could price a model to zero and walk through a dollar cap. The router logs a refusal instead of starting the timer. The bundled snapshot still verifies and is still used.
route.record
Optional. Writes request/response fixtures for later replay.
Turns recording on. The --record flag force-enables it regardless of
what the file says. See CLI.
Where fixtures are written. Omitted, the recorder picks its own fixtures directory.
Note
Recorded fixtures go through the same redaction chokepoint as logs, but the extra
header-denylist option is not exposed in the config schema today; there is no
record.extraHeaders. What is and is not redacted is described in
Security.
What refuses to load, and what only warns
A config that refuses to load is doing you a favor. The distinction below is the one worth memorising: the first group stops the process, the second lets it start with behavior you may not have intended.
| Condition | Outcome |
|---|---|
No route key, or listen block missing |
Exit 1 |
Empty upstreams or empty routes |
Exit 1 |
Missing baseURL / dialect, or unknown dialect or profile
|
Exit 1 |
baseURL or catalog.url with inline userinfo |
Exit 1 |
auth as a bare string, both env and file,
neither, or any extra key
|
Exit 1 |
auth.env variable unset or empty at load |
Exit 1 |
auth.file not mode 0400 or 0600 |
Exit 1 |
Credential-shaped headers value, or an auth header in
forwardHeaders
|
Exit 1 |
models referencing an unknown upstream |
Exit 1 |
Missing chain or policy.advanceOn, or an unknown advance
reason
|
Exit 1 |
Partial backoff block, or a non-positive timeout |
Exit 1 |
Malformed dollars / price literal, or an unknown window
|
Exit 1 |
backend.kind: "file" with no persistPath |
Exit 1 |
| Any optional field present with the wrong type | Exit 1 |
A chain model that maps to no upstream |
Warning; 404 at request time if the whole chain is unmapped |
Non-loopback listen.host |
Warning naming the exposure; binds anyway |
provider.sort set |
Accepted, validated, then ignored |
priceMap key that matches no leg |
Silently ignored, no message at all |
catalog.intervalSec of zero or less |
Accepted; known defect |
fixtures not an array, or an entry not a string |
Refuses to load |
Unrecognised top-level key beside route and fixtures
|
Ignored |
What SIGHUP actually reloads
SIGHUP re-reads the whole file, but most of it is not hot-swappable. Treat it
as a way to adjust caps and prices, not as a general reload.
| Part of the config | On SIGHUP |
|---|---|
| Budget caps and cap gauges | Rebuilt |
priceMap overlay |
Rebuilt |
Credential registry (auth refs re-resolved) |
Rebuilt |
| Budget backend | Restart required (logs a warning) |
| Catalog refresher | Restart required (logs a warning) |
| Observer hooks and recorder | Restart required (logs a warning) |
listen.host / listen.port |
Restart required (logs a warning) |
Where the behavior is documented
This page is the schema. What each block does at request time lives with the behavior it governs.
-
Routing
How
match,chain,providerandpolicybecome an ordered list of legs. - Budgets Reserve, settle, windows, the 402 envelope, and choosing a store backend.
- Providers The five dialects, the bundled profiles, and per-dialect parameter fidelity.
- Security Credential isolation, header forwarding, caller keys, redaction, bind posture.
- Observability Per-request routing reports, spend endpoints, metrics, and recorded fixtures.
-
CLI
Flags that override this file,
config check, and signal handling.