# How to pause and resume a sandbox

Call `pause()` to save its files, memory and running processes, and `wake()` to carry on exactly where it stopped, on the same host.

**On Runtime a paused sandbox stops billing compute at once and costs $0.08 per
GB of saved state a month.** The same 2 vCPU, 4 GiB sandbox left running and
idle costs $0.03125 an hour, about $22.50 over 30 days. A pause took a median
234 ms, measured on 24 September 2026 ([speed](/docs/speed)), and a paid
sandbox stays paused for up to 365 days.

## Pause and wake

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

const sbx = await Sandbox.create({ timeoutSeconds: 600 });
await sbx.exec("echo state > /workspace/state.txt");
await sbx.pause(); // memory and files are kept; compute billing stops

// Later, even from another process:
const again = await Sandbox.connect(sbx.id);
await again.wake({ timeoutSeconds: 1200 });
console.log((await again.exec("cat /workspace/state.txt")).stdout); // state
await again.stop();
```

```python check
from withruntime import Sandbox

sbx = Sandbox.create(timeout_seconds=600)
sbx.exec("echo state > /workspace/state.txt")
sbx.pause()  # memory and files are kept; compute billing stops

again = Sandbox.connect(sbx.id)
again.wake(timeout_seconds=1200)
print(again.exec("cat /workspace/state.txt").stdout)  # state
again.stop()
```

```bash no-run
runtime sandbox pause "${id}"
runtime sandbox wake "${id}"
```

`pause()` returns once the sandbox's processors have stopped, which is where
compute billing ends. The host then writes the memory to disk; a wake asked for
meanwhile waits for that write. A wake gets a fresh lease of `timeoutSeconds`.

## What a pause keeps

| Kept              | Detail                                               |
| ----------------- | ---------------------------------------------------- |
| Files             | The whole disk, as it was                            |
| Memory            | Variables, caches, a loaded model, an open REPL      |
| Running processes | A dev server or a watcher carries on after the wake  |
| Its name          | `getOrCreate(name)` finds it and wakes it            |
| Where it wakes    | On the same host; a wake never swaps in a fresh boot |

Each pause replaces the previous saved state. A paused sandbox is one machine
you come back to, not a history of copies. For a copy to start from again and
again, take a [snapshot](/docs/javascript#snapshots-and-forks) instead.

## Wake it by using it

A paused sandbox wakes by itself when a request needs it: an `exec`, a file,
process, terminal, desktop or code-interpreter call, or a visit to one of its
shared ports. The call waits while it wakes, usually about half a second, then
runs. A browser at a shared port sees a short "Waking up" page that reloads
itself.

So the cheapest way to keep a sandbox for an agent or a user is to let it pause
when idle and wake when used:

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

const dev = await Sandbox.getOrCreate("dev", { idlePauseSeconds: 900 });
await dev.exec("git -C /workspace/app pull || true"); // wakes it if paused
await dev.update({ idlePauseSeconds: 1800 }); // 0 turns it off
```

```python check
from withruntime import Sandbox

dev = Sandbox.get_or_create("dev", idle_pause_seconds=900)
dev.exec("git -C /workspace/app pull || true")  # wakes it if paused
dev.update(idle_pause_seconds=1800)  # 0 turns it off
```

`idlePauseSeconds` counts from the last exec, file, process, terminal, desktop
or preview request, from 60 to 86,400 seconds. A sandbox created with no
`timeoutSeconds` pauses after 300 seconds if nothing has used it yet.

## Options

| Setting                             | What it does                                                    |
| ----------------------------------- | --------------------------------------------------------------- |
| `sbx.pause()`, `sbx.wake()`         | Pause now; wake now, with an optional new `timeoutSeconds`      |
| `onLeaseEnd: "pause"`               | The default: at the end of its lease the sandbox pauses         |
| `idlePauseSeconds`                  | Pause after that many seconds with no request (60 to 86,400)    |
| `autoWake: false`                   | A paused sandbox stays paused; calls fail with `sandbox_paused` |
| `sbx.extend(seconds)`               | More time before the lease ends, while it runs                  |
| `POST /v1/sandboxes/{id}:retention` | How long a paid sandbox is kept paused, 1 to 365 days           |
| `runtime_sandbox_manage`            | The MCP tool: `"action": "pause"` or `"wake"`                   |

Python takes the same names in snake_case: `on_lease_end`,
`idle_pause_seconds`, `auto_wake`.

## What it costs

| State   | 2 vCPU, 4 GiB sandbox                                | Source                             |
| ------- | ---------------------------------------------------- | ---------------------------------- |
| Busy    | $0.08 an hour                                        | Measured CPU plus reserved memory  |
| Waiting | $0.03125 an hour                                     | Memory plus the 50-millicore floor |
| Paused  | $0.08 per decimal GB of saved state per 30-day month | Paused storage                     |

Paused storage counts the disk and memory-snapshot blocks the sandbox alone
owns. Shared base-image blocks are left out, and so is the size of the disk you
asked for. Billing starts when the processors stop and ends on a
confirmed wake or deletion ([paused storage](/docs/pricing#paused-storage)).

- **Paid sandboxes** are kept 30 days from each pause by default, and 1 to
  365 days if you set it.
- **Trial sandboxes** are kept seven days for free, and a paused one does not
  count toward the trial's eight at once or its 50 hours.
- **Paid accounts** hold 100 sandboxes at once to start, running or paused. A
  paused sandbox holds no CPU or memory against the account's limits.

## Pause when an agent waits

An agent that waits for a person, a webhook or a scheduled job can pause its
sandbox for the wait and keep everything it had in memory. A coding agent
keeps its checkout and its dev server between tasks, as in
[Claude Code in a sandbox](/integrations/claude-code). A pause is a whole-machine
save, so it suits [per-user dev environments](/use-cases/per-user-dev-environments)
that sit idle most of the day. For copies that run side by side, see
[sandbox forks](/glossary/sandbox-fork).

## Start

```bash no-run
npx withruntime sandbox run --trial -- python3 -c 'print(6 * 7)'
```

New accounts get 50 free sandbox hours, no card. The first run prints a link
to approve in your browser. Then use the [JavaScript](/docs/javascript) or
[Python](/docs/python) SDK as above.

Facts on this page were checked on 25 September 2026.