---
title: Lifecycle
description: 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.

```sh
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](/concepts/machine/#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](/sandboxes/vault/) |
| `--secret` | vault entries to set as environment variables |
| `--egress`, `--allow` | the outbound network policy; see [Network egress](/sandboxes/egress/) |

Creating checks your org's [quotas](/getting-started/limits/#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](/concepts/architecture/#desired-state-and-the-reconciler)). 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

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