RunSpecimen

Local run assurance · release candidate

RunSpecimen

One approved run. One receipt. No silent second launch.

Flight ops for consequential local agent campaigns — human TTY approval, exclusive workspace lease, mandatory postflight, and a tamper-evident certificate. Not a sandbox. Not a scheduler.

View on GitHub Install & verify a receipt
Cursor and Codex adapters are available in the repository for local installation. Public marketplace availability is not yet confirmed.

Stdlib-only Python CLI · Apache-2.0 · Local-only, no telemetry · Cursor & Codex adapters stay adapters

The wedge

When “the command succeeded” isn’t enough evidence

Agents draft scripts and launch jobs. They are terrible at proving which code and binary actually ran — or at refusing a duplicate worker after a crash.

Authorize

A human types APPROVE on a real TTY, binding contract, source, and resolved executable hashes with an expiry.

Exclusive

One workspace-wide execution lease. Exactly one mutating lifecycle step at a time — no parallel workers, no silent second launch.

Verify & advance

Postflight asserts outcomes and issues a certificate. Successors refuse an unpostflighted or failed predecessor.

Core lifecycle

Approve → preflight → run → postflight → verify

Campaign steps that refuse to skip the paperwork.

  1. Approve

    Interactive TTY approval binds contract + provenance. Agents must not type APPROVE.

  2. Preflight

    Recheck approval freshness, provenance, outputs, predecessor, and the workspace lease before launch.

  3. Run

    Execute the declared argument vector once (shell=False), within wall-clock and capture bounds.

  4. Postflight

    Assert exit code, required outputs, and declared checks. Issue the certificate required before a successor.

  5. Verify

    Rehash live contract, source, runtime, outputs, and the SHA-256 hash-chained event log against the receipt.

Feature set

Built for exclusive, receipt-backed steps

Narrow promise. Explicit non-goals. The CLI is the enforcement boundary.

TTY-bound approval

Interactive approval with expiry. Refuses pipes/CI without a real terminal. Marketplace plugins cannot approve for you.

Provenance binding

Contract, source roots, and resolved executable hashes are bound into the approval document and rechecked at launch.

Workspace lease

POSIX fcntl lease serializes approve / preflight / run / postflight across the whole workspace.

Crash-safe state

Atomic JSON state writes. A run ID cannot be reused after execution starts.

Predecessor gating

Successors require a valid postflighted predecessor. Failed or missing certificates block advancement.

Tamper-evident receipts

Append-only SHA-256 hash-chained event log plus a verifiable local certificate after successful postflight.

Exact postflight checks

Exit code, output existence/SHA, JSON field equality, and source-unchanged assertions — hashed into the receipt.

Loopback dashboard

Read-only 127.0.0.1 guide for phase and evidence. It cannot approve or execute. No remote service.

Agent adapters

Cursor and Codex integrations help draft and drive the lifecycle. They stay constrained adapters to the local CLI.

Use cases

Where a green exit code is not the story

Best fit: small teams already letting agents operate long-running local jobs.

Computational research

Prove the approved source and interpreter ran, required outputs appeared with declared fields, and the next campaign step waited for a certified predecessor.

ML evaluation & validation

Gate eval jobs so provenance drift, duplicate workers, and “looks done” handoffs cannot silently advance a campaign.

Quant / backtesting

One exclusive run under recorded config and source hashes — then a certificate before the successor strategy step.

Security research & fuzzing

Keep human approval in the terminal while agents prepare contracts; reconstruct what was authorized after an incident.

Cursor / Codex supervision

Let the agent draft, validate, run, postflight, and verify. You keep the only gate that matters: type APPROVE.

Regulated engineering evidence

Locally reconstructable receipts for consequential steps. Useful evidence today — not a compliance product yet.

Honest boundary

What RunSpecimen is — and is not

Answers

  • Was this step authorized?
  • Was it exclusive under the workspace lease?
  • Did declared checks pass under recorded provenance?
  • Is the successor eligible to advance?

Does not replace

  • OS sandboxes / process containment
  • Runtime firewalls for tool-call blocking
  • CI pipelines or observability traces
  • External signatures or transparency logs (yet)

A green postflight means declared assertions passed under recorded provenance — not that the scientific or engineering claim is true. Pair with containers when you need isolation.

Get started

Clone, approve once, verify a receipt

Success metric: first verified local receipt — not marketplace impressions.

# Install (dev bootstrap recommended)
git clone https://github.com/darashkevich/runspecimen
cd runspecimen
sh scripts/bootstrap_dev.sh

# Host + contract checks
runspecimen doctor --workspace .
runspecimen validate --workspace . --contract examples/demo_contract.json

# Lifecycle (human TTY required for approve; dashboard cannot approve or run)
runspecimen approve --workspace . --contract examples/demo_contract.json
runspecimen preflight --workspace . --contract examples/demo_contract.json
runspecimen run --workspace . --contract examples/demo_contract.json
runspecimen postflight --workspace . --contract examples/demo_contract.json
runspecimen verify --workspace . --contract examples/demo_contract.json \
  --campaign-id demo-campaign --run-id run-001
Open the repository Read the user guide About

Optional visibility only: runspecimen dashboard --workspace . --contract examples/demo_contract.json --open binds to loopback, is read-only, and cannot approve or execute a run.