Readme2demo – runs your README in a sandbox, publishes only what re-runs

Readme2demo, an AI agent that reads a repository's README and runs it inside a hardened Docker sandbox to generate verified tutorials and demo videos, has been released. The tool replays every step in a fresh container before publishing, ensuring the tutorial has been executed twice. It supports both self-hosted runs via Claude subscription and metered API billing for scale.

▶ readme2demo generating its own tutorial: an AI agent runs this repo's README in a sandbox, a fresh container replays every step, then the demo is rendered. Full self-run output in examples/readme2demo · run against another project in examples/toolhive. AI-verified tutorial and demo video generator. Point it at a repo. An AI agent reads the README and actually runs it inside a hardened Docker sandbox. Only after a clean-room replay passes does it render a demo video VHS and publish the tutorial, step-by-step guide, and troubleshooting doc. The value is not "AI writes a tutorial" — it's that the tutorial ran, twice , before you saw it. See it in action: browse verified example runs /alphacrack/readme2demo/blob/main/examples — real tutorials, step-by-step guides, and demo videos, each independently replayed in a clean container before publishing. repo URL → ingest/plan → agent run in Docker → normalize transcript → distill minimal path → VERIFY replay in fresh container → render VHS video → generate tutorial.md + troubleshooting.md See IMPLEMENTATION PLAN.md /alphacrack/readme2demo/blob/main/IMPLEMENTATION PLAN.md for the full architecture. - Python ≥ 3.10, Docker - Auth, one of: Your Claude subscription no API key : a local Claude Code install. The planner/distiller/tutorial passes run on your subscription via --llm-backend claude-cli claude -p , and the in-sandbox agent authenticates with CLAUDE CODE OAUTH TOKEN create one: claude setup-token . Fully supported for self-hosted, single-operator runs against your own repos — Pro/Max plans include a monthly Agent SDK credit that covers claude -p . ANTHROPIC API KEY — metered API billing; best for scale and concurrency, and required if you host readme2demo as a service for others per Anthropic's terms, subscription auth may not power a multi-tenant product — see ROADMAP.md /alphacrack/readme2demo/blob/main/ROADMAP.md . - Optional: LLM API KEY + LLM MODEL for --engine openhands experimental run on your Claude subscription no API key — supported for self-hosted runs claude setup-token interactive: approve in browser, then COPY the sk-ant-oat01-... token it prints do NOT use $ ... export CLAUDE CODE OAUTH TOKEN=sk-ant-oat01-... readme2demo run <repo-url --llm-backend claude-cli run on metered API billing scale, concurrency, or hosting for others export ANTHROPIC API KEY=sk-ant-... readme2demo run <repo-url --llm-backend auto picks api pip install -e ". dev " docker build -t readme2demo/base:latest images/base/ readme2demo run https://github.com/example/tool readme2demo run -gr https://github.com/example/tool same, via the flag readme2demo run -s my guide.md guide-only: no repo, your guide is self-contained readme2demo run -gr https://github.com/example/tool -s my guide.md both: your guide drives everything readme2demo run https://github.com/example/tool --allow-docker-socket for tools that manage containers SECURITY TRADEOFF: pierces sandbox isolation — trusted repos only readme2demo run https://github.com/example/tool --skip-video --budget-usd 3 readme2demo resume runs/tool-20260702-... --from-stage render readme2demo report runs/tool-20260702-... The repo is optional : pass it positionally or with -gr/--github-repo , supply a guide with -s/--step-by-step , or both. At least one is required. With a guide alone, no repo is cloned — the guide must be self-contained install a published package, or clone what it needs as an explicit step ; the fresh-container replay still verifies every command. Outputs land in runs/<run-id / : tutorial.md , step by step.md , troubleshooting.md , commands.sh , demo.tape , demo.mp4 , demo.gif , plus manifest.json with stage statuses and total cost. The demo video is always built from step by step.md : its steps are parsed, and every demo-safe, grounded command becomes a typed command in the video with the step title shown as an on-screen comment. Three ways it comes to exist, in priority order: You pass one : readme2demo run <url -s my guide.md — injected into the clone as the authoritative guide; planner and agent follow it, video plays it. The <url is optional here: readme2demo run -s my guide.md runs guide-only against an empty sandbox. The repo ships one step by step.md / step-by-step.md at root or docs/ , any case : same treatment, automatically. Neither exists : the pipeline generates a detailed step by step.md — every command from the verified commands.sh as a numbered step with real captured outputs — then builds the video from it. Ready to contribute back to the repo. Setup steps clones, installs, builds are documented in the guide but kept out of the video — it plays against the verified, already-built worktree, showing the payoff. Every tutorial carries a verification badge: ✅ Verified on <date · image <digest · commit <sha — or a loud ⚠ UNVERIFIED if the replay didn't pass. Unverified output is never silently published. CLI flags readme2demo.toml defaults: engine = "claude-code" or "openhands" model = "claude-sonnet-5" planner/distiller/tutorial passes max turns = 60 budget usd = 5.0 base image = "readme2demo/base:latest" skip video = false python -m pytest tests/ -q 175 unit tests, no docker/network needed ruff check src/ tests/ correctness lint matches CI python -m pytest -m integration requires docker + API keys none yet READMEs are untrusted code. The agent runs inside a hardened container cap-drop ALL, no-new-privileges, memory/cpu/pids limits, non-root — that container is the permission boundary. Known MVP tradeoff: the API key enters the sandbox; use a dedicated low-limit key. A host-side key-injecting egress proxy is planned Milestone 4 . Full threat model and private vulnerability reporting: SECURITY.md /alphacrack/readme2demo/blob/main/SECURITY.md . Examples /alphacrack/readme2demo/blob/main/examples — verified output committed as proof Roadmap /alphacrack/readme2demo/blob/main/ROADMAP.md — where this is headed including the exploratory hosted/SaaS direction Contributing /alphacrack/readme2demo/blob/main/CONTRIBUTING.md — the one non-negotiable rule, and how to get set up Security policy /alphacrack/readme2demo/blob/main/SECURITY.md · Code of Conduct /alphacrack/readme2demo/blob/main/CODE OF CONDUCT.md Architecture /alphacrack/readme2demo/blob/main/architecture/README.md — stage boundaries and diagrams MIT licensed. The CLI and verification pipeline are, and will stay, free and open source.