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

# Relay: the runtime with no policy

Relay is `vitna-runtime` started with no policy at all, for a developer who wants
a local gateway today and a register later, or never. Every request is served as
exactly the model it names, on your own keys, and every one is a line in a
ledger on your disk.

```bash
OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... npx -p vitna-runtime vitna-relay
```

`vitna-relay` is on the path of any [install](installing.md) from 0.2.0, and
0.1.2 has no such command. After `npm install -g vitna-runtime` it is
`vitna-relay`.

## What it is

The same runtime, not a second gateway. The owner decided on 2026-09-29 that
Relay keeps its name as a thin, zero-config preset over `vitna-runtime` rather
than a product of its own, so there is one codebase: `vitna-relay` chooses a few
defaults and starts the runtime in passthrough mode, and everything that serves a
request is the code [serving a lane](serving.md) describes.

Four properties it keeps, each held by a test:

- **The model served is exactly the one you named.** There is no policy, so there
  is no lane, no fallback chain, no rule and no seller rotation, and nothing can
  answer with a model you did not ask for. A request naming `vitna/<lane>` is
  refused by name with a 404.
- **It never calls vitna.ai.** Not at start, not per request, not to check for a
  newer version. Sending a ledger anywhere is [pushing](pushing.md), a separate
  command, and it needs a policy this has not got.
