# How to pause a sandbox when it is idle

A Runtime sandbox pauses itself after 300 seconds of idle time. It wakes on the next request. `idlePauseSeconds` changes the wait.

**On Runtime, an idle sandbox stops billing for compute by itself. It keeps 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. Without
credit, a paused sandbox does not count toward the four running
at the same time, or toward the month's free usage.

## Change the idle time

```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 sandboxes create --name dev --get-or-create --idle-pause 900)
runtime sandboxes update "${id}" --idle-pause 0     # never pause for idleness
```

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

## What counts as activity

A sandbox is idle only when all of these are quiet: requests (exec, file,
process, terminal, desktop or preview), a command or terminal still running,
an open preview, port, SSH or tunnel connection, network traffic, and CPU. For
CPU, its processes must use less than a fortieth of a vCPU. When the idle time
runs out, the sandbox pauses as if you had called `pause()`, within about five
seconds. With automatic wake on, which is the default, the next request wakes it
and runs.

| Setting                       | Value                                                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `idlePauseSeconds`            | 60 to 86,400. 0 is never. A shorter time is raised to 60                |
| Default                       | 300, for every sandbox that can pause                                                            |
| Made before 27 September 2026 | Keeps its setting. `sbx.info.idlePauseUnusedOnly` marks the old default, which counted only until the first request |
| CLI                           | `--idle-pause <seconds>` on `create` and `update`                                                                   |
| Python                        | `idle_pause_seconds`                                                                                                |

## What it saves

A worked example from the published rates. It is 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, at $0.025 per active vCPU-hour. So real
use adds to both rows alike. Paused storage counts only the disk and memory
blocks that the sandbox alone owns. It does not count the disk size you asked
for ([paused storage](/docs/pricing#paused-storage)).

## Mistakes to avoid

- **Expecting a sleeping job to hold it awake.** A job that computes, downloads
  or keeps a connection busy counts as work. A job that sleeps for minutes
  between steps uses none of those, so the sandbox pauses under it. It carries
  on after the next wake. Give such work a longer idle time, or set 0.
- **Setting it below the gaps between your calls.** A command that runs holds
  the sandbox awake however long it takes. But the pause between two calls
  counts. An agent that thinks for two minutes between commands has its
  sandbox paused after one. The next command wakes it. Set 300 if the wait matters to
  you.
- **Setting a time limit as well.** Idle pause and a time limit are separate.
  A busy sandbox created with `timeoutSeconds` still pauses when that limit runs
  out, unless you [extend it](/how-to/extend-a-sandbox-lease). Leave the limit
  out, and only idleness pauses it.
- **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 October 2026.