Guides

Boxes

A box is a Firecracker microVM with its own Linux kernel, root disk and a persistent /data disk. This page covers how a box moves between states, how big it can be, when it pauses by itself, and how to label and configure it.

Lifecycle

• Every change to a box — create, start, pause, resume, stop, delete — is an operation, and a box runs at most one at a time. The CLI waits for each one; the API returns it so you can wait yourself.
• Resume brings back a paused box’s memory and processes. If that can’t be done, the box starts fresh instead: files kept, processes not.
• A paused box can’t be stopped directly — resume it first, or delete it.
• Restart power-cycles a box that stopped answering. The guest is asked to shut down, then forced off after 60 seconds, and booted again on the same disks.
• A reboot from inside (sudo reboot) comes back on its own. A shutdown from inside (sudo poweroff) leaves the box stopped until you start it.

Templates

Pass --template to moil create, or --from to start from one of your snapshots. moil templates lists what your workspace can use.

Sizes and disk

A box is 4 vCPU and 8 GiB unless you ask for another size your plan allows.

moil create --name big --vcpus 8 --mem 16
moil create --name scratch --template base --disk 50
moil resize big --vcpus 16 --mem 32       # applied at the next start
moil resize big --disk 100                # /data grows while running

• A new CPU or memory size applies the next time the box starts. Add --restart to stop and start it for you.
• /data is 20 GiB by default. On paid plans it grows while the box runs and shrinks only while it is stopped, when the data still fits.
• Your home directory is /data/home, so anything you put there survives restarts, snapshots and forks. /tmp lives in memory.

Idle pause

A box with no commands, SSH sessions or port traffic for 30 minutes pauses itself, so a forgotten box costs disk, not compute. On paid plans you choose anywhere from 5 to 60 minutes, or turn it off.

moil idle dev 10m        # pause after 10 idle minutes
moil idle dev off        # never pause by itself (paid plans)
moil create --name job --idle 5m

A box that paused itself wakes on use: moil exec, moil ssh, a file copy, or a request to one of its public URLs. A box you paused or stopped stays that way until you resume or start it — its URLs answer 503 in the meantime.

Logs and status

moil logs dev -f                 # console log, then follow it
moil get dev --json | jq .state
moil ps dev                      # what is running inside

moil logs reads the console log and recent operations without waking a paused box, which makes it the first thing to run when a box won’t come up.

Labels and environment

moil create --name eval-17 --label team=search --label run=17
moil ls --label team=search
moil create --name api --env NODE_ENV=production --env PORT=3000

• Labels are key=value pairs for finding boxes later — by team, by run, by customer. They never reach the guest.
• --env sets variables for every command and shell in the box. For API keys and tokens use secrets, which never land on the box’s disk.