> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkbloom.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox lifecycle: stop, resume, and retention

> What persists across a stop, where the workspace lives, how image upgrades work, and how the idle limit, keepalive, and maximum affect long-running work.

A sandbox is billed only while it runs. This page covers stopping and resuming
one, what survives, how images change, and how to keep long work alive.

## Stop and resume

```sh theme={null}
darkbloom-sandbox-cli stop sbx-…       # keeps the workspace
darkbloom-sandbox-cli resume sbx-…     # boots it again on the same workspace
darkbloom-sandbox-cli delete sbx-…     # the sandbox and its workspace, for good
darkbloom-sandbox-cli list             # your sandboxes, newest first (--all: the ended ones too)
darkbloom-sandbox-cli status sbx-…     # one sandbox: state, why it stopped, its deadlines
```

The console's sandbox page can stop a persistent sandbox too (**Stop sandbox**,
which keeps the workspace), but it cannot resume one: only the CLI that created
it can.

`list` shows the sandboxes that are not over. Deleted ones and ones that failed
to start stay on record for at least 30 days: `list` only counts them (`77
ended sandboxes … are not shown`), and `list --all` lists them. The service's
list is bounded (100 sandboxes; more only when more than that have not ended):
when it is full the count reads `at least …`, and `status sbx-…` still shows an
older one. `list --json` prints the service's whole list.

## What persists

Across a stop and resume you keep:

* the workspace (`/workspace` or `~/workspace`): your files, their owners and
  permissions, links, git repositories, and Codex's login and sessions, since
  `CODEX_HOME` is there;
* the sandbox ID;
* its size;
* your SSH key.

Everything outside the workspace starts fresh at every boot: a package
installed with `apt` or `brew` outside it is gone after a resume.

## Where the workspace lives

The workspace stays on the one Mac it was created on and is **not backed up**.
A resume runs only there:

* if that Mac is busy, the service answers `no_capacity`;
* if it is offline, `host_unavailable`;
* if it is only getting ready (it has just updated or restarted, or is
  downloading the sandbox's image), `host_starting`, which is worth a retry
  within the minute.

None of these answers changes the sandbox: it stays stopped as it was, and
`status` keeps saying why it stopped. If the Mac leaves the fleet, the
workspace is lost with it. Keep your work in git, pushed elsewhere.

`status` and `list` say when a stopped sandbox's Mac is offline or was removed
(`home` in the API; a **Mac offline** or **Mac removed** badge in the console):

* **Offline under a day:** it resumes once the Mac is back, and still counts
  toward your workspace storage.
* **Offline a day or more:** it no longer counts toward your storage, and it
  resumes only if that Mac returns.
* **Removed:** it can never resume (`409 host_removed`) and no longer counts
  toward your storage. Delete it before it is deleted automatically (`status`
  says when): deleting erases its workspace key; the automatic deletion keeps
  it.

## Retention

A stopped sandbox costs nothing. If it stays stopped for 30 days, Darkbloom
deletes it and its workspace; `status` and `list` show the date. Resume it
before then: once it runs again, the next stop starts a new 30 days.

## Each resume is a new boot

A resume uses a fresh nonce, gets a new attested host key (the CLI pins it on
the next `ssh`), a new hold, and billing from `ready`.

![Sandbox console sandbox detail showing state, size, workspace and a state timeline through requested, placed, booting, attested and ready](https://mintcdn.com/eigenlabs-f49d2e97/2TtlNanikOmTAJr5/images/console/sandboxes-detail.png?fit=max\&auto=format\&n=2TtlNanikOmTAJr5\&q=85\&s=5da764d390dca12e9311fb7eb011d784)

A sandbox's page in the sandbox console: its state timeline from requested to ready. Example data.

## Image upgrades

Darkbloom pins one agent image per platform and moves the pin when it ships
fixes. A running sandbox keeps its image until it stops; a stopped one keeps
the image it was created with.

A plain `resume` changes it only to a re-signed twin: the same image, with the
same guest content, signed again for the Mac's new add-on. The CLI verifies a
twin before it adopts it, and says so (`resumed sbx-… on image …: this
workspace's image … re-signed for its Mac's new add-on`). The Macs of the fleet
take a new release one by one, over hours or days, and a sandbox follows the
Mac that holds its workspace: `status` and `list` say for each sandbox whether
its own Mac still boots its image (`current`) or boots another now (`upgrade
available`), so two of your sandboxes can differ.

Once its Mac boots any other image, a plain `resume` changes nothing and says
so (image digests shortened here):

```text theme={null}
sbx-… was not resumed: the plane boots agent-linux sandboxes from image 1a2b3c4d5e6f now, and this workspace's image is 0f1e2d3c4b5a (409 upgrade_required). A plain resume changes a sandbox's image only to a verified re-signed twin of it (the same guest content).
An upgrade boots 1a2b3c4d5e6f on the same workspace (its files, volume and Mac), with the same sandbox ID and the same SSH key; …
To upgrade and resume it: darkbloom-sandbox-cli resume sbx-… --upgrade-image
```

On a terminal, `resume` instead starts `sbx-… needs an image upgrade to
resume:`, shows both images and what an upgrade keeps, and asks `Upgrade sbx-…
to image … and resume it? [y/N]` before it upgrades to the image it showed.
`--upgrade-image` upgrades without asking (for scripts and `--json`). An
upgrade keeps everything a resume keeps: only the image changes, and the new
boot is attested like every boot.

* Only a **stopped, persistent sandbox that has run before** can upgrade (else
  `409 upgrade_not_allowed`): stop a running one first. A sandbox that was
  stopped before it ever started also can: its workspace was never created, so
  the upgrade only picks the image its first boot runs.
* There is no way back to the old image, and a failed upgraded boot loses
  nothing: the sandbox stays stopped on the new image, and `resume` retries.
* If the CLI loses the service's answer, it keeps the request: run the same
  `resume` again, which replays exactly it. Do not use an older CLI or delete
  the record meanwhile.

## Idle limit, keepalive, and maximum

A running sandbox stops by itself in two ways, so you never pay for one you
forgot:

* **Idle limit** (`--idle-minutes`, 15 by default): it stops after that long
  with nothing attached (`ssh`, `vnc`, `codex`) and no network traffic. Work
  left running inside does **not** count: a build or training run in `tmux` or
  under `nohup` is stopped when you disconnect. An ephemeral sandbox loses its
  workspace with it.
* **Maximum** (`--max-minutes`, 240 by default): every boot stops after that
  long, however busy. `extend` raises it.

Before you leave work running unattended:

```sh theme={null}
darkbloom-sandbox-cli keepalive sbx-… 45m       # 90m, 2h, 1h30m, … ; off to cancel
darkbloom-sandbox-cli extend sbx-… 120          # 120 more minutes before the maximum (15 or more, 1440 in total)
darkbloom-sandbox-cli status sbx-…              # what keeps it running, and until when
```

A keepalive holds off only the idle limit, and only up to the boot's keepalive
limit: by default an hour from the boot's start. Ask for more and the CLI says
until when it was held; past the limit the service refuses it
(`409 keep_alive_limit`) and the idle limit applies again.

For longer unattended work, keep a client attached (leave
`darkbloom-sandbox-cli ssh sbx-…` open on your machine, for example in a local
`tmux`) or let it move traffic. A resume starts each boot without a keepalive
unless you pass `resume sbx-… --keep-alive DURATION` (held to the same limit).

The [troubleshooting page](https://docs.darkbloom.dev/sandboxes/troubleshooting.md) lists the stop reasons
and what to do next.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.