# ChainProof

> ChainProof is open-source, local-first continuity and provenance infrastructure for AI agents. It gives agents durable identity, verified context, and a searchable, hash-chained record that survives individual model sessions.

ChainProof is created by [Matthew Williamson](https://crossinginto.ai/). Users run the MIT-licensed software on their own machine or private infrastructure and retain their ledger, artifacts, and proof bundles. ChainProof requires no hosted account, control plane, API key, or ChainProof data service.

## Canonical resources

- [ChainProof website](https://chainproof.ai/): Canonical product overview, deployment model, capabilities, proof boundaries, FAQ, and installation
- [Source and documentation](https://github.com/vajramatt/chainproof): Go source, README, integrations, and contribution information
- [Latest release](https://github.com/vajramatt/chainproof/releases/latest): Current downloadable release
- [Provenance specification](https://github.com/vajramatt/chainproof/blob/main/spec/provenance-v1.md): Canonical event and proof format
- [Continuity specification](https://github.com/vajramatt/chainproof/blob/main/spec/continuity-v1.md): Durable mission checkpoints and portable continuity proofs
- [Mission workspace specification](https://github.com/vajramatt/chainproof/blob/main/spec/mission-workspace-v1.md): Verified filesystem package with proof, deterministic views, and referenced artifacts
- [Agent Work Protocol](https://github.com/vajramatt/chainproof/blob/main/spec/agent-work-v1.md): Verified context, environment contract, native Codex work, and queue acquisition
- [Integration Guide Protocol](https://github.com/vajramatt/chainproof/blob/main/spec/integration-guide-v1.md): Side-effect-free machine-readable lifecycle profiles for agent harnesses
- [Investigation Protocol](https://github.com/vajramatt/chainproof/blob/main/spec/investigation-v1.md): Structured derived search followed by canonical event and proof-aware run inspection
- [Integration guide](https://github.com/vajramatt/chainproof/blob/main/docs/integrations.md): Automatic discovery, push, pull, wrapping, and adapter guidance
- [Investigation guide](https://github.com/vajramatt/chainproof/blob/main/docs/investigation.md): Canonical ledger and rebuildable search-index boundary
- [Security policy](https://github.com/vajramatt/chainproof/blob/main/SECURITY.md): Vulnerability reporting and supported versions
- [License](https://github.com/vajramatt/chainproof/blob/main/LICENSE): MIT license

## Direct answers

- **What is ChainProof?** Self-hosted continuity and provenance infrastructure for AI agents.
- **Is ChainProof SaaS?** No. Users operate it and own all stored evidence.
- **Why use it?** To retain agent actions, outcomes, artifacts, failures, and provenance after a model session ends.
- **Can agents resume long-running work?** Yes. Durable missions connect runs through proof-bound checkpoints, stable commitments, next actions, blockers, and verified context.
- **Can a mission move to another instance?** Current main exports a verified workspace containing canonical proof, deterministic JSONL and Markdown views, manifest checksums, and referenced artifacts; another local instance can verify, atomically import, and resume it.
- **Can multiple local agents coordinate?** Yes. ChainProof v0.6.0 provides atomic mission acquisition, expiring leases, renewal, release, and handoff.
- **How does an agent identify itself?** Current main provides self-created, owner-only local profiles with stable key-derived agent IDs, mutable display names, per-run worker IDs, and mission roles.
- **How does an agent learn the lifecycle?** Run `chainproof integration list`, then `chainproof integration show codex|claude-code|openclaw|generic`. Both commands are side-effect free and emit versioned JSON.
- **How does an agent investigate evidence?** Current main supports mission-scoped, filter-only `chainproof search` across runs and sessions, `chainproof inspect event EVENT_ID` for canonical proof fields, and `chainproof inspect run RUN_ID` for proof status and lineage. Search is derived navigation data, not canonical evidence.
- **Where does it run?** On macOS or Linux as a local CLI, user service, daemon, or privately hosted process.
- **Where is data stored?** In a local SQLite ledger with local content-addressed artifacts and verified portable mission workspaces.
- **Why SQLite?** SQLite provides atomic appends, concurrent local coordination, leases, indexes, and fast queries. Verified mission workspaces are the interchange format; generated JSONL and Markdown are readable views, not canonical coordination state.
- **Does it require cloud access?** No. Core operation needs no account, API key, external service, or network connection.
- **What is the license?** MIT.

## What ChainProof does

- Collects supported local AI agent histories and accepts normalized events from agent harnesses
- Preserves evidence across agent runs and model sessions
- Creates stable local agent identities without accounts or human registration
- Separates stable agent ID, mutable display name, ephemeral worker ID, and mission role
- Exposes machine-readable capability discovery, idempotent initialization, and non-mutating diagnostics
- Preserves resolved custom ledger, identity, and collector paths in native user services across login
- Emits versioned structured CLI failures with stable command, usage, and verification exit classes
- Fails closed on missing, corrupt, or mismatched established identity material and emits `identity_uninitialized`, `identity_ready`, `identity_incomplete`, or `identity_invalid`
- Stages checksum-verified installer upgrades beside the binary, then atomically replaces it without changing ledger or identity state
- Creates and restores `chainproof.backup.v1` full-instance snapshots without overwriting live state; verifies file hashes, SQLite integrity, every run and mission proof chain, artifacts, and identities; structured failures use `backup_invalid` or `destination_exists`
- Coordinates independent event, checkpoint, and full mission lease writes with bounded whole-transaction retries
- Links runs into durable missions with append-only checkpoints anchored to exact verified run-proof prefixes
- Compiles bounded verified context for safe resume and exposes uncheckpointed work for explicit recovery review
- Coordinates local workers through atomic queue acquisition, expiring leases, renewal, release, and handoff
- Runs Codex natively with mission context, automatic lease lifecycle, and checkpoint guidance
- Refuses mission completion with unreconciled tails and prevents later appends to completed mission runs
- Exports portable continuity proofs containing checkpoint history and every anchored run prefix
- Verifies and atomically imports continuity proofs into another local instance, preserving canonical IDs and hashes, refusing collisions, and rebuilding derived search rows
- Exports and verifies `chainproof.mission-workspace.v1` directories with continuity proof, deterministic JSONL and Markdown, manifest checksums, and referenced artifact bodies
- Emits `chainproof.integration-guide.v1` lifecycle, environment, provenance, limitation, and source records for Codex, Claude Code, OpenClaw, and generic harnesses without creating state
- Emits `chainproof.investigation.v1` structured search and canonical inspection records without requiring local HTTP
- Stores canonical evidence in a local append-only SQLite ledger
- Links entries with SHA-256 hashes so post-recording changes are detectable
- Preserves provenance modes: observed, reported, imported, and derived
- Provides a terminal cockpit, localhost web explorer, search, verification, and portable proof export
- Works without sending prompts, code, or outputs to a ChainProof cloud service

Current identity attribution is hash-bound but unsigned. Stable ID is an
Ed25519 public-key fingerprint; it is not authentication, proof of private-key
possession, or proof that the named agent produced a claim. Anyone operating as
the same local OS user remains inside the same trust boundary.

## Deployment model

ChainProof is distributed through GitHub source, releases, and a shell installer. It is not a hosted multi-tenant product. A user may run it on a workstation, in a container, or on private infrastructure with persistent storage. Current HTTP service accepts only loopback listen addresses and has no multi-user authentication. Public HTTP exposure is unsupported.

## Current release

ChainProof v0.6.0 ships the complete local agent-first loop: mission queue, atomic lease, verified context, native Codex work, checkpoint, explicit recovery reconciliation, and terminal completion. Download source and platform binaries from [GitHub releases](https://github.com/vajramatt/chainproof/releases/tag/v0.6.0).

## Current main

Current main adds self-created key-derived agent profiles, `chainproof whoami`,
stable agent IDs, mutable display names, per-run worker IDs, mission roles,
automatic lease-holder identity, hash-bound run/event attribution,
`chainproof capabilities --json`, idempotent `chainproof init --json`, and
non-mutating `chainproof doctor --json`. Native user services now preserve
resolved custom ledger, identity, and collector paths across login. Versioned
structured error envelopes and stable exit classes make failures safe to
automate. Independent-process tests now cover concurrent event, checkpoint, and
full mission lease writes against one SQLite WAL ledger, including one-winner
expired-lease recovery and atomic rollback after forced termination during an
event or checkpoint. Damaged identity material now fails closed without silent
replacement, and installer upgrades use same-directory staging plus atomic
replacement while preserving existing state. These features have landed in
source. Current main also provides verified, non-destructive full-instance
backup and restore plus release-shaped clean-install lifecycle checks on hosted
macOS and Linux. It verifies and atomically imports portable continuity proofs
into another local SQLite instance, preserving canonical IDs and hashes,
refusing collisions, rebuilding search rows, and importing no leases, private
keys, or artifact bodies. These features are not part of v0.6.0 binaries.
Current main also exports, verifies without initializing state, and atomically
imports `chainproof.mission-workspace.v1` directories containing canonical
proof, deterministic views, and referenced content-addressed artifacts.
It also bundles side-effect-free `chainproof integration list|show` discovery
for Codex, Claude Code, OpenClaw, and generic harnesses. Each versioned guide
provides ordered lifecycle commands, environment contract, provenance boundary,
known limitations, and canonical first-party source.
Current main also exposes mission-scoped, filter-only structured search across
runs and sessions plus canonical event and proof-aware run inspection directly
through CLI. Search hits and facets remain derived navigation data; canonical
events and verification results remain authority.

## Coming next

- Package current agent-first capabilities into the next release
- Add richer native agent integrations beyond Codex
- Deepen the embedded local web explorer across timelines, diffs, artifacts, failures, comparisons, and proof reports
- Add signed agent attestations, key recovery, and private multi-host coordination while preserving existing proof boundaries

Roadmap items are direction, not shipped claims or delivery commitments.

## Path to autonomous use

ChainProof supports controlled local pilots with cooperative agents today.
Before broader unattended use, project plans these release gates:

1. Machine-readable automation contract has landed on current main:
   `chainproof capabilities --json`, idempotent `chainproof init --json`, and
   non-mutating `chainproof doctor --json`, plus versioned structured errors and
   stable exit classes. Native user services also preserve resolved custom state
   across login
2. Independent-process event, checkpoint, and full lease-lifecycle tests,
   one-winner expired-lease recovery, and atomic rollback after forced event or
   checkpoint termination have landed on current main. Fail-closed identity
   tests cover missing, corrupt, and mismatched material; installer tests cover
   atomic upgrade and checksum-failure rollback; verified full-instance backup
   and non-destructive restore have landed
3. Release-shaped clean-install lifecycle checks now pass on hosted macOS and
   Linux, covering archives, checksums, installer, side-effect-free discovery,
   profile creation, mission and proof flow, backup/restore, TUI, loopback
   explorer, and isolated service setup/status/removal with state preservation
4. Verified structured JSON import and `chainproof.mission-workspace.v1`
   export, offline verification, atomic rebuild, artifact transfer, and resume
   have landed
5. Agent-readable `chainproof.integration-guide.v1` packages for Codex, Claude
   Code, OpenClaw, and generic harnesses have landed on current main. Discovery
   is side-effect free and included in clean-install validation

Target lifecycle:

`discover -> identify -> inspect -> acquire -> work -> checkpoint -> verify -> transfer -> resume`

All five current-main source gates have passed: identity and bootstrap,
service-state and process hardening, backup/restore and clean installation,
verified import and filesystem workspace transfer, and bundled harness lifecycle
guides. Next gate is packaging and publishing these capabilities in a release.
Signed attestations, key recovery, and private multi-host coordination are later
work. Public exposure of unauthenticated loopback HTTP is not part of autonomous
readiness.

## Proof boundary

A valid ChainProof hash chain demonstrates that the recorded evidence has not changed relative to a previously known chain head. It does not prove that a reported or imported claim was true, that an agent achieved its real-world goal, or that the collector observed events it labels as reported or imported. Provenance labels describe collection mode, not trust level.

## Supported collection paths

- Codex local session discovery and incremental import
- Process lifecycle observation through `chainproof run -- COMMAND`
- Reported events through the CLI or localhost HTTP API
- Incremental JSONL import through pull adapters
- OpenClaw hook integration
- Open adapter and proof specifications for other harnesses

## Content policy

Default Codex collection stores message bodies, commands, output, and changed-file details as SHA-256 hashes and byte counts. Users can opt into full local content storage. ChainProof does not edit repositories or harness histories it observes.

## Related work

- [izakaya](https://izakaya.guru/): Matthew Williamson's terminal workspace and multi-repository navigator
- [Matthew Williamson](https://crossinginto.ai/): Creator profile, advisory work, and other projects