# 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. The request that wakes it waits and
then runs.** The sandbox returns on the same host with its memory and processes. 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 26 October 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 sandboxes exec "${id}" -- cat /workspace/cache.txt   # wakes a paused sandbox first
```

## A web app that wakes on its first visitor

Share a port and let the sandbox pause. 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. The preview is private, so share the link
that carries its token. `visibility: "public"` gives an address with no token,
on a paid sandbox only.

```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);
console.log("share this:", preview.urlWithToken); // for a day, whether it 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)
print("share this:", preview["urlWithToken"])
```

## What wakes a paused sandbox

| Request                                       | Wakes it | How the caller sees it                                 |
| --------------------------------------------- | -------- | ------------------------------------------------------ |
| `exec`, `spawn`, a process read or write      | Yes      | The call waits while it wakes, then 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. The sandbox runs again. If it has a time limit,
it gets a fresh limit of its own, `timeoutSeconds`. Billing starts when it runs.

## Turn it off

For a sandbox that must stay paused until you decide, turn automatic wake off
when you create it, 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 sandboxes create --no-auto-wake
runtime sandboxes update "${id}" --auto-wake off
```

## Mistakes to avoid

- **Calling `wake()` before every request.** It is not needed. A request wakes
  the sandbox and then runs. Call `wake()` only to choose a new
  `timeoutSeconds`, or to warm the sandbox before traffic arrives.
- **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`. The sandbox stays paused with its data
  kept. A full host can also refuse a wake. 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. If memory images are missing, the
  wake is refused.

## 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 26 October 2026.