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

Creating checks your org's [quotas](/docs/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`, 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](/docs/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 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](/docs/account/orgs/#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](/docs/account/orgs/#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

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

What happened in a sandbox (commands, desktop actions, screenshots and its lifecycle) is on its [timeline](/docs/sandboxes/timeline/).