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), and a paid sandbox stays paused for up to 365 days.
Pause and wake
TypeScriptimport { 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); // stateawait again.stop();Pythonfrom withruntime import Sandboxsbx = Sandbox.create(timeout_seconds=600)sbx.exec("echo state > /workspace/state.txt")sbx.pause() # memory and files are kept; compute billing stopsagain = Sandbox.connect(sbx.id)again.wake(timeout_seconds=1200)print(again.exec("cat /workspace/state.txt").stdout) # stateagain.stop()Terminalruntime 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 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:
TypeScriptimport { Sandbox } from "withruntime";const dev = await Sandbox.getOrCreate("dev", { idlePauseSeconds: 900 });await dev.exec("git -C /workspace/app pull || true"); // wakes it if pausedawait dev.update({ idlePauseSeconds: 1800 }); // 0 turns it offPythonfrom withruntime import Sandboxdev = Sandbox.get_or_create("dev", idle_pause_seconds=900)dev.exec("git -C /workspace/app pull || true") # wakes it if pauseddev.update(idle_pause_seconds=1800) # 0 turns it offidlePauseSeconds 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).
- 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. A pause is a whole-machine save, so it suits per-user dev environments that sit idle most of the day. For copies that run side by side, see sandbox forks.
Start
Terminalnpx 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 or Python SDK as above.
Facts on this page were checked on 25 September 2026.