Access
Until your account is granted sandboxes, the sandbox API answers as if it did not exist. The CLI says:the plane found nothing for this account (404 not_found: …): agent sandboxes may be off on https://api-sandbox.darkbloom.dev/, or the account may not be allowlisted for them. They are by invitation: ask your Darkbloom contact for access, …
Create and placement
| You see | What it means | What to do |
|---|---|---|
no Mac has room for a c4-m8 linux_arm64 sandbox right now, so sbx-… did not start (failed: no_capacity) | The fleet had no room for that size. Nothing was charged. | Retry in a few minutes, or choose a smaller size (sizes). |
create waits a few seconds and goes on after the request did not finish or a lost connection | Its answer was lost. create finds the sandbox the service made by the nonce it sent, or sends the same create again (twice at most). | Nothing. If it still fails it names the nonce: list shows the sandbox if the service made it; delete it if you do not need it. |
create says sbx-… waits for a Mac: reading it until it is placed | Darkbloom accepted the sandbox and is still finding it a Mac. create waits, because it records the image the sandbox boots, which is known once it has a Mac. | Nothing: it goes on by itself, for up to 5 minutes. If you interrupt it (Ctrl-C), the sandbox is left without a record on this computer: delete it with the command that line names, darkbloom-sandbox-cli delete sbx-…. |
sbx-… was created but no Mac took it within 5 min; deleted sbx-… | No Mac took the sandbox while create waited, so create deleted it (it had no record yet, so nothing was using it). | Create it again later (with a new --nonce if you passed one), or with another size (darkbloom-sandbox-cli sizes). |
sbx-… was created but …: delete it with darkbloom-sandbox-cli delete sbx-… | create could not follow the sandbox to its Mac, or could not delete it once it gave up (the service did not answer, or refused), so the sandbox is left without a record on this computer. | Run that command once the service answers again. |
the plane answered a read of sbx-… with …: refused, nothing was recorded, and sbx-… was not deleted | While create waited, the service answered with another sandbox than the one this create made. create trusts no such answer: it records nothing and deletes nothing. | Check the sandbox with the status … --json command the message names (its nonce is this create’s if it is yours); if it is yours, delete it with the delete command the message names. Tell your Darkbloom contact. |
sbx-… was created but is gone | The sandbox was deleted while create waited (from another client, or by Darkbloom). | Nothing to clean up: create another if you need one. |
sbx-… stopped … before this create recorded it, or was deleted … before this create recorded it | Another client (the console, another CLI) stopped or deleted the sandbox while create waited, so create failed and recorded nothing. | A stopped one cannot be resumed from this computer: delete it with the command the message names, and create another. |
…: this client has a record of sbx-…, so create does not delete it, or … while this create waited for its placement …: this client's record of sbx-… is left as it was | A create repeated with --nonce found its sandbox, which this computer already recorded, still waiting for a Mac (or stopped or deleted meanwhile). create never deletes a sandbox it has a record of. | darkbloom-sandbox-cli status sbx-… shows it. Run the same create again later, or delete the sandbox if you do not need it. |
Resume
| You see | What it means | What to do |
|---|---|---|
the Mac that holds sbx-…'s workspace has no room for it right now … (409 no_capacity) | A resume runs only on its workspace’s Mac, which is busy. | Retry resume in a few minutes. |
the Mac that holds this sandbox's workspace has just restarted … (or … is downloading the image this sandbox boots from …, … is reconnecting to Darkbloom …) … nothing changed and the sandbox is still stopped | That Mac is not busy, only getting ready: after a Darkbloom update or a restart it takes sandboxes again within a minute or two. Nothing was charged and the retry costs nothing. | Run the same resume again in a minute (a few seconds for reconnecting). |
the Mac that holds sbx-…'s workspace is offline or not taking sandboxes … (409 host_unavailable) | That Mac is away; the workspace is kept on it. | Retry resume once it is back; status shows since when it is offline and until when the workspace is kept. |
the Mac that held sbx-…'s workspace was removed, so sbx-… cannot resume … (409 host_removed), or status says its Mac was removed | That Mac left the fleet for good; the sandbox no longer counts toward your storage. | delete it; no retry will resume it. |
sbx-… was not resumed: the plane boots … from image … now, … (409 upgrade_required) | Darkbloom moved the image pin. | See image upgrades. |
sbx-… is already running (ready), so there is nothing to resume (or already starting, still stopping) (409 conflict) | resume boots only a stopped sandbox; nothing changed. | Use it (ssh), or wait until status says stopped and resume again. |
a resume of sbx-… is saved and its outcome is not known yet | An earlier resume lost the service’s answer, or its workspace’s Mac had no room or was offline (or, with an older CLI, resume was run on a running sandbox). | Run darkbloom-sandbox-cli resume sbx-…: it sends the saved resume again, which settles it. If it still says so while the sandbox runs, stop the sandbox, then resume it. |
Billing
| You see | What it means | What to do |
|---|---|---|
… the account's balance could not cover the hold for its boot (failed: unfunded) | Your balance cannot hold an hour of the size. | Add funds, then run the command again. |
: Darkbloom's billing could not charge for it (billing_lapsed), a problem on Darkbloom's side, not the account's (or unbillable) | Darkbloom’s side. | Resume it in a few minutes (a create that did not start, failed: unbillable: run the create again); the workspace is kept. |
Stops
| You see | What it means | What to do |
|---|---|---|
stopped after 15 idle minutes with no client attached and no traffic | The idle limit. | See idle limit, keepalive, and maximum: keepalive, or keep a client attached. |
stopped at its maximum of 240 minutes per boot | The maximum. | resume; next time --max-minutes or extend. |
: its Mac went offline while it ran (host_lost) | The Mac disappeared; billing stopped then. | resume when the Mac is back (persistent sandboxes), unless status says its Mac was removed: then delete it. |
Attestation
| You see | What it means | What to do |
|---|---|---|
: its boot failed attestation (verification_failed) | The service could not verify the boot’s statement, so the boot never became ready (and was not billed). | Create a new sandbox; tell your Darkbloom contact. |
ssh, vnc, or attest refuses to connect because verification failed, or the build is revoked | Your CLI could not prove the boot runs a Darkbloom-qualified build on a genuine Mac (or Darkbloom revoked that build). | Do not work around it (no other client, no unattested key): delete the sandbox, create a new one, and report it. This check is what makes the guarantees in security hold. |
Limits and the desktop
| You see | What it means | What to do |
|---|---|---|
409 limit_reached, 429 rate_limited | A per-account limit or the start rate. | See limits. |
sbx-…'s screen is locked. …, or a macOS desktop that shows only the wallpaper and takes no input | The desktop is locked: macOS locks it after 20 minutes without input unless a CLI connection turned that off earlier in the boot (or something in the sandbox locked it). | stop and resume it, then connect within 20 minutes. See the desktop (VNC). |
curl: (56) CONNECT tunnel failed, response 403; see network and
egress.
