background-runnerlisted
Install: claude install-skill williamyates/bgrunner-skill
# Background Runner
Run things that keep going between your turns, and that come back from disk after
the VM is torn down. Two tools ship with this skill; pick one.
Built for Claude's hosted code-execution sandbox (claude.ai chat and Cowork). On a
persistent local machine — e.g. Claude Code — none of the teardown-survival machinery
is needed; plain background execution is enough there.
## First: know the substrate (one paragraph)
The VM persists while warm, but **after ~5 minutes idle it is fully torn down — every
process dies, including PID 1.** On return you get a **fresh VM with the disk restored**.
So detaching a process (double-fork) only buys survival across tool calls and short gaps;
**disk is the only thing that crosses a teardown, and `resume` is the real workhorse.**
Network egress is rate-governed (~8–25 req/s regardless of worker count), and the box has
1 CPU core (concurrency helps I/O, not CPU). Full details + how to re-measure:
`references/environment-model.md` — read it if anything about persistence, timing, or
throughput surprises you.
## Pick your tool
| You want to… | Use | Why |
|---|---|---|
| Run an **arbitrary command/script/service** in the background (and optionally auto-restart it) | `scripts/bgrun.py` | named jobs, status/logs/stop, **post-teardown resume**, supervisor/restart |
| Write the **work yourself in Python** with checkpoint + skip-already-done | `scripts/work_daemon.py` | resume-safe unit loop; re-run same command to continue |
Both