# 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](/docs/pricing#paused-storage), checked 25 September 2026).

## Use it and it wakes

```ts check
import { 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 runs
console.log(hit.stdout, again.state);
```

```python check
from withruntime import Sandbox

sbx = 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 runs
print(hit.stdout)
```

```bash no-run
runtime 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.

```ts check
import { 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
```

```python check
from withruntime import Sandbox

app = 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:

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

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

```python check
from withruntime import Sandbox

sbx = Sandbox.create(auto_wake=False)
sbx.update(auto_wake=True)  # and back on
```

```bash no-run
runtime sandbox create --no-auto-wake
runtime 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.

## Related

- [Pause when idle](/how-to/pause-when-idle), the other half of this pattern.
- [Pause and resume a sandbox](/how-to/pause-and-resume-a-sandbox) for doing
  both by hand.
- [Per-user dev environments](/use-cases/per-user-dev-environments) that sleep
  between visits.
- [Wake on request](/docs/javascript#wake-on-request) in the SDK reference.

Facts on this page were checked on 25 September 2026.