Skip to content
pilots
Dashboard
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. --shell runs one string through the shell instead. --cwd, --env and --user mean 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. --offset replays from any point still held, and --follow keeps reading until the process ends, then says how it ended.
  • A restart policy of never (the default), on-failure or always decides what happens when it exits, and after a cold boot.
  • --keep-awake keeps 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 --env stays 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.