TinyRouter

Fallbacks you can read

Give an alias a list of targets. TinyRouter tries them in exactly the order you wrote, and nothing is inferred. Serve your own hardware first and reach for a hosted model only when it cannot answer:

routes:
  assistant:
    - local/qwen3
    - anthropic/claude-sonnet-4-6

What it promises

The whole routing contract fits on one page.

Quick start

1. Install

   curl -fsSL https://tinyrouter.dev/install.sh | sh

   The script picks the archive for Linux or macOS on x64 or arm64, checks it against that release's SHA256SUMS, and unpacks tinyrouter and tinyrouter.example.yaml into the current directory. It needs no root. Pin a release with | sh -s -- 0.9.0. It is about a hundred lines, so read it before you pipe it into a shell. The executable embeds the Bun runtime, so nothing else needs installing, except apk add libstdc++ on Alpine.

   Or download by hand

   curl -fsSL https://github.com/honzabit/tinyrouter/releases/latest/download/tinyrouter-linux-x64.tar.gz | tar -xz

   Swap linux-x64 for linux-arm64, darwin-x64, or darwin-arm64, and check the download against SHA256SUMS. On macOS, extract with tar rather than Finder, which marks the executable as damaged. On Alpine, use linux-x64-musl or linux-arm64-musl, after apk add libstdc++. Releases up to 0.9.0 have no musl build; use the container below for those.

2. Configure

   The archive includes an example that matches the executable beside it. Keep the providers you use, add a route like the one above, and export the keys it references:

   cp tinyrouter.example.yaml tinyrouter.yaml
   export TINYROUTER_API_KEY=local-secret
   export ANTHROPIC_API_KEY=sk-ant-...

3. Run

   ./tinyrouter

   It reads tinyrouter.yaml and listens on 127.0.0.1:8080 until you set server.host. Use --check to validate a configuration without starting.

4. Call the alias like a model

   curl http://localhost:8080/v1/chat/completions \
     -H 'Authorization: Bearer local-secret' \
     -H 'Content-Type: application/json' \
     -d '{"model":"assistant","messages":[{"role":"user","content":"Hello"}]}'

   Any client that takes an OpenAI base URL works unchanged: point it at http://localhost:8080/v1.

Or run the multi-architecture container:

docker run --rm -p 8080:8080 --env-file .env \
  -v "$PWD/tinyrouter.yaml:/etc/tinyrouter/tinyrouter.yaml:ro" \
  ghcr.io/honzabit/tinyrouter:latest

Providers

Clients always see one shape, OpenAI's /v1/chat/completions and /v1/models, streaming or not. Behind it:

Also in the box

See what it is doing

A single static HTML file in ui/, also attached to every release as tinyrouter-ui.html, reads the gateway's own endpoints. It shows which providers are healthy, which the circuit breaker has demoted, and where your tokens went:

Bad bodies is the column no status code can give you: a provider that answers 200 and then hangs part-way through the stream. The status line went out long before anyone knew.

Download it and open it locally rather than using a copy hosted here. It is a page that reads your gateway, and a page served from someone else's domain is a page whose JavaScript you have to trust with it. That is the whole argument for this project, so it would be odd to make an exception.

When to use it

• You want to audit the thing that holds your keys. Two dependencies, no build magic, one file of configuration.
• You refuse to run infrastructure for a proxy. One process. No database, no Redis, no admin UI.
• You run local models with cloud fallback. Serve your own hardware first, fail over only when it cannot answer.
• You need failover you can reason about. The routing contract fits on a page and never switches providers mid-stream.
• Clients you don't control need one endpoint. Anything that accepts an OpenAI base URL gets aliases and failover with no code changes.

Use something else when

Those are good projects. TinyRouter exists for the case where the feature you want most is being able to understand the whole thing.

Documentation

Reference lives in the repository, versioned alongside the code, so a clone or a source archive describes the commit you actually have rather than whatever is newest.