The work, documented.
Grant a mandate. Put an agent to work. Keep the proof. This page holds everything you need to do all three.
for your agent · paste it into Claude Code, Codex, or the agent you use
Read Runa's docs: https://runacode.io/docs
My project: [describe it: stack, repo, what you want agents to do]
Context, so you answer precisely. Runa runs agents that do real work under an exact mandate: real machines with CPU or GPU, scoped permissions, a spend cap, credentials the agent can use but never see, output versioned on Ruhub, every action sealed on the Ring0 record. Install: npm install -g runa. One run: runa run "<task>". SDKs: from runa import run (Python), import { run } from "runa" (TypeScript).
Answer three things, concretely:
1. Which tasks in my project should become agent runs.
2. The mandate to grant each one: permissions, budget, time, approvals.
3. My first command: the exact runa run line to start with.01
What Runa is
Runa runs agents that do real work — code, files, services, payments — with exactly the authority you grant and nothing else. Five things, in one breath: a machine to work in, a mandate that bounds it, a gate that answers it, a vault that keeps what it made, a record that proves what it did.
Give agents the work, never the keys.The work ends. The proof remains.
02
Quickstart
Install the runner once.
npm install -g runaThen state the task. One command opens the run.
$ runa run "fix the login bug"Before anything moves, Runa shows you the mandate it needs — which repository, which branches, how much to spend, for how long. Trim it, grant it, and the agent begins. When it ends, you hold the record.
03
Sessions
The work happens in a session: an isolated machine the agent works in — its own files, its own tools, its own clock. You choose the kind; the kind serves the task.
ephemeralOne task, then gone. Nothing lingers.persistentState kept between visits. Pause it; resume it; it remembers.scheduledSleeps until its hour — or until the event that wakes it.parallelSeveral sessions from one starting point. Compare the results; keep the best.
A session lives a plain life. When the task asks for more, grant more: more power, more memory, more time.
Open
The session starts from your workspace, mounted from Ruhub. It may open a temporary service — a door that lives only as long as the session does.
Pause, resume
A persistent session holds its state between visits. Stop it tonight; it continues tomorrow, mid-thought.
Checkpoint, fork
Seal a point you can return to. From one checkpoint, several sessions — run them side by side, judge the results, keep one.
Close
The session ends. What it made moves on — chapter 06.
- session/
- workspace/# the active project, mounted from Ruhub
- src
- tests
- service# temporary — dies with the session
04
The mandate
The mandate is the whole of the agent's authority: a few lines, granted before the run, held for its duration, expired after it. What the mandate does not name, the agent cannot do.
- readthe repositories and files it may open
- writethe branch pattern it may touch — agent/*, never main
- runthe commands it may execute — tests, builds
- spendthe budget ceiling — a number, not a promise
- expirethe hour the authority dies on its own
- everything elserefused, recorded, visible
read runa/billingwrite agent/*run test suitespend $2.00expire 3h
Within the mandate, two speeds. Some actions are pre-authorized inside their bounds; some are asked, one by one.
05
The run
Each sensitive action leaves the session as a question: may I? Every question walks the same path, and the path is short.
The agent asks
The action leaves the session as a request — named, scoped, priced.
The rules answer
Allowed or denied, by the mandate as granted. No answer is silent.
A guarded worker acts
The worker holds the credential; the agent never sees it. It performs the allowed action — and only that.
The receipt is filed
A verified activity record, written as it happens.
14:02:11 read runa/billing ✓14:02:36 write agent/retries ✓14:02:58 spend $0.12 ✓14:03:15 read secrets/.env ✕ denied14:03:40 run tests · 214 ok ✓
06
The work survives
The session ends; the work does not. Approved results return to Ruhub, versioned, with their full lineage. Large artifacts persist in the artifact vault — CHITA, internally — which outlives the session that made them.
- ruhub/
- billing @ v42# approved · versioned · lineage kept
- vault/
- test-report · r-0142# durable — outlives the session
Lineage is the chain of custody, and it is unbroken: which version went in, who worked on it, under what authority, and who said yes.
input billing @ v41task fix the login bugagent run r-0142mandate write agent/* · spend $2.00 · expire 3hactions 5 asked · 4 allowed · 1 deniedartifact billing @ v42approval granted — sealed
07
Private computepreview
Some questions belong to several parties at once. Three lenders hold three ledgers; they need one answer — does this pattern appear in all three — and none may show the others its books. Private compute produces the one approved answer (a cooperative protocol, HSS-CoFHE, in preview): a similarity, a score, a statistic. Each party keeps its data. All receive the answer. ring0 defines who participates, what runs, and who sees the output.
08
The record
When the run ends, the record is sealed: the task, the mandate as granted, every action asked and answered, the spend, the artifacts, the lineage from workspace to proof. It is not a log you scroll — it is an object you keep.
task fix the login bugmandate read runa/billing · write agent/* spend $2.00 · expire 3hactions 5 asked · 4 allowed · 1 deniedspend $1.34 of $2.00 — $0.66 returnedtests 214 okartifact billing @ v42 · in the vault
The record lives on ring0 (in its ledger store, MLE-DB) — permissions, budgets, spend, receipts, artifact identities and their history. It follows you, not the machine. Every run pays its own way and returns what it did not use.
You do not wonder what the agent did. You read it.
09
Honest boundaries
Trust is the product, so the boundary is stated. Runa verifies authority, actions, budget, receipts, and state. It does not verify truth.
do
- Trust who granted the authority, and what was granted.
- Trust that each action matched the mandate — or was refused.
- Trust that the budget held, and where the spend went.
- Trust the receipts, and how state changed.
don't
- Assume an answer is true because the run was clean.
- Assume generated code is free of bugs — read it, test it.
- Assume a normal session hides your data from the machine's operator.
10
ring0 & Ruhub
The rules do not live in Runa's hands, and not in the agent's. They live on ring0, where they are public, and where the proof of every run is kept. Ruhub holds the work — projects, versions, lineage. Runa executes between them.