All pages
Sandboxes
A sandbox is a machine you treat as disposable: somewhere to run a command, try a build, or let an agent work without it touching your laptop. It has a URL, it sleeps by itself, and asleep it costs only its disk.
Create one and run something
pilot machine create scratch
pilot machine exec scratch -- ls /
The name is optional. Pass one when the URL has to be predictable, because
the URL is derived from it and then never changes. exec waits for the command
and returns stdout, stderr and the exit code, and a non-zero exit is a RESULT rather than a
tool failure: a grep that found nothing exits non-zero and nothing is wrong.
Creating one opens a console in it, because that is what you were going to
do next. --skip-console exits instead, which is what a script wants.
The other flags worth knowing: --idle-timeout for how long it
waits before sleeping, --vcpus and --mem-mib for its size,
--image to start from a build rather than the stock template,
--volume to attach durable storage, --url-auth org to keep its URL
between you and the fleet, --label k=v so
pilot machine ls --label finds it again, and --schedule to give it a
cron of its own (scheduled jobs).
The default size, 1 vCPU and 512 MiB, is restored from a snapshot of a machine that already booted, which is what makes a create take well under a second. Any other size boots a kernel at that size instead, because a memory image only loads at the size it was taken at, so it costs a few seconds once. The guest gets exactly the size you asked for, and every wake after its first suspend is the ordinary instant restore.
A larger root disk
The root disk is 2 GiB unless you ask for more. --disk 8GiB on
pilot machine create, pilot machine fork or pilot template fork
gives it more, up to 64 GiB, and the filesystem already fills the disk when
the command returns. This is not a boot: a create still restores in well under a second.
The space you do not use costs nothing. You pay for the blocks the machine writes, never for
the size, so ask for the room the work needs: dependencies, a browser, a mobile toolchain.
pilot machine create build-box --disk 16GiB --skip-console
pilot machine fork golden --disk 8GiB # more room than its source
pilot machine resize build-box --disk 32GiB # grows in place
pilot machine exec build-box -- df -h /
A fork keeps the size of its source and may ask for more, never less.
pilot machine resize --disk grows a machine that already exists. A running one
grows in place with every process still running. A sleeping one grows when it next wakes.
A disk only grows. Over the API and in the SDKs the field is disk_gib, and over MCP
it is disk_gib on create_machine, fork and
resize_machine.
Files in and out
Files are raw bytes over the API, so a binary survives the round trip byte for byte. A path is absolute or relative to the machine user's home. A write lands atomically, so a reader never sees half a file, and creates the directories it needs. A directory moves as a streamed archive.
pilot file push ./seed.sql scratch:/tmp/seed.sql
pilot file pull scratch:/var/log/app.log ./app.log
pilot file edit scratch:/etc/app/config.toml
pilot file ls scratch:app --recursive --exclude node_modules
pilot file cat scratch:app/package.json
pilot file rm scratch:/tmp/seed.sql
pilot file edit pulls the file, opens your editor, and pushes it
back when you close it.
Processes that outlive the connection
exec waits for its command. A process is the same command started
and left running: it has a name, it keeps running when you disconnect, and you come back to
it by name to read its output, see how it ended, signal it, or remove it.
pilot process start scratch dev --restart always -- npm run dev
pilot process start scratch build --keep-awake -- npm run build
pilot process output scratch build --follow
pilot process get scratch build
pilot process signal scratch build INT
pilot process rm scratch build
- Everything after
--is the command, run as given.--shellruns one string through the shell instead.--cwd,--envand--usermean what they mean for exec. - Output is kept on the machine's disk, stdout and stderr separately, up to
64MiB of each by default, and addressed by byte offset.
--offsetreplays from any point still held, and--followkeeps reading until the process ends, then says how it ended. - A restart policy of
never(the default),on-failureoralwaysdecides what happens when it exits, and after a cold boot. --keep-awakekeeps the machine from sleeping while the process runs. A dev server should not have it, so the machine still sleeps when nobody is using it. A build or an agent run should.- A value passed with
--envstays in the process's memory and is never written to the machine's disk, which is why such a process is not restarted after a cold boot. Put a secret there rather than in the command line.
A suspended machine resumes with every process where it was. A checkpoint or a fork of a running machine carries its processes too, still running, so a dev server started in one keeps serving in the fork.
Reaching a port
The machine's URL serves port 8080 over HTTP. Everything else is reached
through a tunnel from your own machine: a database client, a debugger, or ssh with
-W as a proxy command.
pilot proxy 5432
pilot proxy 8081:8080 9229
URLs and domains covers reaching another port over HTTP instead, and how to put a machine's URL behind an API key.
Consoles that outlive the connection
A console is a session on the machine, not a pipe to your terminal. Detach
with ctrl-\ and whatever you started keeps running. Coming back replays what
was printed while you were away.
pilot console scratch
pilot session ls scratch
pilot attach scratch
pilot session ls shows each session and whether it is
busy, which is also what the idle monitor reads. pilot session kill
ends one.
Sleeping, waking, and background work
A machine suspends 2s after its last request, exec or stream byte by default, and wakes on the next request, exec or attach. Suspend is a freeze rather than a kill, so every process resumes where it was, and a suspended machine holds no memory and no CPU on its host. A request that arrives while the suspend is still being written cancels it, so a machine in use never waits for one. Five things count as activity:
- A request, an exec or a stream in flight. A long silent build under exec is never suspended.
- A process started with
--keep-awake, while it runs. - A console session with a command running, even after you detach. The guest reads its own process tree, so a build whose output goes to a file still counts and a shell sitting at a prompt does not.
- The guest using CPU with nobody connected, such as a detached install or test run.
- Traffic to the machine: guest to guest on
.internal, or a reply to a connection it opened.
An open connection that is carrying nothing is NOT activity. A dev server's live-reload stream to an open tab, or an idle websocket, lets the machine suspend. The tab's connection is held open while the machine sleeps and closed when it next wakes, or when the tab sends a byte, so the client reconnects to a machine that is already awake. A client should re-check its state when it reconnects: an event sent while the old stream was being closed is not replayed.
What none of them see is a process idle between bursts of its own, such as a worker that polls an outside queue every minute: a suspended guest fires no timers. For those, say how long the machine should wait after its last activity.
pilot machine create worker --idle-timeout 30m
What a machine is using
| You want | Run |
|---|---|
| One machine's CPU and memory |
pilot machine metrics <machine>
|
| Every machine of an organization, as Prometheus text |
GET /v1/metrics
|
| The end of the console log, not the boot |
pilot machine logs <m> --tail 50
|
| The processes inside it |
pilot ps ls <machine>
|
A machine runs a NAMED set of processes: the image's own command is
app, a compose file with two services on one build context adds a second, and
anything started with pilot process start adds its own. pilot ps start,
stop and restart act on one of them and leave the rest alone, and
pilot ps output is that process's output rather than the machine's console.
CPU is a TOTAL in seconds, not a rate. Take two readings and divide by the time between them. It never goes down, including across a suspend, so a difference is always real work. Memory reads as zero while a machine is suspended, which is the truth rather than a gap in the data: a suspended machine holds no memory anywhere.
Stop naming the machine
pilot use sets a default for the directory you are in, and every
machine command then takes no name at all.
pilot use scratch
pilot exec -- npm test
Destroying one
pilot machine destroy is irreversible and takes every checkpoint
of that machine with it. A sleeping sandbox is charged for its disk and nothing else
(billing), so there is rarely a reason to destroy one to
save money. Destroy it when you want it gone.