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 and billing stops
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 rm web                         # delete the sandbox and its disk

Sandboxes are named by ID (sbx_...) or by name. A name is unique in your org and consists of lowercase letters, digits and dashes, starting with a letter. Each command acts on one sandbox.

Creating a sandbox

pols new (POST /v1/sandboxes) takes:

Option	Meaning
`--name`	a name; without one, use the ID
`--size`	`small`, `default` (the default), `large` or `xlarge`; 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.
status is where it is now: pending, running, stopped, deleted or error.

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

Stopping and resuming

Stopping shuts the VM down gracefully (or powers it off at once if it is still booting), keeps its disk and closes its billing interval. 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.