- **It listens on loopback**, `127.0.0.1:8787`. Any other `VITNA_HOST` needs
  `VITNA_INBOUND_KEY` or it refuses to start, exactly as the runtime does: see
  [the front door](serving.md#the-front-door).
- **Nothing is estimated.** A provider that reports no usage gets nulls on the
  row, never a plausible number.

## Pointing a client at it

**OpenAI SDKs and OpenAI-compatible tools**: set the base URL to
`http://127.0.0.1:8787/v1` and send any model name the provider behind it
serves. An unrouted name goes through OpenRouter where `OPENROUTER_API_KEY` is
set and to OpenAI directly where only `OPENAI_API_KEY` is, and the boot lines say
which key carries what, so read them once. Use the name the provider uses: through
OpenRouter that is `openai/gpt-5.6-luna`, directly it is `gpt-5.6-luna`. Nothing
here translates one into the other.

**Anthropic SDKs and Claude Code**: set `ANTHROPIC_BASE_URL=http://127.0.0.1:8787`.
With `ANTHROPIC_API_KEY` set, a request naming a model goes to Anthropic as it was
written, with its `anthropic-version` and `anthropic-beta` headers, and comes back
as Anthropic sent it, streams byte for byte. Thinking, prompt caching and every
beta work as they do direct, and Anthropic's own errors reach the client in its
own words, "prompt is too long" included. The one exception is
[redaction](#redaction-is-on), which is on: a known credential format in the
request is swapped for a stand-in before it leaves, and the real value is put
back wherever the answer carries the stand-in.

Your client's own credential is never forwarded. The runtime answers with the
keys in its own environment, so what a request costs is billed to the
`ANTHROPIC_API_KEY` Relay was started with, whatever the client is signed in as.
A client still has to hold some credential before it will send anything. On
loopback any value does, since nothing reads it; with `VITNA_INBOUND_KEY` set it
must be that key, sent as a bearer. For Claude Code that credential is
`ANTHROPIC_AUTH_TOKEN`, set in the shell Claude Code starts from, beside
`ANTHROPIC_BASE_URL`. Unlike a lane, Relay needs no `MAX_THINKING_TOKENS=0`: a
request naming a model is not translated, so thinking is carried.

## What it records

One line per request in `~/.vitna/relay/ledger.jsonl`, made on first start. Your
home directory rather than the one you ran it from, which is usually a
repository somebody could commit a ledger to. Each row is marked unrouted, with
no lane, no sku, no decision and no policy digest, because nothing in a record
chose the model. What the provider reported is there: tokens in and out, the
parts of the input a provider read from or wrote to its prompt cache, latency,
status, and the provider's message when it refused. With redaction on, a row
also counts the credentials lifted from the request and put back into the
answer, and holds none of them. [The ledger](ledger.md) is what each field
means.

## Flags

| Flag | Variable it sets | What it does |
|---|---|---|
| `--port <n>` | `VITNA_PORT` | Listen on this port rather than 8787 |
| `--ledger <path>` | `VITNA_LEDGER` | Append to this file rather than the one in your home directory |
| `--no-ledger` | | Record nothing, which the runtime says out loud at start |
| `--redact` | `VITNA_REDACT_PASSTHROUGH=1` | Lift known credential formats out of every request and put them back into its answer: [redaction](redaction.md). The default |
| `--no-redact` | `VITNA_REDACT_PASSTHROUGH=0` | Send every request with its credentials as written |
| `--cache <seconds>` | `VITNA_CACHE_TTL_SECONDS` | Answer a repeat of a deterministic request from memory for this long: [the response cache](cache.md) |

A flag beats the variable, and the variable beats Relay's default. Every other
variable of the runtime's (`VITNA_HOST`, `VITNA_INBOUND_KEY`, the upstream
budgets, `VITNA_ALLOW_PROVIDERS`) works as it does for `vitna-runtime`.

`VITNA_ALLOW_PROVIDERS` matters more here than anywhere, since every request
Relay serves names a model rather than a lane, and such a request is held to the
list by the route it takes: `openai` admits OpenAI directly, `openrouter` admits
OpenRouter, and `anthropic` admits an Anthropic request sent as written. So
`VITNA_ALLOW_PROVIDERS=anthropic` makes Relay an Anthropic-only gateway, refusing
every chat completion by name. [The provider allowlist](serving.md#the-provider-allowlist)
is the whole rule.

## Redaction is on

The one thing Relay changes in a request, and the one place the runtime makes a
change nobody asked for. A coding agent reads `.env` files, configuration and
shell history into its context, and without this the next request carries any
production key in them to a provider, where it cannot be called back. So Relay
lifts each known credential format out of a request before it leaves, sends a
stand-in of the same shape, and puts the real value back wherever the answer
carries the stand-in: in text, in tool arguments, and in a stream when a
stand-in arrives split across two chunks. A file the agent writes back gets the
real key.

What it does not do:

- **It knows formats, not secrets.** Provider keys, cloud and service tokens,
  JWTs, private keys, the password in a connection string and secret-named
  assignments, as [what it lifts](redaction.md#what-it-lifts) lists them. A
  credential in any other format leaves as written.
- **It does not read everything.** Images, documents, tool definitions and
  thinking go as written, since a thinking block's signature covers its text.
  The model only ever saw the stand-in, so thinking that mentions a key shows
  the stand-in.
- **It does not survive a restart.** A secret keeps its stand-in for as long as
  Relay runs, so a conversation's prompt cache holds from turn to turn. A
  restart draws new stand-ins, and a cached prefix that held a secret misses
  once.

`--no-redact`, or `VITNA_REDACT_PASSTHROUGH=0`, sends every request with its
credentials as written, and Relay's lines at start say which it is. The owner
decided on 2026-09-29 that Relay turns this on; every other way of starting the
runtime keeps it off until an operator names it.

## What it refuses

- **A policy.** With `VITNA_POLICY` or `VITNA_POLICY_B64` set it refuses to start:
  a machine holding a signed policy wants `vitna-runtime`, and serving that
  policy's traffic as passthrough would be the wrong runtime quietly. The
  opposite holds too: `vitna-runtime` still refuses to start without a verified
  policy, so a production runtime whose policy went missing can never become
  this.
- **A network address without a key.** `VITNA_HOST=0.0.0.0` with no
  `VITNA_INBOUND_KEY` refuses to start, since anybody who found the address could
  spend your provider keys.
- **`VITNA_REDACT_LANES`.** There are no lanes to name; redaction already covers
  every request.
- **A `VITNA_REDACT_PASSTHROUGH` that is neither 1 nor 0.** `true` read as off
  would turn redaction off for somebody asking for it, so the value is refused
  at start, by name.
- **A lane.** `vitna/<lane>` is a 404 that says this runtime serves no policy.

## When you want lanes

Relay is the way in, not the destination. A lane is a model a person accepted a
decision about, with a chain behind it and a ledger row that names the decision,
and that needs a policy. The same npm package serves one:
[installing the runtime](installing.md) is `npm install -g vitna-runtime` started
as `vitna-runtime` with a signed policy and the key that signed it, on your own
provider keys. Your Relay ledger is already in the shape it writes, so nothing
you recorded stops being readable.
