How to wake a sandbox on request

Do nothing: a paused sandbox wakes by itself when an exec, file, process or terminal call, or a visit to a shared port, reaches it.

On Runtime automatic wake is on for every sandbox, and the request that wakes it simply waits and then runs. The wait is usually about half a second, the sandbox comes back on the same host with its memory and processes, and the wake is billed from the moment it runs again. Between requests a paused sandbox costs $0.08 per decimal GB of saved state a month and no compute (pricing, checked 25 September 2026).

Use it and it wakes

TypeScriptimport { Sandbox } from "withruntime";const sbx = await Sandbox.create({ timeoutSeconds: 900 });await sbx.exec("echo warm > /workspace/cache.txt");await sbx.pause();// Hours later, from any process. No wake() call is needed:const again = await Sandbox.connect(sbx.id);const hit = await again.exec("cat /workspace/cache.txt"); // waits for the wake, then runsconsole.log(hit.stdout, again.state);

Pythonfrom withruntime import Sandboxsbx = Sandbox.create(timeout_seconds=900)sbx.exec("echo warm > /workspace/cache.txt")sbx.pause()again = Sandbox.connect(sbx.id)hit = again.exec("cat /workspace/cache.txt")  # waits for the wake, then runsprint(hit.stdout)

Terminalruntime sandbox exec "${id}" -- cat /workspace/cache.txt   # wakes a paused sandbox first

A web app that wakes on its first visitor

Share a port, let the sandbox pause, and the next visit wakes it. An API client's request waits up to 30 seconds for the wake; a browser sees a short "Waking up" page that reloads itself.

TypeScriptimport { Sandbox } from "withruntime";const app = await Sandbox.getOrCreate("demo-app", { idlePauseSeconds: 600 });await app.spawn("python3 -m http.server 3000");const preview = await app.previews.create(3000, { visibility: "public" });console.log("share this:", preview.url); // works whether the sandbox runs or sleeps

Pythonfrom withruntime import Sandboxapp = Sandbox.get_or_create("demo-app", idle_pause_seconds=600)app.spawn("python3 -m http.server 3000")preview = app.previews.create(3000, visibility="public")print("share this:", preview["url"])

What wakes a paused sandbox

Request	Wakes it	How the caller sees it
`exec`, `spawn`, a process read or write	Yes	The call waits, usually about half a second, and runs
A file read, write or list	Yes	Same
A terminal, the desktop, the code interpreter	Yes	Same
An API client at a shared port	Yes	The request waits up to 30 seconds
A browser at a shared port	Yes	A "Waking up" page that reloads itself
Reading a file watch	No	Delivery stops with `paused`, and resumes after a wake
Any of these with `autoWake: false`	No	Fails with `sandbox_paused` until you call `wake()`

Each wake is an ordinary wake: a fresh lease of the sandbox's own timeoutSeconds, billed from the moment it runs.

Turn it off

For a sandbox that must stay paused until you decide, switch automatic wake off at create or later:

TypeScriptimport { Sandbox } from "withruntime";const sbx = await Sandbox.create({ autoWake: false });await sbx.update({ autoWake: true }); // and back on

Pythonfrom withruntime import Sandboxsbx = Sandbox.create(auto_wake=False)sbx.update(auto_wake=True)  # and back on

Terminalruntime sandbox create --no-auto-wakeruntime sandbox update "${id}" --auto-wake off

Mistakes to avoid

Calling wake() before every request. It is not needed. A request wakes the sandbox and runs; an explicit wake() is for choosing a new timeoutSeconds or warming it ahead of traffic.
Treating sandbox_paused as a crash. It means autoWake is off. Call wake(), or turn automatic wake back on.
Ignoring a refused wake. A wake that cannot be paid for fails with the refusal, such as insufficient_funds, and leaves the sandbox paused with its data kept. A full host can also refuse one; no compute is charged for the failed attempt.
Expecting a fresh machine. A wake restores the same sandbox on the same host. A wake never swaps in a fresh boot; missing memory images refuse it.

Pause when idle, the other half of this pattern.
Pause and resume a sandbox for doing both by hand.
Per-user dev environments that sleep between visits.
Wake on request in the SDK reference.

Facts on this page were checked on 25 September 2026.