# Moil

> Moil gives each agent run its own Firecracker microVM — a real Linux kernel, root, Docker and a disk that stays. Snapshot it, fork it mid-run, or point CI at it.

## Key facts

- A box is a Firecracker microVM with its own kernel, root, systemd and Docker; 4 vCPU / 8 GiB by default, with a persistent 20 GiB disk at /data (home is /data/home).
- Templates: desktop (default; Linux desktop + Chromium), base (no desktop), ci (Ubuntu 24.04).
- States: running, paused (memory kept), stopped (files kept, fresh boot on start), deleted. Idle boxes pause themselves after 30 minutes and wake on exec, SSH or a request to a public port.
- Install: `npx moil@latest` installs the CLI and signs in with a device code. Without a browser, set MOIL_API_KEY.
- CI: GitHub Actions jobs run on a fresh box with runs-on: moil-small | moil-medium | moil-large | moil-xlarge | moil-2xlarge.
- Plans: Free $0, Pro $29/mo + usage, Team $249/mo + usage, Enterprise Custom. Usage: vCPU $0.005 per vCPU-hour, memory $0.002 per GiB-hour, disk $0.00015 per GiB-hour, egress $0.03 per GiB. Billed per second while running. Details: https://moil.dev/pricing
- Contact: support@moil.dev

## CLI cheat sheet

```
moil login                                      Sign in with a device code in your browser. Skipped when MOIL_API_KEY is set.
moil whoami                                     The account, workspace and key the CLI is using.
moil usage                                      This month’s usage, included credit left, and your plan’s limits.
moil update                                     Move the CLI to its newest version.
moil keys create --name N [--expires-in 90d]    Make an API key. It is printed once.
moil keys ls | revoke <key>                     List or revoke keys in the current workspace.
moil templates                                  List the templates a box can start from.
moil create --name N [--template T | --from S]  Start a box from a template or a snapshot, and wait until it runs.
moil create … --vcpus 8 --mem 16 [--disk 50]    Pick another size from your plan. Memory and disk are in GiB.
moil ls [--label k=v] [--json]                  Your boxes, optionally filtered by label.
moil get <box> [--json]                         One box: state, size, template, ports and operations.
moil logs <box> [-f]                            Console log and recent operations. Never wakes the box.
moil pause | resume <box>                       Freeze a box with its memory, then carry on where it stopped.
moil stop | start <box>                         Shut down (files kept), then boot fresh.
moil restart <box>                              Power-cycle a box that stopped answering. Disks are kept.
moil resize <box> --vcpus N --mem M | --disk D  Change size or grow /data. A new CPU or memory size applies at the next start.
moil idle <box> 15m | off                       How long a box may sit idle before it pauses itself.
moil rm <box> [--yes]                           Delete a box and its disks. Its snapshots stay.
moil exec <box> -- <cmd…>                       Run one command and exit with its exit code.
moil exec --stream <box> -- <cmd…>              Print output as it is written.
moil exec --bg <box> -- <cmd…>                  Start a detached job and print its ID; follow it with moil jobs.
moil jobs ls | logs | kill <box> [job]          Background jobs started with exec --bg.
moil run [--push DIR] [--timeout 10m] -- <cmd>  Create a box, upload DIR, run the command, delete the box.
moil ssh <box>                                  An interactive shell over SSH.
moil cp <src> <dst>                             Copy files in or out: moil cp ./a.tgz run-42:/data/a.tgz.
moil ps <box>                                   Processes running in the box.
moil snapshot <box> --name N                    Save a box’s disks as a snapshot.
moil snapshot ls | rm <snapshot>                List or delete snapshots.
moil restore <box> --snapshot S [--yes]         Put a box’s disks back to a snapshot, in place. Same ID, name and URLs.
moil fork <box> [--count N]                     Copy a box on its host in seconds, up to 5 copies, no snapshot needed.
moil port publish <box> <port> [--private]      Give a port an HTTPS URL; --private adds a link token.
moil port ls | unpublish <box> <port>           List or remove published ports.
moil port forward <box> [LOCAL:]REMOTE          A private localhost tunnel until Ctrl-C.
moil desktop screenshot <box> > shot.png        Grab the screen of a desktop box.
moil desktop link <box> [--control] [--ttl 1h]  A watch-only (or control) link to the desktop.
moil desktop revoke <box>                       Invalidate every desktop link for the box and close open viewers.
moil secrets set NAME --host H                  Store a credential the egress proxy adds for host H.
moil secrets ls | rm NAME                       List or delete secrets. Values are never printed.
```

## Start

- [Overview](https://moil.dev/docs): What a box is, the words Moil uses, and where to go next.
- [Quick start](https://moil.dev/docs/start): Install the CLI, start a box, get a shell, clean up.

## Guides

- [Boxes](https://moil.dev/docs/machines): Lifecycle, sizes, idle pause, logs, labels and environment.
- [Snapshots & forks](https://moil.dev/docs/snapshots): Save a box once, start new ones from it, or copy one mid-run.
- [Desktop & browser](https://moil.dev/docs/desktop): Watch a box’s screen, let an agent drive it, take over and hand back.
- [Ports](https://moil.dev/docs/ports): Give a server inside a box an HTTPS URL — public, or behind a link token.
- [Secrets](https://moil.dev/docs/secrets): Credentials the egress proxy adds to requests, so code never holds them.
- [CI runners](https://moil.dev/docs/ci): Send GitHub Actions jobs to a fresh box with one runs-on line.

## Reference

- [CLI](https://moil.dev/docs/cli): Every moil command on one page.

## Optional

- [Pricing](https://moil.dev/pricing): plans, unit rates and a cost calculator
- [Blog](https://moil.dev/blog): engineering notes
- [Changelog](https://moil.dev/changelog): what changed, newest first
- [Contact](https://moil.dev/contact): support@moil.dev