Skip to main content
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

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

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):
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:
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 lists the stop reasons and what to do next.