> Source: https://vitna.ai/docs/runtime/local
> Raw Markdown: https://vitna.ai/docs/runtime/local.md
> Corpus index: https://vitna.ai/llms.txt
# A lane on your own machine
An operator note: one command from a workload in the register to a runtime
answering on the same machine, run from a checkout of Vitna's repository, which
is private. It is for Vitna's own operators. Outside Vitna, the runtime is
installed from npm with a policy the console signs, which is
[Installing the runtime](installing.md).
## Outside Vitna, start here instead
Every `npm run` command further down this page needs a checkout of the
repository and a register you can read straight from its database, and neither
is published. The same runtime from npm takes a signed policy and its key from
`/console/deployment`:
```bash
npm install -g vitna-runtime
```
[Installing the runtime](installing.md) goes from there to a served lane, and
[Serving a lane](serving.md) covers every variable. To try a runtime with no
policy and nothing to sign, `vitna-relay` is in the same package:
[Relay](relay.md).
## Operator note: one command from the register
So an operator can send a request through a lane and read the row it wrote,
from a checkout:
```bash
npm run runtime:local
```
It reads your register, emits the same signed policy
[`aperture:policy`](../routing/policy.md) emits, and starts the runtime on it.
Nothing about the runtime is relaxed to make that work, and the section at the
bottom is exact about what is different.
## Before you start
Two things, and you probably have both.
**A register you can read.** `DATABASE_URL` points at it. This command reads the
record and writes nothing to it, and the runtime it starts never touches the
database at all.
**A key for one provider.** `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` or
`OPENROUTER_API_KEY`, whichever reaches the model your lane is decided on. It is
yours, it is read out of your environment, and it goes to that provider and
nowhere else.
```bash
export DATABASE_URL=postgresql://localhost/vitna
export OPENAI_API_KEY=sk-...
```
```powershell
$env:DATABASE_URL = "postgresql://localhost/vitna"
$env:OPENAI_API_KEY = "sk-..."
```
## The sequence
**1. Give a workload a lane name.** A lane is a workload carrying an alias a
caller can put in a request. A workload without one is decided and not routable,
which is the ordinary state of most of them.
```bash
npm run aperture:workloads
npm run aperture:workload:edit -- <workload-id> --policy-alias deep-research
```
The workload also needs an accepted decision behind it, which is what a lane
resolves to. If it has none, the command below says so and names the workload.
**2. Start it.**
```bash
npm run runtime:local
```
It prints the lanes it emitted, the decision behind each one, and where the
policy and the ledger are:
```
policy /home/you/vitna/.vitna/policy.json, 2 lanes, digest 9f2c...
deep-research claude-opus-4-8 anthropic decision 154
classification-and-lookups gpt-5.6-luna openai decision 151
ledger /home/you/vitna/.vitna/ledger.jsonl, one line per request
key generated for this run, held in memory, gone when this exits
Point an OpenAI client at http://127.0.0.1:8787/v1 and send a lane as its model:
vitna/deep-research
vitna/classification-and-lookups
vitna-runtime 0.2.0
vitna-runtime: policy 9f2c... for convexity, generated 2026-09-10T09:00:00.000Z
vitna-runtime: 2 lanes servable: deep-research -> claude-opus-4-8 (direct, completion budget 540000ms), classification-and-lookups -> gpt-5.6-luna (direct, completion budget 540000ms)
vitna-runtime: OPENAI_API_KEY is set, and bills your openai account directly for the first attempt of classification-and-lookups, and every model name sent without a lane
vitna-runtime: ANTHROPIC_API_KEY is set, and bills your anthropic account directly for the first attempt of deep-research
vitna-runtime: upstream budgets: 540000ms for a completion (VITNA_UPSTREAM_TIMEOUT_MS), 300000ms to a stream's first byte (VITNA_UPSTREAM_FIRST_BYTE_MS), 300000ms of silence inside a stream (VITNA_UPSTREAM_IDLE_MS)
vitna-runtime: listening on 127.0.0.1:8787, loopback only, so no key is asked for. POST /v1/chat/completions, POST /v1/messages, GET /status, GET /healthz.
```
With more than one organisation in your register, `--org` says which:
`npm run runtime:local -- --org convexity`. With one, it takes it and says so.
`--port` and `--dir` move the port and the directory.
**3. Send a request**, from another shell.
```bash
curl 127.0.0.1:8787/v1/chat/completions \
-H 'content-type: application/json' \
-d '{"model":"vitna/deep-research","messages":[{"role":"user","content":"hello"}]}'
```
```powershell
$body = '{"model":"vitna/deep-research","messages":[{"role":"user","content":"hello"}]}'
Invoke-RestMethod -Method Post -ContentType application/json -Body $body `
-Uri http://127.0.0.1:8787/v1/chat/completions
```
Any OpenAI-compatible SDK works the same way: point its base URL at
`http://127.0.0.1:8787/v1` and send `vitna/<lane>` where it wants a model name.
The address rather than `localhost` on purpose: the runtime listens on IPv4
loopback only, and a client that resolves `localhost` to `::1` first and does
not fall back would find nothing there.
A name without the prefix is passed through untouched, so you can point a
service that is already running at this and move one lane at a time.
**4. Read what it recorded.**
For a cloud lane, the proof command sends one short, fixed prompt and checks
that the runtime appended exactly one served row under its loaded policy and
the decision ID carried by that policy. Run it from a second shell on the same machine:
```powershell
npm run runtime:prove -- --lane deep-research
```
The package exposes the same check as `vitna-runtime-prove`. It
prints the provider, sku, decision, policy digest and reported token counts,
without printing the prompt or answer. It refuses a local Anchor lane, a cache
hit, a fallback, overlapping traffic or a missing ledger. This check confirms
the serving path; the decision's separate price evidence is in its decision
pack. A pack is signed only when exported with a signing key.
```bash
cat .vitna/ledger.jsonl
```
```powershell
Get-Content .vitna\ledger.jsonl
```
One line per request:
```json
{"at":"2026-09-10T09:01:04.221Z","model":"claude-opus-4-8","units":1,
"lane":"deep-research","sku":"anthropic/claude-opus-4-8","provider":"anthropic",
"via":"direct","decision":"154","policy":"9f2c...","routed":true,
"outcome":"served","status":200,"latencyMs":1840,
"inputTokens":11,"outputTokens":3}
```
`decision` is the point of the whole exercise. It is the accepted decision that
put this model on this lane, and it is on the row because a lane cannot enter a
policy without one. [The ledger](ledger.md) is what each field means and how the
file reads back into the register.
## What just happened
The command did four things, and the third is the one worth understanding.
1. It read your register and assembled a policy, refusing to write a partial one
for the reason [`aperture:policy`](../routing/policy.md) refuses: a policy
missing a lane leaves a runtime resolving that alias against whatever it
loaded last.
2. It generated an Ed25519 keypair, used it to sign the policy, and wrote the
file.
3. It started the runtime in a second process, handing it the path and the
public half of that key.
4. It held the key nowhere. The private half was unreachable the moment the
policy was written, and neither half is on your disk, in your environment or
in the output.
**The refusal you did not have to satisfy is still there.** The runtime loaded a
signed document, checked the signature against a key it was pinned by something
other than the file, and would have refused to start if it did not verify. That
is the same check it does on a box, running the same code, and
[Serving a lane](serving.md) is why it is worth anything. What changed is who
holds the key for the ten minutes you are trying this: nobody, for one run.
That is the arrangement the licence already describes. The policy parser and its
canonical form are published under Apache-2.0 precisely so that a policy signed
with your own key verifies against whatever key your runtime pinned, with no
Vitna in the picture at all. This command is that sentence with nobody to type
it.
## What is different from an install
Four things, and none of them is a weakened check.
**The signature is yours, not Vitna's.** The record never saw this key, so it
publishes nothing to compare it against. Verifying the file offline works and
says so:
```bash
npm run aperture:policy -- --verify .vitna/policy.json
```
It reports the lanes, recomputes the digest and checks the signature, then says
the key was not checked, because a signature proves only that whoever holds a
key signed with it. Run it with `DATABASE_URL` set and it also compares that key
against the ones the record has registered, so a record that has registered one
says this file did not come from Vitna. It did not. You signed it.
**Restart it to pick up a change.** A second run signs with a second key, so a
policy it writes is refused by the first run's reload. That is
[fail static](serving.md) doing its job rather than a fault. Stop the command
and start it again.
**Everything lands in `.vitna/`**, which is gitignored. The policy is signed by a
key that no longer exists, and the ledger is a record of requests made from your
machine.
**Nothing is pushed anywhere.** That is not a setting here either. The serving
process holds no code path that reaches vitna.ai, and
[sending closed days to the record](pushing.md) is a separate command you
schedule if you decide to.
## Operator note: benchmarking local throughput
From a checkout too, you can run `scripts/bench-cortex.mjs`, a synthetic
memory-hierarchy and hardware-amortization model (not a live GPU or NVMe timing
benchmark):
```bash
npm run aperture:anchor:bench
```
For real local inference timing and NVMe direct-I/O measurements, run the
`vitna-anchor` binary directly (`generate --timing` and `read-experts` in
`convexityos/vitna-anchor`).
## When you want it for real
[Installing the runtime](installing.md) is the same runtime with the key held
the way a production key is held: generated once, its public half published by
the record and pinned by you out of band, its private half on the signer and
nowhere else. Nothing you learned above stops being true. You stop being the one
who signs.