Docs
Moil docs
Moil gives every agent run a Linux machine of its own — a Firecracker microVM we call a box. Start one from the CLI or the API, run work in it, keep the state that worked, and throw the rest away.
Your first box, in three lines
npx moil@latest # install the CLI and sign in
moil create --name dev
moil exec dev -- uname -aGuides
- Quick start Install the CLI, start a box, get a shell, clean up.
- Boxes Lifecycle, sizes, idle pause, logs, labels and environment.
- Snapshots & forks Save a box once, start new ones from it, or copy one mid-run.
- Desktop & browser Watch a box’s screen, let an agent drive it, take over and hand back.
- Ports Give a server inside a box an HTTPS URL — public, or behind a link token.
- Secrets Credentials the egress proxy adds to requests, so code never holds them.
- CI runners Send GitHub Actions jobs to a fresh box with one runs-on line.
- CLI Every moil command on one page.
Concepts
The CLI, the API and the dashboard all use the same handful of words.
| Word | What it means |
|---|---|
| Box | A Firecracker microVM of your own: its own kernel, root, systemd and Docker. Files under /data (your home is /data/home) and the software you install survive restarts. |
| Template | What a new box boots from: desktop (the default, with a Linux desktop and Chromium), base (the same toolchains, no desktop) or ci (an Ubuntu 24.04 runner image). |
| Snapshot | A saved copy of a box’s disks. New boxes start from it in seconds; it is private to your workspace. |
| Fork | A copy of a box made on its host, with the same template and size. Disks are copied; memory and processes are not. |
| Operation | A lifecycle change — create, start, pause, resume, stop, delete. A box has at most one at a time, and you can follow it until it succeeds or fails. |
| Workspace | Where boxes, snapshots, keys and secrets live. Every API key belongs to exactly one workspace and reaches nothing outside it. |
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 |
A box that sits idle for 30 minutes pauses itself. A command, an SSH session or a request to one of its public ports wakes it back up — but only if it paused itself. A box you paused or stopped stays put until you resume or start it. See idle pause.
Three ways in
- The CLI —
moil, for people at a terminal and for agents with a shell. Every command is on the CLI page. - The HTTP API — JSON over HTTPS with an API key in
Authorization: Bearer …. Lifecycle calls return an operation you can wait on. - The dashboard — for watching a box’s screen, managing keys and secrets, and seeing this month’s usage.
Feeding these docs to an agent? /llms.txt lists every page with a one-line summary and the CLI in plain text.