# How to pause a sandbox when it is idle

Set `idlePauseSeconds`; after that many seconds with no request the sandbox pauses, and the next request wakes it.

**On Runtime an idle sandbox can stop billing compute by itself, and keep its
memory, files and processes while it sleeps.** Left running and idle for
30 days, a 2 vCPU, 4 GiB sandbox costs about $22.50. Paused, it costs
$0.08 per decimal GB of saved state a month, and a pause took a median 234 ms,
measured on 24 September 2026 ([speed](/docs/speed)). On the free trial a
paused sandbox counts toward neither the eight at once nor the 50 hours.

## Set an idle timeout

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

const sbx = await Sandbox.create({ idlePauseSeconds: 600 }); // ten idle minutes
await sbx.exec("echo started > /workspace/log.txt"); // each request restarts the clock
await sbx.update({ idlePauseSeconds: 1800 }); // change it later; 0 turns it off
```

```python check
from withruntime import Sandbox

sbx = Sandbox.create(idle_pause_seconds=600)  # ten idle minutes
sbx.update(idle_pause_seconds=1800)  # change it later; 0 turns it off
```

```bash no-run
id=$(runtime sandbox create --name dev --get-or-create --idle-pause 900)
runtime sandbox update "${id}" --idle-pause 0     # never pause for idleness
```

An agent over MCP sets it with `runtime_sandbox_manage`, `"action": "update"`
and `idlePauseSeconds` ([MCP](/docs/mcp)).

## What counts as activity

The idle clock restarts on every exec, file, process, terminal, desktop or
preview request. When it runs out, the sandbox pauses as if you had called
`pause()`. With automatic wake on, which is the default, the next of those
requests wakes it and runs.

| Setting                        | Value                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `idlePauseSeconds`             | 60 to 86,400; 0 is never                                                      |
| Default                        | 300, only when `timeoutSeconds` is left out, and only until the first request |
| Not set by default             | With an explicit lease, an image or a snapshot                                |
| `sbx.info.idlePauseUnusedOnly` | `true` for that default; `false` for an idle time you set                     |
| CLI                            | `--idle-pause <seconds>` on `create` and `update`                             |
| Python                         | `idle_pause_seconds`                                                          |

## What it saves

A worked example from the published rates, for a 2 vCPU, 4 GiB sandbox that
waits on a person and is in use two hours a day:

| Pattern over 30 days                | Compute                          | Paused storage              |
| ----------------------------------- | -------------------------------- | --------------------------- |
| Left running all month, mostly idle | about $22.50 at $0.03125 an hour | none                        |
| Idle pause, 60 hours running        | $1.88 at the same waiting rate   | $0.08 per GB of saved state |

Busy time is billed on measured CPU, $0.025 per active vCPU-hour, so real use
adds to both rows alike. Paused storage counts only the disk and memory blocks
the sandbox alone owns, not the disk size you asked for
([paused storage](/docs/pricing#paused-storage)).

## Mistakes to avoid

- **Setting it below what a slow step needs.** A request resets the clock, but
  a long `exec` is one request. Pick an idle time longer than the gaps between
  your calls, not the length of a command.
- **Leaving an unattended job to run.** Idle time counts requests, not CPU. A
  long job started with `spawn` and left alone is paused with the sandbox when
  the idle time runs out, and carries on only after a wake. Give unattended
  work a longer idle time, or 0.
- **Forgetting the lease.** Idle pause and the lease are separate. A busy
  sandbox still pauses when its `timeoutSeconds` runs out, unless you
  [extend the lease](/how-to/extend-a-sandbox-lease).
- **Turning automatic wake off by accident.** With `autoWake: false`, an
  idle-paused sandbox answers `sandbox_paused` until you call `wake()`.

## Related

- [Wake a sandbox on request](/how-to/wake-a-sandbox-on-request) for what the
  next request sees.
- [Find a sandbox by name](/how-to/find-a-sandbox-by-name) to come back to the
  same one tomorrow.
- [Per-user dev environments](/use-cases/per-user-dev-environments), idle most of
  the day.
- [Pause when idle](/docs/javascript#pause-when-idle) in the SDK reference.

Facts on this page were checked on 25 September 2026.