Capsule
An agent wrote a patch and says the tests pass. Prove it — on a different machine, with no access to the one that made it.
Capsule gives an agent an isolated Git worktree to work in, runs the verification command itself, and seals the whole attempt into a directory of three files. Anyone with that directory can re-derive the result from scratch.
Why not just push a branch?
Because a commit SHA proves the tree exists, not that anything checked it, and it only works if the producer and the reviewer share a remote.
The deeper reason is that a source change can be re-derived and a build artifact cannot. in-toto and SLSA exist because nobody can cheaply recompute a compiled binary from its inputs, so a verifier checks signatures over a producer's claims instead. A patch is different. Apply it to the pinned base and you get the tree back, byte for byte:
apply(sealed patch, pinned base) == the tree being merged
That is a reproduction check, not a trust check. It holds when every signature is absent, every key is unknown, and the producing machine is assumed hostile. So Capsule carries the patch itself and lets you recompute, rather than asking you to believe a digest.
The second half is evidence. capsule evidence <id> -- cargo test spawns the
program directly in the capsule workspace and records the exit code and a digest
of the output it observed. The receipt marks that record executed: true. A
verifier can then demand it:
| Establishes | You must trust | |
|---|---|---|
| The patch reproduces the tree | Recomputed by anyone | Nothing |
| Executed evidence passed | The command ran and passed | The producing host |
| A caller's claim passed | Someone said so | The producer, entirely |
| A signature over the receipt | Who produced it | Your out-of-band key |
Capsule never blurs those rows. Evidence it did not run is stored as
executed: false and can never satisfy --require-executed-evidence.
Where this earns its keep
Evaluation harnesses. Run N candidate patches from one pinned base. Each
gets its own worktree and index, so candidates never race on a shared checkout.
Each seals into a comparable, independently verifiable result. Attach dimensions
with --link eval=parser-v2 --link candidate=model-a --link sample=184.
Handoff across a trust boundary. A contractor, a partner team, an autonomous agent, or an air-gapped run produces a receipt. You verify it without their branch, their remote, their state directory, or their word.
If your agent just pushes a branch to a repository you already control, Git already does most of this. Use Capsule when the producer and the verifier do not share trust or infrastructure.
Install
Needs Git on PATH, and Rust 1.85+ to build from source.
The binary is capsule. The crate is change-capsule because capsule was
taken. For library use without the CLI:
= { = "0.3", = false }
Use it from an agent
The integration surface is small on purpose:
- call the CLI with
--json, or embed the Rust crate; - give the returned
workspace_pathto the agent as its working directory; - let the agent use its own file, search, shell, and Git tools;
- have Capsule run the verification command;
- close, export, verify, integrate.
There are no per-agent adapters, and none are needed: anything that can spawn a process and read JSON can drive the whole loop.
Walkthrough
examples/parallel-attempts.sh runs the
complete story end to end: two competing attempts from one base, executed
evidence, sealed receipts, tamper detection, explicit integration, cleanup.
pinned Git commit
│
├── capsule A ── ordinary worktree ── sealed patch + provenance
├── capsule B ── ordinary worktree ── sealed patch + provenance
└── primary worktree untouched until explicit integration
Merge gate
- uses: actions/checkout@v4
with:
fetch-depth: 0 # the pinned base must be present
- uses: SiliconState/change-capsule@v0.3.0
with:
bundle: ./receipt
repo: .
require-executed-evidence: "true"
verify-head: "true"
The gate passes only when all of this holds:
- the bundle's artifacts match their descriptor digests and byte counts;
- the sealed result is internally consistent and its schema is supported;
- the pinned base exists in the checkout, and the sealed patch applies to it, reproducing exactly the sealed bytes and changed paths;
- Capsule itself ran a command that passed against that exact patch;
- the checked-out tree equals base plus the sealed patch.
Run the same checks locally with
scripts/verify-gate.sh --bundle ./receipt --repo . --require-executed-evidence.
Capsule does not commit receipts into the repository, and does not ask you to change how you merge.
What a receipt proves
Stated plainly, because "verifiable AI code" claims more than anything can
deliver. Every attestation carries this same list machine-readably under
predicate.proof_boundary.
Proves, recomputable by anyone holding the receipt, trusting nothing:
- the patch bytes match their sealed digest and byte count;
- the patch applies to the pinned base and reproduces exactly the sealed bytes and changed paths;
- with
--verify-head, the tree being merged is base plus that patch; - with a signature, a specific out-of-band key signed those exact bundle bytes.
Also proves, if the receipt carries executed evidence, but only as far as you trust the machine that produced it:
- the recorded command ran in the capsule workspace, and Capsule observed that exit code and that output digest.
Does not prove, and signing does not change this:
- that a
executed: falserecord ever ran — that is a caller's assertion; - who or what wrote the change;
- that the change is correct, safe, reviewed, or good;
- that the producing host was uncompromised.
So a merge gate on this proves the diff being merged is the diff that was
sealed, and it passed a command Capsule ran. That is an integrity control, not
a quality control. Keep running your own tests. If you already use in-toto,
SLSA, or Sigstore, capsule attest emits a standard in-toto Statement — see
docs/interop.md.
CLI
capsule create create an isolated attempt from a resolved base commit
capsule list list durable capsule records
capsule show show the full manifest
capsule path print the workspace path
capsule status inspect health, changed paths, commits, and seal state
capsule diff emit the complete current or sealed patch
capsule checkpoint commit current work with an explicit identity
capsule evidence run a verification command, or record a caller's claim
capsule close seal patch, inventory, evidence, and digest
capsule result show the sealed handoff manifest
capsule artifacts discover sealed artifacts, URIs, sizes, and content addresses
capsule export write a portable receipt directory
capsule verify verify a receipt offline, optionally against a repository
capsule attest emit an in-toto Statement for a verified receipt
capsule keygen generate matching raw Ed25519 key files
capsule sign create a detached Ed25519 signature over bundle.json
capsule integrate apply one sealed result to its pinned base
capsule drop safely remove an owned worktree and branch
capsule recover reconcile interrupted journals
capsule capabilities print the static machine-readable protocol contract
capsule lookup resolve one idempotency key without scanning state
--json is global. In JSON mode, errors are one object on stderr carrying a
stable kind, so no consumer parses error text. State lives in the platform
state directory, overridable with CAPSULE_HOME or --home.
Evidence, in both forms
# Executed: Capsule spawns the program. No shell, so no quoting surprises.
# Claimed: for a run Capsule could not perform, such as one on other hardware.
# This can never satisfy --require-executed-evidence.
close and verify accept three independent evidence requirements, not a
ladder. --require-executed-evidence is the one to use: it asks for a record
Capsule ran itself, that passed, bound to the patch being sealed.
--require-successful-evidence asks something quite different — that every
record passed — so it rejects an attempt whose tests failed once and were then
fixed. That is rarely what you want, and it is off by default in the Action.
Crash-safe creation
An orchestrator that can time out or restart should pass an idempotency key.
The same key always resolves to the same attempt, and lookup answers "did my
earlier call already create this?" without scanning a large state root:
Keys are opaque local orchestration state, not credentials. Do not put secrets in them. They never appear in a receipt.
Signing
Optional authenticity over the exact exported bundle.json bytes, with a raw
Ed25519 keypair. The verifier supplies the trusted key out of band; no key
inside a receipt is ever trusted:
Rust API
use ;
let manager = open_default?;
let capsule = manager.create?;
// Launch any external tool with capsule.workspace_path as its cwd. Then have
// Capsule run the verification command, so the result is observed, not asserted.
manager.add_evidence?;
// Sealing refuses to proceed unless that command passed on this exact patch.
let result = manager.close?;
manager.export_artifacts?;
// Anywhere else, holding only ./receipt and a clone of the repository:
let report = verify_bundle?;
assert_eq!;
The crate owns the attempt lifecycle, provenance, artifacts, and receipts. The caller owns process launch, model choice, prompts, credentials, and sandboxing. The workspace isolates Git state; it is not a security sandbox. Run untrusted code under an external sandbox.
Guarantees
- Many attempts may start at the same immutable commit, each with its own worktree and index, and may change the same files without interfering.
- The source worktree stays untouched until explicit integration.
- Every result carries a complete patch, changed-path inventory, digest, and sealed provenance, and its receipt verifies offline on any machine.
- Evidence records whether Capsule ran the command. That flag cannot be forged through the API, and a verifier can require it.
- Journaled checkpoint, integration, and cleanup transitions survive process restart and can be recovered by another process.
- Missing, replaced, drifted, or unrepresentable workspaces fail closed.
- Cleanup refuses foreign directories even with
--force. - Integration is explicit and requires a clean target at the exact pinned base.
Scope
Capsule owns an attempt boundary. It does not plan work or orchestrate agents, and it composes with the tools that do.
Within Git repositories: capsule workspaces disable inherited sparse checkout; a
private temporary index makes skip-worktree and assume-unchanged irrelevant
to snapshots; dirty submodules and unregistered embedded repositories are
rejected rather than silently omitted; non-UTF-8 inventory paths use a canonical
{ "unix_bytes_hex": ... } form; ignored untracked content is excluded from the
patch but recorded as provenance after two matching close-time inventories.
Out of scope: remote execution, distributed persistence, background jobs, non-Git snapshots, automatic rebasing, merge queues, network services, resource quotas, and execution sandboxing.
Status
Durable state and receipts are schema v5. Earlier schemas are not read; this crate is young enough that carrying migration machinery costs more than it saves.
docs/architecture.md— components, state, lifecycledocs/protocol.md— the contract for agents and automationdocs/security.md— trust assumptions and known limitsdocs/composition.md— composing with agents and CIdocs/interop.md— in-toto, SLSA, and Sigstore
License
MIT.