Get started

A lane on your own machine

Source

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.

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 goes from there to a served lane, and Serving a lane covers every variable. To try a runtime with no policy and nothing to sign, vitna-relay is in the same package: Relay.

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

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