Capsule
Capsule is an agent-neutral Rust library and CLI for isolated, recoverable code-change attempts — each sealed into a portable, verifiable receipt.
It does not run an agent. It gives any agent or automation system a safe place to work, and it gives everyone downstream — reviewers, CI jobs, merge gates — a durable result whose integrity can be re-checked anywhere with capsule verify, without access to the original workspace, session, or state directory.
pinned Git commit
│
├── capsule A ── ordinary worktree ── sealed patch + provenance
├── capsule B ── ordinary worktree ── sealed patch + provenance
└── primary worktree remains unchanged until explicit integration
A capsule is more than a Git worktree. It records the complete boundary of an attempt:
- collision-resistant identity;
- exact repository and base commit;
- isolated ordinary filesystem path;
- optional links to tasks, runs, agents, or external systems;
- checkpoints created during the attempt, including crash-recoverable checkpoint journals;
- caller-recorded verification evidence;
- complete binary-capable patch, changed-path inventory, and sealed provenance;
- discoverable, streamable artifacts with file URIs and SHA-256 content addresses;
- exported receipts that verify offline, with no capsule state required;
- bounded structured lifecycle audit events and aggregate metrics;
- configurable repository, count, age, size, patch, path, and ignored-content policy;
- a static machine-readable capability contract, plus crash-safe idempotent creation with direct keyed lookup;
- explicit state inspection and backup;
- immutable result digest and drift detection;
- explicit, journaled integration;
- guarded cleanup and crash recovery.
No daemon, VFS, container, shell interpreter, object store, task tracker, model SDK, or agent framework is required.
Contents
- Who can use it
- Install
- Quick start
- CLI reference
- Orchestration protocol — capabilities, idempotent creation
- Policy and operations — policy, state administration, migration
- What a receipt proves
- Merge gate — committed-receipt protocol
- Rust API
- Guarantees
- Scope
- Status
- Documentation
Who can use it
Any process that can consume a path or JSON can use Capsule: interactive coding agents, headless agents, IDE agents, CI jobs, eval harnesses, task trackers, multi-agent coordinators, and custom scripts.
Capsule does not contain adapters for particular agents. This is intentional. The stable integration surface is:
- call the CLI with
--jsonor embed the Rust crate; - give the returned
workspace_pathto the agent as its working directory; - let the agent use its existing file, search, shell, and Git tools;
- record optional evidence;
- close the capsule and inspect, verify, or integrate its result.
The stable handoff surface is the exported receipt: bundle.json, result.json, and result.patch, content-addressed and verifiable by capsule verify on any machine with Git. A harness that emits receipts and a reviewer that checks them never need to share a filesystem, a state directory, or a tool version.
For a complete runnable walkthrough — two competing attempts, sealed receipts, tamper detection, explicit integration — run examples/parallel-attempts.sh.
Install
Prerequisites:
- Git on
PATH; - Rust 1.85 or newer when building from source.
That installs the capsule binary. The crate is registered as change-capsule because capsule was already taken on crates.io; the command you run is capsule.
For library-only use without the Clap CLI dependency:
[]
= { = "0.2", = false }
Quick start
1. Create attempts
Create two independent attempts from the same pinned HEAD:
Each response includes an ID, path, branch, and resolved base commit. Start any agent or command with workspace_path as its current directory.
2. Inspect during work
Each JSON diff response includes canonical lowercase patch_sha256 for the exact live or sealed patch returned (and, with --output, the exact bytes written), so orchestrators can deduplicate only current evidence.
3. Checkpoint (optional)
Checkpoint commits are prepared through a private index, journaled, then atomically advanced onto the capsule branch; recover finishes an interrupted transition:
4. Record evidence
Record verification performed by the caller. Capsule never runs this command; schema-v4 evidence records the SHA-256 of the complete current patch alongside the caller's claim:
5. Seal and export
--require-successful-evidence preserves the legacy policy (some evidence, all exit codes zero). --require-current-successful-evidence instead requires at least one successful claim bound to the exact patch being sealed. Close accepts a result only when two complete ignored-content inventories surrounding the tracked snapshot transaction agree exactly on path identities, byte total, and structural content digest; it uses the final inventory for policy and the sealed result and fails before publication on instability:
artifacts reports media types, byte lengths, file:// URIs, and sha256: content addresses. Artifact readers, publishers, and exports consume one bounded, validated byte snapshot, so later filesystem mutation cannot change the bytes described by that operation. On Unix, bounded sensitive-file reads use no-follow and nonblocking opens before validating the opened descriptor as a regular file, so a FIFO or other special file cannot wedge a read; Windows retains reparse-point-aware opens and post-open checks. export reserves a new destination directory without clobbering, moves in result.json and result.patch, then publishes bundle.json last as the completion marker.
6. Verify the receipt
Verify anywhere — on the same machine, in CI, or after copying ./handoff to a reviewer. Verification needs no capsule state; --repo additionally proves the sealed patch applies to the pinned base and reproduces exactly the sealed bytes and changed paths:
7. Sign the receipt (optional)
Optional authenticity signs the exact exported bundle.json bytes (through a fixed domain-separated SHA-256 commitment) with a raw Ed25519 keypair. Generate matching keys with the OS CSPRNG; both files are exactly 32 raw bytes (the private file is a seed, not PEM/PKCS#8, and the public file is the compressed Ed25519 public key). Key creation publishes the non-secret public key first, never overwrites existing paths, and uses mode 0600 for the private file on Unix. If private publication then fails, the error reports both exact paths and the harmless public file remains for explicit cleanup. The verifier supplies the trusted public key out of band; no key embedded in a receipt is trusted, and Capsule never stores keys in state:
A successful JSON verification reports "signature_authenticated": true only after one exact in-memory bundle.json snapshot passes both authentication and ordinary receipt verification; the CLI never reopens it between checks. Ordinary receipt verification reports false. This proves that the trusted key signed those exact bundle bytes. The bundle descriptors then bind result.json and result.patch. It does not prove that evidence claims were honestly executed, identify a human, protect a compromised private key, or make the producer trustworthy.
8. Integrate and clean up
Integrate only the selected result into a clean worktree that is still at the pinned base:
Cleanup removes only the capsule-owned worktree and branch. Its manifest, patch, result, and evidence remain:
CLI reference
capsule capabilities print the static machine-readable protocol contract
capsule create create an isolated attempt from a resolved base commit
capsule lookup resolve one idempotency key directly, without scanning state
capsule list list durable capsule records
capsule show show the full manifest
capsule path print the ordinary filesystem workspace path
capsule status inspect health, changed paths, commits, and seal state
capsule diff emit the complete current or sealed patch
capsule result show the sealed handoff manifest
capsule artifacts discover sealed artifacts, URIs, sizes, and content addresses
capsule export create a self-describing result artifact directory
capsule keygen generate matching raw Ed25519 private/public key files
capsule sign create an optional detached Ed25519 signature over bundle.json
capsule verify verify an exported receipt offline, optionally against a repository
capsule attest emit an in-toto Statement for a verified receipt
capsule audit show one capsule's events or the administrative event stream
capsule metrics show aggregate lifecycle and storage counters
capsule policy show, replace, or evaluate resource/repository policy
capsule state inspect, back up, or explicitly migrate durable state
capsule checkpoint commit current work with an explicit identity
capsule evidence record externally-run verification evidence
capsule close seal patch, inventory, evidence, and digest
capsule integrate explicitly apply one sealed result to its pinned base
capsule drop safely remove an owned worktree and branch
capsule recover [ID] reconcile all interrupted journals or only one known capsule
--json is global. Errors are emitted as one JSON object on stderr in JSON mode. capsule diff --json returns metadata rather than embedding arbitrary patch bytes; pass --output <file> for patch data. Policy failures use error kind policy; unknown artifact requests use artifact_not_found; idempotency failures use idempotency_conflict and idempotency_not_found, so no consumer has to parse error text.
State defaults to the platform state directory and can be overridden with CAPSULE_HOME or --home. capsule capabilities is the one command that reads neither.
Orchestration protocol
Coordinators, CI and evaluation harnesses, task runners, and multi-agent systems need two things before they can drive Capsule safely: a way to know what this build supports, and a way to retry a creation without ever producing a second attempt.
Capability negotiation
This is a static compatibility probe. It runs before any state or manager initialization, never creates, inspects, locks, canonicalizes, or mutates CAPSULE_HOME, never invokes Git, and succeeds even when --home names a missing, unwritable, malformed, or incompatible state root. Its output is one bounded deterministic JSON object with no timestamps, host paths, or environment-derived values:
Require a protocol version and the subset of feature identifiers you actually use; do not infer behavior from the package version. Feature identifiers are stable versioned strings, unknown identifiers and additive fields are safe to ignore, and removing or redefining an existing identifier requires a new protocol or capability schema version. Every *_bytes limit is a UTF-8 byte count. Capabilities::current() is the Rust equivalent.
Capabilities negotiate protocol compatibility only. They say nothing about whether the binary is authentic, the host is trustworthy, or the state root is usable.
Idempotent creation
Retrying a create after a timeout or crash must not produce a second attempt, and discovering whether the first one succeeded must not require scanning a large multi-agent state root:
An idempotency key is scoped to one canonical state root, compared by exact UTF-8 bytes, and durably bound to one logical creation request and one capsule ID for the lifetime of that record. The same key and the same request always resolve to the same capsule ID; concurrent identical calls create at most one identity and worktree; the same key with a materially different repository, base, label, or links fails with error kind idempotency_conflict before any second capsule or worktree side effect. Repeating a selector — including HEAD — replays the original reservation even after the source branch has moved, so a key is never silently retargeted to a newer commit. Different state roots may use the same key independently.
Keys are opaque local orchestration state, not credentials. Do not put secrets in them: use high-entropy or namespaced values instead. Capsule assigns no meaning to their contents, never stores the raw key as a filename, indexes reservations under a domain-separated SHA-256 digest, and never places idempotency state in a portable receipt — receipts prove result consistency, not who or what produced them.
create without --idempotency-key keeps its existing behavior and JSON response, and idempotent create returns the ordinary capsule JSON shape, so no consumer is forced into a conditional response schema. lookup is non-mutating, reads only the hashed reservation path and the capsule it references, and reports reserved before the manifest exists or materialized with the validated manifest afterwards. It stays usable when unrelated capsule or reservation records are malformed, and returns error kind idempotency_not_found without echoing the raw key.
At-most-one identity is not at-most-once execution: it guarantees Capsule created one attempt, not that an external agent process ran exactly once. A replay can legitimately return a capsule that is already closed, integrated, orphaned, or dropped, so callers still need capsule status, targeted capsule recover <id>, and capsule state inspect. What this does remove is the full-state discovery scan from the normal crash-safe creation path.
Policy and operations
Policy
An absent policy.json means permissive defaults subject to hard safety bounds. Replace policy atomically from a versioned JSON document and evaluate existing state separately:
Policy supports allowed repository roots and optional limits for total/live capsule count, capsule age, state/workspace bytes, result patch bytes, changed paths, ignored paths, and ignored bytes. Result limits apply to the complete base-to-current result, including when a checkpoint contains only a smaller incremental change. Mutating operations fail before their principal side effect when the applicable limit is exceeded. Usage that no configured policy limit references is not measured, except that close always inventories ignored content twice to establish stable sealed provenance. Thus permissive defaults avoid policy-only state/workspace accounting but close still performs its required ignored-content inspection. policy check is observational: it evaluates active and sealed results and reports uninspectable workspaces or artifacts as violations rather than silently treating them as compliant. For example:
State administration
State administration is explicit:
Inspection reads schema/version summaries without requiring supported records, and separately reports the idempotency index: its record count and any malformed entries, identified by indexed digest rather than raw key. Backup requires a new destination and copies durable manifests, results, patches, policy, and the idempotency index in its indexed layout, not live workspaces or Git repositories. Backup publishes backup.json last as its completion marker. An interrupted export or backup may leave a reserved destination without its completion marker; callers should treat it as incomplete and choose a new destination or remove it after inspection.
State migration
Durable state is schema v4. Exported schema-v3 receipts remain verifiable. Existing schema-v3 state must be migrated explicitly; opening it otherwise fails closed. Dry-run validates all candidate manifests/results without writing or reporting a backup, and a backup argument is rejected unless apply is requested. Apply requires a new external backup directory, publishes its backup.json first, then uses an active rollback journal. Migration rejects mixed current/legacy pairs and validates the complete capsule/result seal relationship before backup or writes. After all target writes and syncs, that journal is atomically renamed to a committed-cleanup namespace before deletion, so restart either rolls back active state or only finishes committed cleanup:
Migrated v3 evidence is explicitly unbound (patch_sha256 absent), remains a caller claim, and cannot satisfy current-evidence policy.
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.
Does not prove, and signing does not change this:
- that any recorded evidence command actually ran, or that its output is honest
— Capsule records claims and never executes them, which is why an attestation
calls the field
claimed_evidence; - 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 built on this proves the diff being merged is the diff that
was reviewed and sealed. 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.
Merge gate
A receipt is only useful if something checks it. This repository ships a GitHub Action that verifies a receipt in CI and, with verify-head, refuses the merge unless the tree being merged is exactly the pinned base plus the sealed patch:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # the pinned base must be present
- uses: SiliconState/change-capsule@v0.1.2
with:
bundle: ./receipt # produced by `capsule export`
repo: .
require-successful-evidence: "true"
verify-head: "true"
The gate passes only when every one of these 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;
- evidence exists and every recorded exit code is zero;
- the checked-out tree equals base plus the sealed patch.
Together those mean the diff being merged is the diff that was sealed and verified — established without trusting the machine that produced it. Outputs (verified, capsule-id, base-commit, patch-sha256, changed-paths) are available to later steps, and the run publishes a job summary table.
The same checks run locally with no Action involved:
Committed-receipt protocol
A receipt cannot describe a commit that contains the receipt itself: adding bundle.json, result.json, and result.patch changes the tree. For repositories that commit receipts, use this exact two-commit protocol:
- Create the capsule from the branch base and do all implementation work in its workspace.
- Run verification in that workspace and record the real command and exit code with
capsule evidence. - Close with
--require-successful-evidence, export the receipt, and integrate the sealed result. This creates the implementation commit. - Make one second commit that adds only
receipts/required/bundle.json,result.json, andresult.patch. Do not amend, squash, or add unrelated files. - Push both commits. If the branch is rebased or implementation changes, the old receipt is stale: create a new capsule from the new base and repeat.
The required receipt-gate job in this repository enforces the protocol. scripts/prepare-committed-receipt.sh rejects a dirty checkout, merge commit, malformed receipt path, missing artifact, or any non-envelope change in the tip commit. It checks out the tip's sole parent and identifies that implementation commit's base. SiliconState/change-capsule@v0.1.2 then verifies the committed bundle, successful evidence, exact pinned base, and implementation tree byte-for-byte; pull requests additionally require that pinned base to equal GitHub's current base SHA. Configure this job as a required branch check and use rebase or fast-forward merges that preserve the two commits; a squash merge deliberately destroys this binding.
capsule evidence records a command claim and exit code supplied by the caller; it does not execute the command or provide signed attestation. The gate proves receipt integrity and tree binding, while CI should still rerun security-critical tests independently.
Rust API
use ;
let manager = open_default?;
let mut options = new;
options.label = Some;
let capsule = manager.create?;
// Launch any external tool with capsule.workspace_path as its cwd.
let status = manager.status?;
let result = manager.close?;
# Ok::
Orchestrators additionally get Capabilities::current() for static negotiation, CapsuleManager::create_idempotent(options, key) for crash-safe creation, and CapsuleManager::lookup_idempotency_key(key) — or lookup_idempotency_key_at(state_root, key), which needs no manager — for direct keyed resolution. CreateOptions is unchanged, so existing struct-literal callers keep compiling.
The crate owns lifecycle, provenance, artifact descriptors/streams, policy checkpoints, audit records, and state administration. The caller owns process launch, model choice, prompts, credentials, sandboxing, verification execution, and any remote artifact transport.
Guarantees
- Multiple attempts may start at the same immutable commit.
- Each receives a separate ordinary Git worktree and branch.
- Attempts may change the same files independently.
- The source worktree remains untouched until explicit integration.
- Every result has a complete patch, changed-path inventory, digest, sealed provenance, and discoverable artifact descriptors/streams, and its exported receipt verifies offline on any machine.
- Lifecycle transitions produce bounded structured audit events; aggregate metrics are available without a daemon.
- Repository and resource policy is enforced at core mutation boundaries and can be evaluated against current state.
- Results and journaled checkpoint, integration, and cleanup transitions survive process restart and can be inspected or recovered by another process or agent.
- 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.
- State can be inspected and backed up without a runtime-specific service; exported receipts can be verified with no state at all.
Scope
Capsule owns an attempt boundary, not work planning or agent orchestration.
It composes with issue trackers, agent runners, coding agents, workflow engines, and CI rather than replacing them. An external task ID can be attached with --link; no tracker is privileged or required.
Status
The on-disk capsule/result schema is version 4. Schema-v3 state fails closed until the explicit backup-first migration is applied; exported schema-v3 receipts remain verifiable.
This phase supports Git repositories only. Within that:
- Capsule workspaces disable inherited sparse checkout and materialize a complete checkout even when the source is sparse. Enabling sparse checkout inside the managed workspace remains rejected.
- A private temporary index makes source index
skip-worktreeandassume-unchangedflags irrelevant to snapshots. - Dirty nested submodule worktrees and unregistered embedded Git repositories are rejected rather than silently omitted or converted to accidental gitlinks.
- On Unix, non-UTF-8 inventory paths use
{ "unix_bytes_hex": "..." }; this form requires lowercase canonical hex and cannot encode valid UTF-8, so every path has one JSON identity. - Ignored provenance hashes native Unix bytes for names and symlink targets under a versioned domain; Windows uses native UTF-16LE code units under a distinct platform tag.
- Ignored untracked paths are excluded from the patch but recorded as provenance only after two matching close-time inventories.
Out of scope: remote execution, distributed persistence, background jobs, non-Git snapshots, automatic rebasing, merge queues, network services, complex attestation containers, continuous kernel-enforced quotas, and execution sandboxing.
Documentation
docs/architecture.md— components, state layout, lifecycle, result constructiondocs/protocol.md— the framework-neutral contract for agents and automationdocs/security.md— trust assumptions, protections, and explicit known limitsdocs/composition.md— composing with agents, CI, trackers, and multi-agent systemsdocs/interop.md— in-toto, SLSA, and Sigstore interoperability, and what a receipt provesdocs/releasing.md— the coupled receipt-schema and published-pin release protocol
License
MIT.