Skip to main content

Crate blackbox

Crate blackbox 

Source
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

  1. Supervise a child under a PTY (run)
  2. Merge capture layers (terminal, git, filesystem, process)
  3. Redact secrets before write (default)
  4. Persist ordered TraceEvents in SQLite + content-addressed blobs
  5. 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:

§Library map

ModuleRole
runPTY supervision (RunSupervisor)
storageTraceStore + SQLite backend
coreRun, TraceEvent, checkpoints, blobs
captureCapture layers and merge
pipelineEventWriter, batch ingest
adaptersHarness detection and parse
redactionSecret scanning before write
verificationImmutable receipts and outcomes
boundaryBoundary contracts, containment, detectors, provenance, trust (1.7)
evidenceExternal evidence NDJSON import + sensor adapters (1.7)
incidentMulti-run incident reconstruction + pagination (1.7)
forensicLocal forensic analysis packs (1.7)
protocolEvidence protocol canonical form & schemas (1.9)
nativeNative run/event ingestion without PTY (1.9)
securitySecurity decisions and action reconciliation (1.9)
commitmentRun evidence hash chains and signatures (1.9)
otlpOpenTelemetry export/import foundation (1.9)
conformanceProtocol conformance profiles and runner (1.9)
integrationsNative harness reference integrations (1.9)
experimentExperiments, reports, gates
exportPortable / JSONL / HTML
integrityfsck and repair
budgetWall/process/memory/tool budgets
mcpMCP stdio server
cliclap 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 --json envelopes. Shared serde view types for CLI --json and (later) serve HTTP.
workspace_manifest
Workspace checkpoint manifests and restore. Versioned workspace manifests for checkpoint completeness (1.5 W1).