Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Timeout & Hibernation

Sandboxes have a rolling idle timeout that determines when they auto-hibernate to save cost. The timeout is what you'd expect from a "laptop lid" — the sandbox sleeps when nothing is happening and wakes the moment you talk to it again.

Default: persistent (no auto-hibernate)

By default the timeout is 0, which means never auto-hibernate. The sandbox stays running until you explicitly kill or hibernate it.
typescript
import { Sandbox } from "@opencomputer/sdk";

// No `timeout` — sandbox is persistent (stays alive until killed).
const sandbox = await Sandbox.create();
Persistent sandboxes keep accruing compute cost for as long as they're running. If you only need the sandbox to respond to occasional requests, set a timeout so it hibernates between them — see below.

Setting a timeout

Pass timeout in seconds to have the sandbox auto-hibernate after N seconds of idle time. The timer resets on every operation — exec, file access, agent activity — so a busy sandbox never hits the timeout.
typescript
// Auto-hibernate after 5 minutes of inactivity.
const sandbox = await Sandbox.create({ timeout: 300 });

Update on a running sandbox

You can change the timeout at any time:
typescript
await sandbox.setTimeout(600); // 10 minutes
await sandbox.setTimeout(0);   // make it persistent

What happens when the timeout expires

When an idle sandbox hits its timeout, the platform:
  1. Snapshots the VM state (memory + disk) and stops the VM — no compute cost while hibernated.
  2. Marks the sandbox hibernated. Its ID, files, and configuration are preserved.
You don't pay for CPU/memory while a sandbox is hibernated — only for the stored snapshot.

Waking up

Any operation from the SDK automatically wakes a hibernated sandbox. You don't need to call wake() yourself — calling sandbox.exec.run(...), reading a file, or any other operation transparently restores the VM and then performs the requested action.
typescript
// Earlier: sandbox auto-hibernated after 5 minutes of idleness.
// Now, hours later — this call just works. The SDK wakes it first.
const result = await sandbox.exec.run("echo hello");
Wake is typically sub-second thanks to snapshot restore, with a cold-boot fallback if the snapshot isn't available. Once woken, the idle timer restarts with the sandbox's configured timeout.
You can still call sandbox.wake() explicitly if you want to pre-warm a sandbox before routing user traffic to it.

Choosing a timeout

Use caseSuggested timeout
Always-on agent / bot that must respond instantly0 (persistent)
Interactive dev sandbox, keep for the session600–3600 (10 min – 1 hr)
Short-lived batch or test run60–300 (1–5 min)
One-off exec — kill it yourself when done0 + explicit kill()
The tradeoff is latency vs cost: a lower timeout saves money but adds wake latency on the next request after idleness.

See also