{"slug": "readme2demo-runs-your-readme-in-a-sandbox-publishes-only-what-re-runs", "title": "Readme2demo – runs your README in a sandbox, publishes only what re-runs", "summary": "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.", "body_md": "▶ 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.\n\n**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.\n\nThe value is not \"AI writes a tutorial\" — it's that the tutorial **ran, twice**, before you saw it.\n\n**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.\n\n```\nrepo URL → ingest/plan → agent run (in Docker) → normalize transcript\n        → distill minimal path → VERIFY replay in fresh container\n        → render VHS video → generate tutorial.md + troubleshooting.md\n```\n\nSee [IMPLEMENTATION_PLAN.md](/alphacrack/readme2demo/blob/main/IMPLEMENTATION_PLAN.md) for the full architecture.\n\n- Python ≥ 3.10, Docker\n- Auth, one of:\n**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`\n\n(`claude -p`\n\n), and the in-sandbox agent authenticates with`CLAUDE_CODE_OAUTH_TOKEN`\n\n(create one:`claude setup-token`\n\n). 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`\n\n.`ANTHROPIC_API_KEY`\n\n— 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)).\n\n- Optional:\n`LLM_API_KEY`\n\n+`LLM_MODEL`\n\nfor`--engine openhands`\n\n(experimental)\n\n```\n# run on your Claude subscription (no API key) — supported for self-hosted runs\nclaude setup-token        # interactive: approve in browser, then COPY the\n                          # sk-ant-oat01-... token it prints (do NOT use $(...))\nexport CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...\nreadme2demo run <repo-url> --llm-backend claude-cli\n\n# run on metered API billing (scale, concurrency, or hosting for others)\nexport ANTHROPIC_API_KEY=sk-ant-...\nreadme2demo run <repo-url>              # --llm-backend auto picks api\npip install -e \".[dev]\"\ndocker build -t readme2demo/base:latest images/base/\nreadme2demo run https://github.com/example/tool\nreadme2demo run -gr https://github.com/example/tool             # same, via the flag\nreadme2demo run -s my_guide.md                                  # guide-only: no repo, your guide is self-contained\nreadme2demo run -gr https://github.com/example/tool -s my_guide.md   # both: your guide drives everything\nreadme2demo run https://github.com/example/tool --allow-docker-socket  # for tools that manage containers (SECURITY TRADEOFF: pierces sandbox isolation — trusted repos only)\nreadme2demo run https://github.com/example/tool --skip-video --budget-usd 3\nreadme2demo resume runs/tool-20260702-... --from-stage render\nreadme2demo report runs/tool-20260702-...\n```\n\nThe repo is **optional**: pass it positionally or with `-gr/--github-repo`\n\n, supply a guide with `-s/--step-by-step`\n\n, 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.\n\nOutputs land in `runs/<run-id>/`\n\n: `tutorial.md`\n\n, `step_by_step.md`\n\n, `troubleshooting.md`\n\n, `commands.sh`\n\n, `demo.tape`\n\n, `demo.mp4`\n\n, `demo.gif`\n\n, plus `manifest.json`\n\nwith stage statuses and total cost.\n\nThe demo video is always built **from** `step_by_step.md`\n\n: 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:\n\n**You pass one**:`readme2demo run <url> -s my_guide.md`\n\n— injected into the clone as the authoritative guide; planner and agent follow it, video plays it. The`<url>`\n\nis optional here:`readme2demo run -s my_guide.md`\n\nruns guide-only against an empty sandbox.**The repo ships one**(`step_by_step.md`\n\n/`step-by-step.md`\n\nat root or`docs/`\n\n, any case): same treatment, automatically.**Neither exists**: the pipeline*generates*a detailed`step_by_step.md`\n\n— every command from the verified`commands.sh`\n\nas a numbered step with real captured outputs — then builds the video from it. Ready to contribute back to the repo.\n\nSetup 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.\n\nEvery tutorial carries a verification badge: `✅ Verified on <date> · image <digest> · commit <sha>`\n\n— or a loud `⚠ UNVERIFIED`\n\nif the replay didn't pass. Unverified output is never silently published.\n\nCLI flags > `readme2demo.toml`\n\n> defaults:\n\n```\nengine = \"claude-code\"      # or \"openhands\"\nmodel = \"claude-sonnet-5\"   # planner/distiller/tutorial passes\nmax_turns = 60\nbudget_usd = 5.0\nbase_image = \"readme2demo/base:latest\"\nskip_video = false\npython -m pytest tests/ -q            # 175 unit tests, no docker/network needed\nruff check src/ tests/               # correctness lint (matches CI)\npython -m pytest -m integration      # requires docker + API keys (none yet)\n```\n\nREADMEs 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).\n\nFull threat model and private vulnerability reporting: [SECURITY.md](/alphacrack/readme2demo/blob/main/SECURITY.md).\n\n[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\n\nMIT licensed. The CLI and verification pipeline are, and will stay, free and open source.", "url": "https://wpnews.pro/news/readme2demo-runs-your-readme-in-a-sandbox-publishes-only-what-re-runs", "canonical_source": "https://github.com/alphacrack/readme2demo", "published_at": "2026-07-08 04:16:43+00:00", "updated_at": "2026-07-08 04:29:34.955698+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "generative-ai"], "entities": ["Readme2demo", "Docker", "Claude", "Anthropic", "VHS"], "alternates": {"html": "https://wpnews.pro/news/readme2demo-runs-your-readme-in-a-sandbox-publishes-only-what-re-runs", "markdown": "https://wpnews.pro/news/readme2demo-runs-your-readme-in-a-sandbox-publishes-only-what-re-runs.md", "text": "https://wpnews.pro/news/readme2demo-runs-your-readme-in-a-sandbox-publishes-only-what-re-runs.txt", "jsonld": "https://wpnews.pro/news/readme2demo-runs-your-readme-in-a-sandbox-publishes-only-what-re-runs.jsonld"}}