Run the router yourself

The Haarness Router puts one OpenAI-compatible endpoint in front of your own provider accounts, on your own machine or inside your network. It is licensed under MIT (Open source), and the managed router in Haarness Cloud is built on the same code. You do not need a Cloud account.

The router's source is not public yet. Its repository opens soon. Until then, write to [email protected] if you want to run it.

Managed router or your own?

Both speak the same API, so switching later only means changing the base URL and the key.

If you only want to use your own provider keys, you may not need to self-host: a Cloud router can use Your provider keys instead of credits. See Models and routers.

Get a first router running

You need the router's source, a current Rust toolchain (install it with rustup) and a C compiler.

1. Build it, in the router's source folder:

   cargo build --release

2. Write a config.toml that names the providers you have keys for, and the environment variables that hold the keys:

   [providers.openai]
   kind = "openai"
   api_key_env = "OPENAI_API_KEY"
   
   [providers.anthropic]
   kind = "anthropic"
   api_key_env = "ANTHROPIC_API_KEY"

   List only providers whose key you have: if a variable named here is not set, the router does not start.

3. Start it with your keys in the environment and a key of its own for your clients:

   export OPENAI_API_KEY=…  ANTHROPIC_API_KEY=…
   export HAARNESS_ROUTER_KEY=$(openssl rand -hex 32)
   ./target/release/haarness-router --config config.toml --require-key

4. In the same shell, send it a request:

   curl http://127.0.0.1:8080/v1/chat/completions \
     -H "Authorization: Bearer $HAARNESS_ROUTER_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"model":"openai/gpt-5-nano","messages":[{"role":"user","content":"Hello"}]}'

The router listens on http://127.0.0.1:8080, so only this machine can reach it. Models are named provider/model, and GET /v1/models lists the ones your keys can use. Point any OpenAI-compatible client at http://127.0.0.1:8080/v1 with HAARNESS_ROUTER_KEY as the API key. Its dashboard is at http://127.0.0.1:8080/ui: models, routes, live metrics and a playground.

To use its models in Desktop, the terminal UI or the CLI, connect the router.

Add providers, aliases and fallback

Each [providers.<name>] section takes a kind:

[providers.inhouse]
kind = "openai-compatible"
base_url = "https://llm.example.internal/v1"
api_key_env = "INHOUSE_API_KEY"

A plain http:// address is refused unless the section also sets allow_insecure_http = true.

An alias gives clients one model name that tries several models in order:

[aliases.fast]
targets = ["openai/gpt-5-nano", "anthropic/claude-haiku-4-5-20251001"]

Clients ask for the model fast. The router moves to the next target only when one cannot be reached, or answers 408, 429 or a 5xx before it has sent anything.

config.all-providers.example.toml in the router's source shows every provider type. Its README and docs/ folder cover model capabilities, --set overrides and the dashboard.

Run it on a server

Before other machines can reach the router:

1. Require a key with --require-key, as above.

2. Protect the dashboard, or turn it off. By default /ui has no password, and it can create router keys: anyone who can open it can make a key for themselves, even with --require-key. Give it a username and password from two environment variables:

   [web_ui]
   basic_auth_username_env = "HAARNESS_UI_USERNAME"
   basic_auth_password_env = "HAARNESS_UI_PASSWORD"

   Or start the router with --set web_ui.enabled=false to serve the API only.

3. Put HTTPS in front with a reverse proxy that terminates TLS. Haarness connects to a router on another machine only over HTTPS, and the dashboard's password is only safe over HTTPS.

4. Listen on another address with --host 0.0.0.0, --port 9090 or --bind 10.0.0.5:8080. Keep the default 127.0.0.1 when the proxy runs on the same machine.

What it does with your keys

• Provider keys come only from environment variables. The config file and --set name the variables; there is no setting for a key's value. The router reads them once at startup and never returns or logs them.
• Router keys stay with the router. The key a client sends is checked and never forwarded to a provider. Keys created in the dashboard live in memory and are gone after a restart.
• Callers cannot bring their own provider key unless you set allow_upstream_key_header = true under [auth]. Then a request may carry one in X-Upstream-API-Key, and only for an exact provider/model.
• It keeps nothing. No prompts, no usage history, no billing. It logs one line per request, without the prompt, headers or keys.
• The config is strict. An unknown setting, a typo or a missing environment variable stops the router at startup, rather than failing a request later.

Flags

Next

Connect it to Haarness: Haarness Router.