> ## Documentation index
> Fetch the complete documentation index at: https://haarness.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://haarness.ai/docs/cloud/self-hosted-router.md) 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:

```sh
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.

```sh
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](https://haarness.ai/docs/cloud/self-hosted-router.md). To require a key, start it like this:

```sh
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:

```sh
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:

| Setting | CLI flag | Effect |
| --- | --- | --- |
| **Connection name (optional)** | `--name "Team router"` | The name shown in pickers |
| **Available in** | `--project` | Only this project, not every project |

## 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](https://haarness.ai/docs/cloud/models-and-routers.md).

### 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:

| Provider | Needs |
| --- | --- |
| Amazon Bedrock | A Bedrock API key and its region |
| Azure OpenAI | Your Azure resource name and an API key |
| Google Vertex AI | Your Google Cloud project, location and an OAuth access token |

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](https://haarness.ai/docs/cloud/self-hosted-router.md)
- [Models and routers in Cloud](https://haarness.ai/docs/cloud/models-and-routers.md)