Pushing the ledger
Sending a runtime's closed days to Vitna, deliberately, as a command of its own.
VITNA_LEDGER=/var/lib/vitna/ledger.jsonl \
VITNA_POLICY=/etc/vitna/policy.json \
VITNA_PUBLIC_KEY=... \
VITNA_PUSH_KEY=vitna_push_... \
vitna-runtime-push--dry-run shapes and prints the payloads with no key and no network. --window 2026-08-24 pushes one day. vitna-runtime-push is on the path of any install from 0.2.0. Inside Vitna, from a checkout of its private repository, the same file runs as a script, with -- before its flags:
npm run runtime:push -- --dry-runFrom the container it is the same binary behind a different entrypoint, reading the ledger volume the runtime writes to and the policy it serves:
docker run --rm --entrypoint vitna-runtime-push \
-e VITNA_LEDGER=/var/lib/vitna/ledger.jsonl \
-e VITNA_POLICY=/etc/vitna/policy.json \
-e VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
-e VITNA_PUSH_KEY="$VITNA_PUSH_KEY" \
-v "$PWD/ledger.jsonl:/var/lib/vitna/ledger.jsonl:ro" \
-v "$PWD/policy.json:/etc/vitna/policy.json:ro" \
ghcr.io/convexityos/vitna-runtime:latestThe key comes from Vitna, minted for your organisation and shown once: ask through the contact form, and /console/settings lists the ones you hold.
Why this is not part of the serving process
The runtime's claim is that it never calls vitna.ai, and that claim survives push being enabled because push is not the runtime: it is this command, reading the same ledger file you could have handed to `aperture:usage:import` by hand, run when you or a timer you installed runs it. The serving process contains no code path that reaches vitna.ai, with telemetry or without, and "off by default, forever" means precisely that nothing schedules this until a person does.
The file path stays the default path. Pushing is the same reading arriving with less typing, not a different kind of reading.
What a run does
- Loads and verifies the policy against the pinned key first, because a push attributes readings to a policy digest, and attributing them to a document nobody signed would launder exactly the provenance the field carries.
- Aggregates the ledger's served units per lane per closed UTC day, maps each lane to its workload through the policy, and posts one payload per day to
POST /api/v1/usage. - Prints what it left out, per reason, because a silent drop is a share that is quietly wrong: today's rows (still open), unrouted passthroughs (no lane to be a reading of), refusals and failures (worth no units), and rows naming a lane the loaded policy no longer carries.
What it holds, and does not
No state. The server keeps one reading per workload per window, so a re-push of a day it already holds answers alreadyStood and costs one request; a pusher that tracked what it had sent would be a second copy of that answer that could drift from it.
No adoption. What lands are readings; whether a workload's incumbent moves stays an operator's act, on the same file, through the import command.
What a push carries
Volume, and the operational figures beside it. Every one is counted exactly, on your machine, from rows the runtime already had, before anything leaves.
| Figure | What it is |
|---|---|
units, windowUnits | Served requests for this sku, and the workload's total that day. Serves only, which is what a share of a window means |
refused, failed | Attempts on this sku that produced no unit. A lane that fails often and a lane that runs little were the same shape in the record before these |
primaryServes, fallbackServes, ruleServes | How those units were reached. A lane serving 95 percent from its primary is a different lane from one serving all of it there |
inputTokens, outputTokens | Summed as the provider reported them. A provider that reported none contributes none, and the sum stays null |
latencyP50Ms, latencyP95Ms | The middle and the tail, exact from the day's own rows. Nothing is sampled: the runtime holds all of them, and an estimator would put a figure in a record that carries none |
No prompts and no responses, ever. The ledger holds none, so a push cannot carry one.
Null is not zero. A figure the runtime could not count is absent, and the record reads that as not reported. A zero would be a claim.
No money. The runtime holds no prices, and a runtime that pushed spend would be freezing a price into telemetry. aperture:reconcile prices a window at the tape's own figures on each day instead.
No quality. That is a measurement with a sample size and a source reference, and it arrives through the door evidence already has.
A refusal that happened before any sku was chosen names none, so there is nothing in the register for it to be a reading of. Those are counted in the run's own summary and pushed nowhere.
Scheduling it
A daily timer after midnight UTC pushes yesterday once it has closed. On a systemd box, a oneshot service running vitna-runtime-push with the four variables, and a timer with OnCalendar=*-*-* 00:20:00 UTC, is the whole of it. A missed run costs nothing: the next one pushes every closed day the record does not already hold.
On Fly, the recipe as it stands installs no push, because a Fly app has no timer and nothing in the recipe's `fly.toml` schedules one. Two things have to be true first. The ledger must live on a volume, or it dies with the machine: the recipe's [[mounts]] block and VITNA_LEDGER line are commented out, and uncommenting both is the step. And the policy must be readable as a file by the pusher, which reads VITNA_POLICY and not the encoded secret. Then push by hand, on the machine that holds the volume:
fly ssh console -C "vitna-runtime-push --dry-run"with VITNA_POLICY and VITNA_PUSH_KEY set for that command. A scheduled Fly machine mounting the same volume is the other way to run it on a timer; this page does not document one yet.
