# How to cap what a single sandbox can cost

Pass `maxTotalCostMicros` to set a ceiling over the sandbox's whole life.

**On Runtime, the server holds the cap for each sandbox. A runaway agent or a
forgotten long-lived machine stops at the amount you chose.** CPU is billed on
measured use. So the cap lasts longer than it would on a provider that bills
allocated vCPUs. For example, $50 covers 625 fully busy hours of a 2 vCPU,
4 GiB sandbox at $0.08 an hour. It covers 1,600 hours of the same
sandbox waiting, at $0.03125 an hour (rates checked 25 October 2026,
[pricing](/docs/pricing)).

## One cap, the whole life

`maxTotalCostMicros` answers the question "how much may this sandbox cost, ever?"
It counts everything the sandbox is charged while it runs. When the total
reaches the cap, the sandbox stops, with `stopReason` set to `lifetime_cap`.
Money is in microdollars: 1,000,000 is one US dollar. The cap has no default
([the create body](/docs/api#sandboxes)).

## Set it on a create

```ts
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create({
  vcpu: 2,
  memoryMiB: 4096,
  timeoutSeconds: 1800,
  maxTotalCostMicros: 5_000_000, // stop after $5 over its whole life
});
console.log((await sbx.exec("nproc")).stdout);
```

```python
from withruntime import Sandbox

with Sandbox.create(vcpu=2, memory_mib=4096, timeout_seconds=1800,
                    max_total_cost_micros=5_000_000) as sbx:
    print(sbx.exec("nproc").stdout)
```

## Cap a sandbox that runs for hours

A sandbox has no time limit unless you set one. It runs while it works. A
`persistent` paid sandbox runs until you stop it, whether it is idle or not, as
long as the account has credit. A long-lived agent or dev server needs exactly
this behavior. This is also the case a lifetime cap is built for.

```ts check
import { Sandbox } from "withruntime";

const server = await Sandbox.create({
  persistent: true,
  maxTotalCostMicros: 50_000_000, // at most $50 over its life
});
await server.update({ maxTotalCostMicros: 80_000_000 }); // raise it later; null removes it
```

```python check
from withruntime import Sandbox

server = Sandbox.create(persistent=True, max_total_cost_micros=50_000_000)
server.update(max_total_cost_micros=80_000_000)
```

```bash no-run
runtime sandboxes create --max-total-cost 20   # withruntime 0.7.0; dollars here
runtime sandboxes update "${id}" --persistent on --max-total-cost 50
```

The CLI takes dollars. The SDKs and the API take microdollars. After a stop, a
sandbox keeps its disk, billed as paused storage. So `restart()` brings it back.

## Other limits that bound cost

| Control                 | What it bounds                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `timeoutSeconds`        | An optional time limit, 60 to 86,400 seconds (24 hours); none by default              |
| `onLeaseEnd`            | `"pause"` (the default) or `"stop"` at the limit or when credit runs out              |
| `idlePauseSeconds`      | Pauses after 300 seconds idle by default; 60 to 86,400 |
| `cpu`, `cpuFloorMillis` | The waiting charge: a higher floor or `"reserved"` raises it                          |
| A key's daily limit     | Everything one agent's key commits in any 24 hours                                    |

A paused sandbox stops billing compute immediately. It costs $0.08
per decimal GB of saved state per 30-day month. So `onLeaseEnd: "pause"` with
an idle pause is the cheapest way to keep a machine around
([pause and resume](/how-to/pause-and-resume-a-sandbox)).

## Mistakes to avoid

- **Dollars in the SDK.** `maxTotalCostMicros: 50` is fifty microdollars, not
  fifty dollars. Write `50_000_000`.
- **Expecting a lifetime cap to pause.** At the cap, the sandbox stops. Its
  `stopReason` is `lifetime_cap`. Start a new sandbox if the work needs more
  ([a sandbox stopped on its own](/docs/troubleshooting#a-sandbox-stopped-on-its-own)).
- **A persistent sandbox with no cap.** It runs for as long as the account has
  credit. Give it `maxTotalCostMicros`, or give its key a
  [daily spending limit](/how-to/set-a-daily-spending-limit).
- **Counting storage as covered by the cap.** Images, volumes and kept
  snapshots are charged as storage on their own
  ([storage prices](/docs/pricing#snapshots-images-and-volumes)).

## Check what a sandbox cost

`runtime usage` prints the balance and what each kind of resource was charged.
`runtime usage --json` gives every figure in integer microdollars. To see what
the same work would cost elsewhere, `runtime compare --from e2b` prices your
last 30 days at the rival's published rates. For estimates before you run, use
the [sandbox cost calculator](/calculators/sandbox-cost-calculator).

Facts on this page were checked on 26 October 2026.