Haarness Router

The Haarness Router puts all your model providers behind one endpoint. Your provider keys live on the router, and Haarness only needs the router's address. You can run it yourself or use the managed one in Haarness Cloud.

Connect a router you run

You need a running router; Run the router yourself shows how. Then connect it from any Haarness app.

Desktop: Settings → Providers → Connect Haarness Router. Enter the router address, such as http://localhost:8080, and connect. The button appears while Desktop uses a Haarness server on this computer.

Terminal UI: /providers, then Connect Haarness Router, or /connect, then Haarness Router….

Command line, on the machine that runs the Haarness server:

haarness provider connect-router http://localhost:8080

When it works you see the number of models the router offers, for example Connected router · 12 models available. The models appear in the picker once no turn is running.

If the address or key is wrong, nothing is saved and you can try again.

Use its models

Router models appear as router/ followed by the router's own model name. Aliases you defined on the router appear too.

haarness models router
haarness run -m router/openai/gpt-5-nano "Hello"
haarness run -m router/fast "Hello"        # an alias

The list refreshes from the router, so models you add there show up without reconnecting.

A router that needs an access key

A new self-hosted router accepts requests without a key, and its dashboard at /ui has no password. On anything but your own computer, require a key and protect the dashboard or turn it off. To require a key, start it like this:

export HAARNESS_ROUTER_KEY="$(openssl rand -hex 32)"
haarness-router --config config.toml --require-key

Desktop and the terminal UI notice that the router requires a key and ask for it after you enter the address. From the command line, pipe the key in:

printf '%s' "$HAARNESS_ROUTER_KEY" \
  | haarness provider connect-router https://router.example.com --key-stdin

The key is never accepted as a command-line argument. Haarness stores it in its credential store, not in configuration. The router uses its own key only to let you in; it never passes it on to a provider.

Several routers

Connect as many as you like. The first gets the id router, the next router_2, and so on; use that id in model names, such as router_2/fast.

Choose Advanced in the connect form, or pass these flags, to set:

On a remote Haarness server

When the terminal UI is attached to a server on another machine, the connection is checked and saved on that server. localhost then means the server's machine, not yours. If a turn is running, the router becomes available when it finishes.

Addresses

• Without http:// or https://, localhost and 127.0.0.1 addresses use HTTP and everything else uses HTTPS. /v1 is added if you leave it out.
• A router on another machine must use HTTPS. Haarness only accepts plain HTTP on localhost, 127.0.0.1 and [::1]; it skips any other http:// router, and haarness providers prints why.
• An address with a user name, password, query or # part is refused.

Use the managed router in Haarness Cloud

With a Haarness Cloud account you do not need provider accounts or a router of your own. Sign in with haarness login or Sign in to Haarness in Desktop, then choose Haarness Cloud in the model picker. Requests are paid with Cloud credits. See Models and routers.

Your own provider keys in Cloud

A Cloud router set to Your provider keys uses your keys and your provider bills you; it never falls back to Cloud credits. In Routers, choose Provider keys on the router, pick a provider and paste its key. Keys are stored encrypted, never shown again, and shared with everyone who uses that router in your account. Most providers need only an API key; three need more:

Vertex access tokens expire; replace the token when it does. Models are discovered with your key. If one is missing, for example a custom Azure deployment, add it under Advanced model settings → Additional model IDs and call it as provider/model-id.

Related

• Run the router yourself
• Models and routers in Cloud