RunSpecimen

v0.2.0-rc.16 on PyPI and GitHub

RunSpecimen

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

When you let an AI agent run commands on your machine, you want to know exactly what was approved, what ran, and whether it succeeded. RunSpecimen makes sure one human-approved command runs at a time and creates a receipt you can check later.

Install from PyPI View rc16 release
python3 -m pip install --pre runspecimen==0.2.0rc16
Adapters install from the GitHub tree.

Python 3.9+ · Apache-2.0 · Local-only, no telemetry · No third-party dependencies

The problem

When “the command succeeded” isn’t enough evidence

AI agents can draft scripts and launch jobs, but they're not great at proving which code actually ran — or at refusing a duplicate after a crash.

You approve first

Type APPROVE in a terminal to authorize the command. The approval binds the script, source code, and executable with an expiry time you control.

One run at a time

A workspace lock prevents duplicate or overlapping runs — no parallel workers, no silent second launch.

Check results

A mandatory postflight step verifies outputs before allowing the next command. Failed or missing checks block advancement.

Core lifecycle

Approve → preflight → run → postflight → verify

Steps that refuse to skip the paperwork.

  1. Approve

    You type APPROVE in a terminal. Agents cannot approve for you.

  2. Preflight

    Recheck that the approval is still valid and the workspace is ready before launch.

  3. Run

    Execute the command once, with time limits and output capture.

  4. Postflight

    Check exit code, required outputs, and any declared assertions. Issue a receipt required before the next step.

  5. Verify

    Compare the receipt against live files to confirm nothing changed. Reports which approval method was used.

Features

What you get

A focused toolset for approving, running, and tracking agent commands.

Terminal approval

Interactive approval with expiry. Works only in a real terminal — scripts and plugins cannot approve for you.

Source tracking

The script, source code, and executable are recorded at approval and checked again at launch.

Workspace lock

Prevents overlapping runs across the workspace — one step at a time.

Crash recovery

Detects an interrupted run and lets you abandon it with a recorded decision. The old run ID cannot be reused.

Step sequencing

Successors require a valid completed predecessor. Failed or missing receipts block advancement.

Receipts

Creates a tamper-evident log you can verify later. Optional signing for extra assurance.

Technical details

Append-only SHA-256 hash chain plus optional HMAC-SHA256 or Ed25519 (pip install 'runspecimen[ed25519]') with an external public-key trust anchor.

Local dashboard

Read-only browser view of current phase and evidence. Cannot approve or execute — no remote service.

Incident bundle

runspecimen bundle packs one run for offline sharing. History stays on disk. Free.

Agent adapters

Repository adapters help draft and drive the lifecycle while staying constrained to the local CLI.

FAQ

What RunSpecimen proves — and what it does not

How is this different from a sandbox?

A sandbox limits what a process can reach. RunSpecimen records whether an approved, exclusive step happened and whether declared outcomes passed. RunSpecimen is not an OS sandbox — use a container when you need real process isolation.

Can AI agents approve runs?

Not through the app. Plugins for Cursor, Codex, Claude, and others deliberately exclude the approve command. A human must run runspecimen approve in a real terminal.

What does crash recovery do?

It identifies a run that was interrupted. You can then abandon it in a terminal; the decision is recorded and that run ID cannot be reused.

Can the dashboard approve or execute?

No. It is a read-only view on your machine only. Approval stays in the terminal.

What is an incident bundle?

runspecimen bundle copies local run evidence into a folder anyone can check offline. It is free and stays on your disk.

What does GHSA-8357-m9wf-gjh9 change?

Advisory GHSA-8357-m9wf-gjh9 covers SIGTERM/SIGHUP orphaning of an approved contract. In 0.2.0rc3–0.2.0rc15, runspecimen run started the contract in its own session and only handled SIGINT, so a closed terminal, kill, or a supervisor/CI cancel could leave the contract running and free the workspace lease.

