A claim task gives an agent one of TVA's fixed claims (claims/<kernel>/) and asks for a Lean proof of
theorem main : claim.Holds. A machine check grades the proof (tva-check): reward 1 when it passes, 0
otherwise. The task runs in the Harbor framework: the agent (Claude Code) works in one container, and a
verifier checks the proof in another.
| Path | What |
|---|---|
build_base.sh, base/Dockerfile |
the base image tva3-base:<hash>: the Lean toolchain, Mathlib and the TVA library, built |
lean_hash.py |
<hash>: a content hash of lean/'s source (lakefile, manifest, toolchain, TVA.lean, TVA/**.lean) |
claim/build.sh, claim/Dockerfile |
the claim image tva3-claim:<hash>-<sub>, on the base: harness, docs, example, tool |
claim/tva-check |
the one tool: check, grade, verify, prepare, time, and the prover's hooks |
claim/CLAUDE.md, claim/settings.json, claim/lean-fixer.md |
the prover's harness: how to work, the hooks, a subagent |
claim/process_safety.md |
what the prover must never kill |
claim/lake |
the build lock in front of the toolchain's lake (one build at a time; readers share) |
claim/oracle.py |
writes a claim's oracle proof (claims/<kernel>/oracle/) where it is used: a task's solution/ (make_task.py --oracle), and the worked example vec_add_f32 in the claim image |
claim_files.py |
the allow list of a claim's files that reach a prover: Claim.lean, claim.json, README.md, SETUP.md, source/ (never oracle/ or check_gpu.py) |
make_task.py |
writes the Harbor task tva3-claim-<kernel>/ and a script that runs it once |
harness/cc_agent.py |
the Harbor agent ClaudeCodeClaim: Claude Code, resumed after an error exit |
meter_relay.py |
the prover's only way out: a TCP relay from the task's sealed network to the meter, one port |
meter.py |
the credit meter: a proxy on the host that records each request's tokens and cost, stops at a budget, and keeps the endpoint's key out of the containers |
/app/claim/ the task's claim (each task adds it); the agent writes Proof.lean and Proof/ here
/app/examples/vec_add_f32/ the worked example: a fixed claim with its complete proof (checked at build)
/app/lean/ the TVA library with Mathlib, built (lakefile: TVA, and ClaimTask = /app/claim)
/app/docs/ TVA's docs, as they were when the image was built
/app/CLAUDE.md, /app/.claude/ the harness; the agent starts in /app, so Claude Code loads both
/process_safety.md what never to kill; each task adds /instruction.md (the task)
/usr/local/bin/tva-check the tool; /usr/local/bin/lake, the build lock
tva-check check /app/claim checks the workspace (Claim.lean, claim.json with claim_sha256 and
namespace, the prover's Proof.lean and Proof/**.lean):
Claim.leanis the claim (its sha256);- the proof files pass the hygiene list: no
sorry/admit/axiom/native_decide, nounsafe,implemented_by,externor other kernel bypass, no meta code (macro,syntax,elab,#eval, …), nonotation, nolocal/scopedinstance, noset_optionbutmaxHeartbeats,maxRecDepth,synthInstance.maxHeartbeats; imports onlyTVA,Mathlib,Claim,Proof(matched on the whole text, comments included); lake build Claim Proofsucceeds;theorem tva_check : TVA.Claim.Holds <ns>.claim := <ns>.mainelaborates and#print axiomsshows onlypropext,Classical.choice,Quot.sound;- Lean's kernel re-checks every declaration of
Claimand of each proof module (Proofand theProof/modules it imports) from the compiled files, one module at a time (claim/replay.lean: leanchecker's replay, run per module, so memory stays that of one module however many the proof has).
grade deletes the proof's build outputs, builds afresh and checks within the grader's limit (1 h); verify
writes /logs/verifier/reward.json. The hooks: SessionStart starts the clock and, after a compaction, shows
/tmp/plan.md again; PreToolUse refuses changes to Claim.lean/claim.json and runs subagents in the
background; PostToolUse reminds of the time (50%, 75%, 90%, 30 and 10 min left); Stop runs the check and
holds the agent until it passes (or until eight stops in a row with the proof unchanged).
Every claim keeps its oracle proof (claims/<kernel>/oracle/), and a prover sees none of them but the worked
example's:
- a task's two images (the prover's and the verifier's) get the claim's own files only, through
claim_files.py's allow list (Claim.lean,claim.json,README.md,SETUP.md,source/); the copy stops on any other file; - the oracle goes only to the task's
solution/(--oracle), which Harbor gives to itsoracleagent alone, never to an agent's container; - the claim image holds one proof,
vec_add_f32's, at/app/examples/vec_add_f32/; itsdocs/name no other proof; - the prover's container reaches no network but the meter: it is only on a sealed Docker network (
internal, no route to the internet or the host) whose one other member,meter(meter_relay.py), relays one port to the credit meter on the host. The task'senvironment/docker-compose.yamlsets this up, and the run script gives the relay the meter's address. The verifier runs with no network at all.
Harbor 0.25.0 (pip install harbor==0.25.0) and Docker are needed. Generated tasks and Harbor's job folders
go outside TVA's tree (make_task.py refuses a folder inside it): run from a work folder elsewhere.
TVA stands for TVA's root.
# 1. the images (the base takes about 10 minutes, 11 GB; nothing is downloaded but Ubuntu's packages,
# Claude Code and its Node in the task image). build.sh builds the base first when it is missing, and prints
# the claim image's tag. The library must build, and the example's proof must pass the check.
$TVA/sandbox/build_base.sh # optional: tva3-base:<hash>
$TVA/sandbox/claim/build.sh # tva3-claim:<hash>-<sub>
# 2. tasks (default: the newest tva3-claim image), and one run script per task
python3 -I $TVA/sandbox/make_task.py softmax_f32 matmul_f16 --out tasks --runs runs \
[--agent-timeout 28800] [--model <model-id>] [--budget 25] [--context-window 640000] [--oracle]
# 3a. plumbing: the oracle (every claim has one, claims/<kernel>/oracle/) → reward 1 (vec_add_f32: about 3 minutes)
python3 -I $TVA/sandbox/make_task.py vec_add_f32 --out tasks --oracle
harbor run -p tasks/tva3-claim-vec_add_f32 -a oracle -e docker -o jobs
# 3b. an agent, through the meter (the run script does all of this; see below)
KEY_FILE=<file with the endpoint's key> tasks/run-tva3-claim-softmax_f32.shOptions of make_task.py: --out (default tasks), --runs (default runs), --image, --oracle,
--agent-timeout (8 h), --model (default DeepSeek V4.1 Flash on Fireworks), --budget (the meter's cap for
one run, $25), --upstream and --price (the endpoint and its dollars per million uncached input, cached input
and output tokens), --context-window (640 000: the window Claude Code assumes and compacts at; keep it below
the model's context length, with a margin), --cpus, --memory-mb.
run-tva3-claim-<k>.sh starts the meter on the host, runs Harbor with the claim agent through it, and prints the
spend. By hand:
python3 -I $TVA/sandbox/meter.py serve --upstream https://api.fireworks.ai/inference \
--key-file <file with the key> --price 0.30,0.006,1.20 --ledger runs/k/meter.jsonl --budget 25 --port 18800 &
K=$(cat runs/k/meter.jsonl.client-key); H=<the host's address, as the containers reach it>
ANTHROPIC_BASE_URL=http://$H:18800/prover ANTHROPIC_API_KEY=$K PYTHONPATH=$TVA/sandbox/harness \
harbor run -p tasks/tva3-claim-<k> -a cc_agent:ClaudeCodeClaim -m anthropic/<model-id> -e docker -o runs/k/jobs
python3 -I $TVA/sandbox/meter.py report runs/k/meter.jsonl # at any time: requests, tokens, costSafety rules.
- The endpoint's key (the Fireworks token) stays on the host: only the meter reads it (
--key-file). Never put it in a container, a task, a URL, a log or a commit, and never print it. The containers get only the meter's own client key (<ledger>.client-key, mode 600), which works nowhere else, and the meter refuses requests from outside the private address ranges. - Run every experiment through the meter, with a budget: at the budget it answers HTTP 402 and the agent stops. The ledger is the account of a run's spend (the provider's billing covers the whole account and lags; Claude Code prices its own use at Anthropic's rates).
- Docker's disk is shared: remove the images you build for a test (
docker rmi, no-f), and never touch other users' images or containers. - Launch long runs detached (
setsid nohup …), so that they outlive the shell that started them.
ClaudeCodeClaim resumes the session (claude --resume, at most 3 times) when a run ends on an error rather
than with the agent's last turn, and logs each run's exit in /logs/agent/cc-runs.txt.
In Harbor's job folder (runs/<task>/jobs/<job>/<trial>/):
verifier/reward.json:{"reward": 1}or0;verifier/details.json: each of the five checks, PASS or FAIL, with its detail;agent/claude-code.txt: the agent's transcript (stream JSON),agent/cc-runs.txt: each run's exit;artifacts/app/claim/: the graded proof (Proof.lean,Proof/).
meter.py report runs/<task>/meter.jsonl gives the run's requests, tokens and cost.