Expand description
§blackbox
Local flight recorder and debugger for supervised processes — especially
AI coding agents. The crates.io package is blackbox-recorder;
the library crate and CLI binary are both named blackbox.
§What the library does
- Supervise a child under a PTY (
run) - Merge capture layers (terminal, git, filesystem, process)
- Redact secrets before write (default)
- Persist ordered
TraceEvents in SQLite + content-addressed blobs - Expose analysis, export, verification receipts, experiments, and MCP
Most users run the blackbox CLI. This crate is the implementation
library for that binary and for embedding capture/store logic.
§Operator docs (CLI)
Guides and reference live in the repository (not all pages are rendered as rustdoc). Start here:
- README — install and first commands
- docs index — full map
- CLI reference
§Library map
| Module | Role |
|---|---|
run | PTY supervision (RunSupervisor) |
storage | TraceStore + SQLite backend |
core | Run, TraceEvent, checkpoints, blobs |
capture | Capture layers and merge |
pipeline | EventWriter, batch ingest |
adapters | Harness detection and parse |
redaction | Secret scanning before write |
verification | Immutable receipts and outcomes |
boundary | Boundary contracts, containment, detectors, provenance, trust (1.7) |
evidence | External evidence NDJSON import + sensor adapters (1.7) |
incident | Multi-run incident reconstruction + pagination (1.7) |
forensic | Local forensic analysis packs (1.7) |
protocol | Evidence protocol canonical form & schemas (1.9) |
native | Native run/event ingestion without PTY (1.9) |
security | Security decisions and action reconciliation (1.9) |
commitment | Run evidence hash chains and signatures (1.9) |
otlp | OpenTelemetry export/import foundation (1.9) |
conformance | Protocol conformance profiles and runner (1.9) |
integrations | Native harness reference integrations (1.9) |
experiment | Experiments, reports, gates |
export | Portable / JSONL / HTML |
integrity | fsck and repair |
budget | Wall/process/memory/tool budgets |
mcp | MCP stdio server |
cli | clap CLI definition |
§Quick embed sketch
use std::sync::Arc;
use blackbox::cli::RunArgs;
use blackbox::run::RunSupervisor;
use blackbox::storage::sqlite::SqliteStore;
use blackbox::storage::TraceStore;
let store = Arc::new(SqliteStore::open_memory()?) as Arc<dyn TraceStore>;
let run = RunSupervisor::new(store)
.execute(&RunArgs {
command: vec!["echo".into(), "hi".into()],
..Default::default()
})
.await?;
println!("run id {}", run.id);§License
MIT OR Apache-2.0.
Modules§
- adapter_
protocol - External process adapter protocol (
blackbox.adapter/v1). Versioned external adapter protocol (process/NDJSON). - adapters
- Built-in harness adapters (Claude, Codex, generic, …).
- aggregates
- Incremental per-run aggregate counters. Incremental, recoverable per-run aggregates (1.5 L1).
- analysis
- Post-hoc analysis passes (errors, anomalies, causal links).
- backup
- Sealed offline store backup / restore. Sealed project backup / restore (offline vault).
- boundary
- Agent boundary contracts, containment receipts, evidence gates (1.7). Agent boundary contracts, containment receipts, and evidence gates (1.7+).
- budget
- Execution budget policy and Linux enforcement. Controlled execution budgets with capability classification (1.6 Phase F).
- capsule
- Reproducibility capsules. Reproducibility capsules with explicit completeness classes (1.6 Phase E).
- capture
- Capture layers: PTY, git, filesystem, process.
- cassette
- Experimental MCP cassette record / replay. MCP tool cassette record/replay (experimental, 1.6 Phase E).
- cli
- Clap CLI definition and command dispatch.
- cli_ext
- 1.6 CLI handlers (fsck, verify, experiment, …). CLI handlers for Blackbox 1.6 commands (fsck, verify, experiment, report, gate, capsule, …).
- commitment
- Run evidence commitments: hash chains and optional signatures (1.9). Run evidence commitments: event hashes, append-only chains, optional signatures (1.9).
- config
- Store paths, capture policy, continuity mode. Project paths and runtime configuration for blackbox.
- conformance
- Protocol conformance profiles and runner (1.9). Machine-readable protocol conformance runner (1.9).
- context
- Resume / context packing helpers.
Bounded resume context packs for agents (
context --for-resume). - core
- Core data model: runs, events, blobs, checkpoints.
- crypto
- Content hashing and sealed-export crypto. Optional at-rest encryption for content-addressed blobs and sealed packs.
- evidence
- External evidence ingestion (1.7). External evidence ingestion (1.7).
- experiment
- Experiments, multi-run reports, and CI gates. Structured experiments, multi-run reports, and regression gates (1.6 Phase D).
- export
- Export formats: portable JSON, JSONL, HTML.
- forensic
- Local forensic analysis packs (1.7). Local forensic analysis packs (1.7–1.8).
- incident
- Multi-run incident reconstruction (1.7). Multi-run incident reconstruction (1.7).
- ingest
- Durable ingest spool and crash recovery. Durable event ingest spool and recovery (1.6 Phase B).
- integrations
- Native harness integrations (1.9). Native harness integrations.
- integrity
- Store integrity checks (
fsck) and repair. Store integrity: fsck, repair planning, and structured reports (1.6 Phase B). - maybe_
run - Ambient wrap decision table (
maybe-run). Project-gated ambient capture entrypoint (blackbox maybe-run). - mcp
- MCP stdio server. Minimal MCP (Model Context Protocol) stdio server.
- memory
- Project memory pack build and shrink. Project memory pack (blackbox.memory/v1) — continuity plane for agent handoff.
- native
- Native run/event ingestion without PTY wrapping (1.9). Native run/event ingestion without PTY process wrapping (1.9).
- nest
- Nest guard without child-visible control env. Nest detection without child-visible environment variables (1.4 N1).
- otlp
- OpenTelemetry interoperability foundation (1.9). OpenTelemetry interoperability foundation (1.9).
- output
- Human and JSON CLI output helpers. CLI text/JSON output helpers (daily-driver 0.2).
- pipeline
- Event writer and batch ingest pipeline. Capture pipeline: single-writer event ingress and sequencing.
- pricing
- Token / cost estimation helpers.
Optional model pricing for
estimated_cost_usd. - privacy
- File permission hardening helpers. Local privacy hardening: restrictive file modes for store artifacts.
- projects
- Multi-project metadata index. Multi-project local index — metadata only (1.6 Phase F).
- protocol
- Evidence protocol: canonical form, schemas, stability (1.9). Blackbox Evidence Protocol (1.9).
- redaction
- Secret scanning and redaction.
- replay
- Replay engines: timeline, mock, sandbox, fork.
- resume
- Resume pack construction. Resume / relaunch helpers for forked and completed runs.
- resume_
inject - Continuity launch injection. Continuity / auto-resume: inject project memory into the next harness launch.
- retention
- Retention policies. Policy-driven retention (keep window OR max age; pinned tag never deleted).
- run
- PTY supervision orchestrator (
run::RunSupervisor). - score
- Eval score.json builder.
Eval / CI score schema (
blackbox.score/v1). - scrub
- Historical re-redaction and blob GC. Re-redact historical traces that may contain secrets at rest.
- search
- FTS search runner. Full-text search across runs and events (FTS5 when available).
- security
- Security decision receipts and action↔effect reconciliation (1.9). Security decision receipts and action↔effect reconciliation (1.9).
- serve
- Local web dashboard (Axum). Local HTTP dashboard with live SSE event streams.
- shell_
install - Shell ambient-wrapper install. Managed shell integration install/uninstall for ambient capture.
- state
- Sticky project state. Sticky project state written after each run (daily-driver handoff + 1.2 memory bus).
- status
- Status and handoff builders. Project status / agent handoff views.
- storage
- Trace store trait and SQLite backend. Trace storage: SQLite backend, blob keys, and pagination helpers.
- summary
- Run summary / postmortem text and JSON. One-command postmortem / summary for a run.
- supervisor
- Supervisor lifecycle, rollup, shutdown. Run supervision stages (1.5 U1).
- sync
- Dir / HTTP / S3 sync. Multi-machine sync: shared directory, HTTP (blackbox serve), or S3.
- terminal
- PTY terminal recording, ANSI, coalescing.
- trajectory
- Run trajectory comparison (LCP / divergence). Ordered trajectory diff between two runs (greedy LCP) + explain text.
- transcript
- Transcript rebuild from store blobs. Rebuild human-readable terminal transcripts from stored events/blobs.
- ui
- Ratatui TUI views.
- util
- Shared string / path helpers. Shared utility functions used across modules.
- verification
- Verification receipts and outcomes. Verification receipts: separate execution, verification, and capture (1.6 Phase C).
- views
- JSON view types for
--jsonenvelopes. Shared serde view types for CLI--jsonand (later) serve HTTP. - workspace_
manifest - Workspace checkpoint manifests and restore. Versioned workspace manifests for checkpoint completeness (1.5 W1).