Upgrade with python3 -m pip install --upgrade --pre runspecimen==0.2.0rc16, then runspecimen --version. 0.2.0rc16 routes SIGTERM, SIGHUP, and SIGINT through process-group cleanup, records an interrupted outcome, and keeps a detached supervisor so wall_timeout_sec still bounds the group if the CLI is SIGKILLed, its group dies, or it is SIGSTOPped. The lease stays held until the group is confirmed empty; otherwise the run is recorded as cleanup_pending.

Residual limits (also stated as cleanup_scope=process_group in state):

  • A descendant that calls setsid() leaves the process group and can outlive cleanup.
  • SIGKILL of both the supervisor and the bind watchdog can still orphan remaining work.
  • A permanently unwritable state directory either keeps the lease (retry) or, if the group was already stopped, leaves a stale phase=running record plus an error that state could not be persisted.

This is not an OS sandbox. Default isolation.backend remains none.

Can I run two jobs in parallel?

Not in the same workspace. A lock covers the whole workspace for approve / preflight / run / postflight. Use separate workspaces if you need concurrency.

Does this include a paid control plane?

No. This site does not sell a RunSpecimen checkout. The published package is the free local CLI.

Read the complete FAQ · Security advisory GHSA-8357-m9wf-gjh9

Published release

What pip installs today

runspecimen==0.2.0rc16 is the local CLI: one approved run, a workspace lock, postflight check, and a receipt. There is no checkout on this site.

What's new in rc16

runspecimen run no longer orphans an approved contract on SIGTERM/SIGHUP (advisory GHSA-8357-m9wf-gjh9, affected 0.2.0rc3–0.2.0rc15). Upgrade with python3 -m pip install --upgrade --pre runspecimen==0.2.0rc16. Residual limits remain: a setsid() descendant can outlive cleanup; SIGKILL of both the supervisor and the bind watchdog can still orphan work; an unwritable state directory can leave a stale phase=running record.

Still includes the rc15 evidence-expansion commands (requirements, freshness, scenes, config, and usage) plus opt-in isolation backends (sandbox-exec on macOS, bwrap on Linux), workspace policy files, retain, digest, and diff. The default isolation backend is none, which does not confine the process. The local Mac app label remains 0.1.6 (16) and is not an App Store upload.

Use cases

Where a green exit code is not the story

Best fit: small teams already letting AI agents run local commands.

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 limits

What RunSpecimen is — and is not

What it answers

  • Was this step authorized?
  • Did only one run happen at a time?
  • Did declared checks pass?
  • Is the next step eligible to proceed?

Does not replace

  • OS sandboxes or containers
  • CI pipelines
  • Transparency logs
  • One-tap approval (typing APPROVE is intentional)

A green postflight means declared assertions passed under recorded settings — not that the scientific or engineering claim is true. The default backend does not confine the process.

Get started

Install, approve once, verify a receipt

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

# Current published candidate (PyPI == GitHub Release bytes)
python3 -m pip install --pre runspecimen==0.2.0rc16
runspecimen --version

# Or from Homebrew (tap still served 0.2.0rc15 on 2026-11-01; pin via pip for rc16)
brew install darashkevich/runspecimen/runspecimen

# Pip/Homebrew installs do not create a cwd examples/ tree — use init-demo
runspecimen init-demo --workspace ./runspecimen-demo
cd runspecimen-demo

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

# Lifecycle (you type APPROVE in a terminal; dashboard cannot approve or run)
runspecimen approve --workspace . --contract contract.json
runspecimen preflight --workspace . --contract contract.json
runspecimen run --workspace . --contract contract.json
runspecimen postflight --workspace . --contract contract.json
runspecimen verify --workspace . --contract contract.json \
  --campaign-id demo-campaign --run-id run-001

# Optional local incident pack (Community; not a hosted vault)
runspecimen bundle --workspace . --campaign-id demo-campaign --run-id run-001 \
  --out /tmp/rs-incident --contract contract.json
Open PyPI Homebrew tap Release notes & assets SHA256SUMS
Release assets and checksums

Verified rc16 release assets (same SHA-256 on GitHub and PyPI): wheel, source distribution, repository adapter ZIP, and checksums.

Optional: runspecimen dashboard --workspace . --contract contract.json --open opens a read-only browser view. It cannot approve or execute a run.