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 it costs nothing while it does.

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).

Files in and out

Files move over the exec stream rather than over a copy service, so a binary survives the round trip byte for byte and there is nothing to open on the network.

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 edit pulls the file, opens your editor, and pushes it back when you close it.

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 after 60s of quiet 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. Three things count as activity:

• A request or an exec in flight, for its whole life. A long silent build under exec is never suspended.
• 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.
• Guest to guest traffic on .internal, and open sessions between machines.

What none of them see is a process nothing is connected to. A daemon started with setsid leaves the session tree by definition, and a worker polling an outside queue was never in it. 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

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 through the agent adds its own. pilot ps start, stop and restart act on one of them and leave the rest alone, and pilot ps logs 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. There is no reason to destroy a sandbox to save money, because a sleeping one costs nothing. Destroy it when you want it gone.