> Source: https://vitna.ai/docs/routing/hosted
> Raw Markdown: https://vitna.ai/docs/routing/hosted.md
> Corpus index: https://vitna.ai/llms.txt

# Running the hosted router

`router:start` serves an OpenAI-compatible endpoint for several organisations at
once, resolving each request against that organisation's own signed policy and
paying for it with that organisation's own delegated OpenRouter key.

```bash
VITNA_ROUTER_POLICIES=/etc/vitna/policies \
VITNA_PUBLIC_KEY=$(cat /etc/vitna/policy-key.pub) \
VITNA_ROUTER_LEDGERS=/var/lib/vitna/router \
VITNA_CONNECTION_KEY=... DATABASE_ROUTER_URL=... \
npm run router:start
```

This is Vitna in a request path, which every other page here says Vitna is not.
[The design](router.md) is where that is argued and where its costs are named,
including the one that does not go away: a hosted router's outage is an outage,
for the customers it exists to serve.

## What a hosted policy is, and why it is a different file

```bash
npm run aperture:policy -- --org convexity --hosted --out /etc/vitna/policies/convexity.json
```

`--hosted` emits only the lanes that organisation's own connections can fund. A
lane it cannot pay for is **absent from the document**, not refused when
somebody calls it, which is the same move the emitter already makes for a
workload's constraints: a lane carrying a data requirement is written with no
OpenRouter name at all, so the traffic cannot go there rather than being asked
not to.

Three things follow, and none of them needed designing:

- The router asks nothing about permission while a request is waiting. That is
  a property of where the check runs.
- Disconnecting an account is a policy re-emission, signed like everything else,
  rather than a runtime state change nobody can audit.
- Every dropped lane is named when the policy is emitted, so a policy quietly
  smaller than the register is not a thing that can happen silently.

A hosted policy and a customer-run policy are different documents with different
digests, deliberately. What a customer runs on their own box with their own keys
and what Vitna may serve on their behalf are not the same set of lanes, and one
file pretending to be both would overstate one of them.

## Calling it

```bash
curl https://router.example/v1/chat/completions \
  -H 'authorization: Bearer vitna_push_...' \
  -H 'content-type: application/json' \
  -d '{"model":"vitna/deep-research","messages":[{"role":"user","content":"hello"}]}'
```

The key decides which organisation the request is for. A model name without the
`vitna/` prefix is forwarded untouched and marked unrouted, exactly as the
runtime does.

**A router key is not a push key.** They are the same shape and they are two
capabilities: a push key reports what already happened, and a router key spends
money at a provider. Mint one deliberately:

```bash
npm run org:key:create -- --org convexity --scope router --label "router, prod"
```

A push key presented to the router is refused with a sentence saying so, and a
router key presented to `/api/v1/usage` is refused the same way. A capability
that is a superset of another has not been separated from it.

## What it holds, and what it cannot

| | |
|---|---|
| The credential in front of a request | The organisation's own OpenRouter key, minted by a consent screen |
| Who bills the customer | OpenRouter, directly, on the account that granted the key |
| Their kill switch | `openrouter.ai/keys/<sha256>`, without telling Vitna |
| A stored provider key | **Refused.** There is no configuration that turns it on |

The router is the only thing anywhere permitted to read a sealed connection, and
it holds no write on anything. The console can store a credential and cannot
read one back; the router can read one and cannot write one. Neither can do
both.

## Configuring an instance

| Variable | Meaning |
|---|---|
| `VITNA_ROUTER_POLICIES` | Directory of signed hosted policies, one per organisation, as `<org>.json`. Required. |
| `VITNA_PUBLIC_KEY` | The key to verify them against, pinned once out of band. Several, comma separated, are accepted. Required. |
| `DATABASE_ROUTER_URL` | The `vitna_router` role. Reads one key row and one connection, and writes nothing anywhere. Required. |
| `VITNA_CONNECTION_KEY` | The sealing key the console's connect flow uses. Required, or no delegated key opens. |
| `VITNA_ROUTER_LEDGERS` | Directory for one ledger per organisation. Optional, and its absence is said out loud. |
| `VITNA_ROUTER_PORT` | Default 8788. |

`GET /status` answers for the organisation whose key is presented and for no
other. `GET /healthz` is unauthenticated and says only whether the process is
up, because that is not a fact about a tenant.

`SIGHUP` reloads every policy. A reload that cannot be verified leaves that
organisation's running policy in force and takes nobody else's lane down.

## Checking the router against a record it does not keep

This is the part worth reading even if you never run the router yourself.

Under the file and GitOps modes, a mistaken or forged policy still has to reach
a runtime, which means a diff somebody merges. A hosted router has no diff and
no reviewer: Vitna signs the policy and Vitna executes it. The merge control is
not thin there, it is absent.

What replaces it is a check you run at a party Vitna is not. Every request the
router makes carries your own delegated key, so OpenRouter's record of what that
key did is a second account of the same traffic, kept by somebody with no stake
in Vitna's ledger being right.

1. Read what your key did at `openrouter.ai/logs?api_key_hash=<sha256>`. The
   digest is on your `/status` response and on the console beside the
   connection. The page resolves only for the signed-in owner.
2. Export it, as JSON or CSV, with a timestamp column and a model column.
3. Compare it against the router's ledger for your organisation:

```bash
npm run router:trail -- --ledger convexity.jsonl --provider openrouter-activity.json
```

It exits non-zero when the two accounts disagree, so it can sit in your own CI
and mean something without being read.

**What it catches**: a serve the router made and did not record, a serve the
ledger claims that never happened, and a model substituted for the one your
decision named. **What it does not**: a forged policy routing within the same
model you already funded, which both accounts would agree on. What bounds that
is the reachable universe above, which is why the two mechanisms are described
together.

The command holds no key and reaches no network. It reads two files you already
have, and it runs equally well against a ledger somebody else produced, which is
the other half of what makes it worth having.

**A clean comparison is not proof the router behaved.** It is one account
agreeing with another over the window compared, which is weaker than a merge
because it catches after rather than before, and stronger than a promise because
the checker is not the party being checked.
