Lifecycle

Create, list, stop, resume, fork and delete sandboxes, and how their status and desired state move.

A sandbox is created running, can be stopped and resumed any number of times, and ends when you delete it.

pols new --name web --size large    # create and wait until it runs
pols ls                             # your sandboxes, newest first (--all adds deleted ones)
pols get web                        # one sandbox
pols stop web                       # shut down; the disk is kept, CPU and RAM charges stop
pols resume web                     # boot the same disk again
pols fork web --name web-try        # a new running sandbox with a copy of web's disk
pols rename web-try web2            # a new name; its addresses do not change
pols rm web                         # delete the sandbox and its disk

Sandboxes are named by ID (sbx_...) or by name. Every sandbox has a name: the one you give it, or a generated adjective and animal like braveotter. A name is unique among your org’s sandboxes that are not deleted and consists of lowercase letters, digits and dashes, starting with a letter. Each command acts on one sandbox.

Names and renaming

pols rename SANDBOX NAME (PATCH /v1/sandboxes/{sandbox} with {"name": ...}, or the MCP tool sandbox_rename) gives a sandbox a new name. Renaming to a name another sandbox of the org has fails with 409 conflict, and a deleted sandbox cannot be renamed. The VM is not touched.

The ID never changes, so use it where a stable identifier matters, such as in scripts that outlive a rename. A name is never part of a sandbox’s addresses: they use its host label, a generated name with a random suffix like braveotterk3f9, which is set at create and stays the same through a rename, so links already handed out keep working.

Creating a sandbox

pols new (POST /v1/sandboxes) takes:

Option	Meaning
`--name`	a name; without one, a generated one like `braveotter`
`--size`	`small` (the default), `default`, `large` or `xlarge`; without `--size`, `small` or the smallest size whose disk holds the template; see sizes
`--template`	the template to start from, by ID or name; default `ubuntu-24.04`
`--env`, `--env-file`	environment variables for every command; see Secrets and environment
`--secret`	vault entries to set as environment variables
`--egress`, `--allow`	the outbound network policy; see Network egress

Creating checks your org’s quotas for running sandboxes, total sandboxes and monthly hours.

Status and desired state

Every sandbox has two fields that together describe where it is going:

desired_state is what you last asked for: running, stopped or deleted, or standby, which the control plane sets for an idle sandbox.
status is where it is now: pending, running, stopped, deleted, error or standby.

standby means the sandbox’s VM is frozen with its memory kept because it was idle; the next call that needs it wakes it.

The API records the desired state and returns right away; the control plane then drives the VM there (see Architecture). The CLI and the MCP tools wait until status reaches desired_state. Pass --no-wait to return at once, and --wait-timeout to wait longer than the default 5 minutes. Over the API, poll GET /v1/sandboxes/{sandbox} until the two match. A standby sandbox whose VM stopped is also settled: it stays at status=stopped with desired_state=standby.

A sandbox reports running once its guest agent answers, so commands and file transfers work as soon as it does. While it boots, it keeps its previous status.

If the host fails to carry out a transition, the sandbox goes to error and its last_error says why. A sandbox in error cannot be used any more; delete it and create a new one.

Standby

A running sandbox that nothing uses for the server’s standby period (15 minutes by default; the account page shows yours under Usage and quotas) while its CPU and outbound traffic stay low goes to standby: its VM is frozen with its memory kept, so it uses no CPU.

Use means a call on its contents (exec, files, computer use, CDP, a desktop link) or SSH and HTTP through the edge. Any of these wakes it, and so do resuming, forking and saving it as a template; the call waits until the sandbox runs again, usually within a second, and answers 503 waking if that takes too long. Reading it (GET) does not wake it.
A sandbox in standby keeps its place among the org’s running sandboxes, and its standby time does not count against the monthly sandbox-hours. When the org’s monthly sandbox-hours or credit run out, it is stopped with the running ones.
It is billed for RAM or, on the new engine, for its memory as disk; see Usage and billing. Its disk keeps being billed.

Stopping and resuming

Stopping shuts the VM down gracefully (or powers it off at once if it is still booting), keeps its disk and ends its CPU and RAM charges; its disk is still billed until you delete it (see Usage and billing). Running processes and the contents of memory are not kept: resuming boots the same disk again, like switching a computer back on.

A stop or resume that conflicts with a transition still in progress is answered with 409 conflict; wait until the sandbox has arrived and try again. Resuming checks the running-sandbox and monthly-hours quotas.

Deleting

pols rm (DELETE /v1/sandboxes/{sandbox}) stops the VM and removes it, its disk and its snapshots. Its environment variables are erased at the same moment. This cannot be undone. The sandbox stays in pols ls --all with status deleted, so its usage remains traceable.

Watching resource use

pols stats web             # CPU, memory and disk use of one sandbox
pols stats web --history   # with the samples of the last hour
pols stats                 # all running sandboxes

The control plane samples every running sandbox every 30 seconds and keeps the last hour in memory. The samples are also in the API (GET /v1/sandboxes/{sandbox}/stats, GET /v1/org/stats) and in the stats field of a running sandbox.

What happened in a sandbox (commands, desktop actions, screenshots and its lifecycle) is on its timeline.