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

# Pushing the ledger

Sending a runtime's closed days to Vitna, deliberately, as a command of its
own.

```bash
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](installing.md) from 0.2.0. Inside Vitna, from a checkout of its
private repository, the same file runs as a script, with `--` before its flags:

```bash
npm run runtime:push -- --dry-run
```

From the container it is the same binary behind a different entrypoint, reading
the ledger volume the runtime writes to and the policy it serves:

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

The key comes from Vitna, minted for your organisation and shown once: ask
through the [contact form](https://vitna.ai/start#contact), and
[/console/settings](https://vitna.ai/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`](../routing/usage-import.md) 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`](installing.md) 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:

```bash
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.
Human Machine Shift+M