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

# Limits and billing

> Per-account limits for running sandboxes, storage, vCPUs, and start rate, plus how per-second billing and hourly holds work.

Limits are per account, unless Darkbloom set your grant's own: then those
replace the values below (a daily egress limit included), and your grant may
also limit vCPUs and sizes (`sizes` then lists only the sizes you may boot).

## Limits

| Limit | Value | When you hit it |
| - | - | - |
| Running sandboxes per account (starting, running, stopping, resuming) | 2 | `409 limit_reached`: `this account already has 2 running sandboxes and its limit is 2 (stopped sandboxes do not count); stop or delete one` |
| Workspace storage per account (running and stopped sandboxes, except stopped ones whose Mac was removed or has been offline a day) | 256 GiB | `409 limit_reached`: `this account's workspaces already hold 224 GiB of its 256 GiB limit (stopped sandboxes included) and this sandbox needs 64 GiB more; delete a stopped sandbox` |
| vCPUs of the running sandboxes together | none, unless your grant sets one | `409 limit_reached`: `this account's running sandboxes already use 8 vCPUs of its 8 vCPU limit and this sandbox needs 4 more (stopped sandboxes do not count); stop or delete one, or choose a smaller size` |
| Sizes you may boot | every size the platform offers, unless your grant names some | `409 size_not_granted`: `this account may not boot the size class c32-m128; its grant allows c4-m8, c8-m16` |
| How fast an account starts sandboxes (creates and resumes together) | 10 at once, then 1 a minute | `429 rate_limited`, with how long to wait |
| A boot's duration | 30–1440 minutes (`--max-minutes`) | the sandbox stops (`max_minutes`) |
| Egress per account per day (UTC) | none by default, unless Darkbloom set one for you or your grant's own | `409 limit_reached`: `this account's sandboxes moved … through Darkbloom's gateway today (UTC), its daily limit is …; creates and resumes are refused until … (running sandboxes are not stopped)` |
| Allowlist hosts | 1–64 exact lowercase hostnames | the CLI refuses it before sending; the API answers `422 invalid_request` |
| Sandbox records per account (ended sandboxes included, each kept at least 30 days after it ends) | 50,000 | `409 limit_reached`: `this account holds 50000 sandbox records and its limit is 50000: an ended sandbox's record is kept at least 30 days after it ends, so creates are refused until older ended ones are pruned or Darkbloom raises the limit (its operators are alerted)` |

An ended sandbox (deleted, or failed to start) stays in `status` for at least
30 days after it ends; then its record is removed. `list` shows every sandbox
that has not ended, however old, and `list --all` the newest ended ones too
(100 entries in all). Its charges stay in your billing history.

The numbers in a `limit_reached` message are your account's own; `list` shows
the sandboxes that count. A refused start is reported by the CLI as:

```text theme={null}
the plane is limiting how often this account sends such requests: wait 42 seconds, then run …
```

Repeating a resume whose outcome you did not read, or a resume the service
answers `upgrade_required`, does not count against the start rate.

## Prices

See [sandbox pricing](https://docs.darkbloom.dev/sandboxes/pricing.md) for every size and its hourly rate,
the Linux formula, and worked examples. `darkbloom-sandbox-cli sizes` reads the
live list and is the price you pay.

## Billing

* **Per second while it runs:** from the moment the sandbox is ready until its
  VM is gone (a stop takes seconds), at its size's price, with a one-minute
  minimum per charge (each boot, and each fresh hour it moves to; the service
  never opens a charge just for a boot's last minutes). Starting up and stopped
  sandboxes are free.
* **A hold per hour.** Before each boot starts, Darkbloom holds an hour at its
  size's price from your balance, and settles it to the seconds the boot ran. A
  boot that runs longer moves on to a fresh hour before each hour ends (one
  more hour held, the last one settled), so every second is billed and nothing
  is charged twice. If your balance cannot hold the first hour, the sandbox
  does not start (`unfunded`); if it cannot hold a later hour, the sandbox
  stops (a persistent one keeps its workspace). [Add credits](https://docs.darkbloom.dev/billing/add-credits.md)
  on the console's **Billing** page.
* **What you were charged.** A sandbox's cost shows two amounts: the estimate
  at its size's price, and what Darkbloom charged your balance (`cost.charged`
  in the API; **Charged** on the console's sandbox page). The charge counts
  each hour once it is settled, so it trails the estimate while the sandbox
  runs. A sandbox on a Mac your own account provides is not charged.
* **What it costs so far.** `status` shows the sandbox's price and both amounts
  on one line:

  ```text theme={null}
  $0.36/hour while it runs; about $0.24 so far (40 min 7 s billed), $0.18 charged to the balance so far (1 charge still open)
  ```
* **When it stops.** `status` shows when the service will stop a running
  sandbox (its idle limit and its maximum) and when it will delete a stopped
  one; `list` shows the same for each.
* **Darkbloom's own billing problems are not yours:** if Darkbloom cannot
  charge for more than 10 minutes, a running sandbox stops (`billing_lapsed`)
  with its workspace kept, persistent or not, and you resume it later. The CLI
  says `a problem on Darkbloom's side, not the account's`.

## Records and retention

An ended sandbox's record is kept at least 30 days, and a stopped sandbox is
deleted with its workspace after 30 days stopped. [Sandbox lifecycle](https://docs.darkbloom.dev/sandboxes/lifecycle.md)
covers both.


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