Docs
Moil docs
How to start a box, run work in it and keep the state you care about. This hub is a preview: commands and names may change before Moil opens up.
Preview CLI. The moil package and every command below are placeholders — nothing is published yet.
- Quick start Install, start a box, clean up.
- Concepts Boxes, snapshots, forks and states.
- CI runners Point
runs-onat a Moil box.
Quick start
1. Install the CLI
npx moil@latestSigns you in and puts moil on your path.
2. Start a box
moil create --name dev
moil ssh dev # a shell inside the box
moil exec dev -- uname -a # or one command, then back3. Keep it, or throw it away
moil pause dev # freeze it; memory and processes are kept
moil resume dev # carry on exactly where it stopped
moil rm dev # delete the box and its disk4. Save the good state
moil snapshot dev --name dev-base
moil create --name dev2 --from dev-base
moil fork dev --count 3Concepts
| Word | What it means |
|---|---|
| Box | A Firecracker microVM of your own: its own kernel, root, systemd and Docker. Files under /data survive restarts. |
| Template | What a new box boots from — a base image with a desktop and browser, a CI image, or one of your snapshots. |
| Snapshot | A saved copy of a box’s disks. New boxes can start from it; it is private to your workspace. |
| Fork | A copy of a live box made on its host, with the same template and size. Memory is not copied. |
| Operation | A lifecycle change (create, start, pause, resume, stop, delete) that you can follow until it succeeds or fails. |
| Workspace | Where boxes, snapshots, keys and secrets live. API keys are scoped to one workspace. |
Box states
| State | Files | Memory & processes | Use it to |
|---|---|---|---|
| Running | kept | live | Work in it |
| Paused | kept | kept | Step away, come back to the same session |
| Stopped | kept | lost | Shut down; the next start boots fresh |
| Deleted | gone | gone | Free the slot for a new box |
Idle boxes pause themselves after a while; a command, SSH session or request to one of their ports wakes them back up.
Coming next
- Boxes & sizes soonLifecycle, sizes, idle auto-pause, logs, labels and environment.
- Snapshots & forks soonSave, restore in place, start from a snapshot, fork a running box.
- Desktop & browser soonScreenshots, input and handing control between agent and human.
- Ports soonPublic and private URLs for a server running inside a box.
- Secrets soonCredentials added at the egress proxy so code only sees placeholders.
- CLI, HTTP API, SDK, MCP soonReference for every command, endpoint and tool.