> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle and long-running sandboxes

> Timeouts, no-limit sandboxes, pause and resume.

```mermaid
stateDiagram-v2
  [*] --> running: create
  running --> paused: pause, idle, or timeout with on_timeout=pause
  paused --> running: connect / resume
  running --> [*]: delete, or timeout (default)
  paused --> [*]: delete
```

## Timeouts

Every sandbox has a timeout: the number of seconds from now until its timeout action runs. The action is **delete** by default, or **pause** if you ask for it. Each call to `set_timeout` replaces the previous value, counted from that moment.

| Where | Default |
| - | - |
| SDK `Sandbox.create()` | 300 s |
| CLI `create`, `run` | `--timeout 300s` |
| API `POST /v2/sandboxes` | 300 s |

```python timeouts.py
from anona_compute import Sandbox

sbx = Sandbox.create("base", timeout=600)  # 10 minutes
sbx.set_timeout(3600)                      # now one hour from this call
print(sbx.get_info().end_at)
sbx.kill()
```

```typescript timeouts.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base", { timeoutMs: 600_000 }); // 10 minutes
await sbx.setTimeout(3_600_000);                                    // one hour from now
console.log((await sbx.getInfo()).endAt);
await sbx.kill();
```

```bash timeouts.sh
SANDBOX_ID=$(anona-compute create -t base --timeout 10m --json | jq -r .sandbox_id)
anona-compute timeout "$SANDBOX_ID" 1h
anona-compute delete "$SANDBOX_ID"
```

## No time limit

A timeout of `-1` means **no deadline**: the sandbox runs until you pause or delete it. It reports `endAt` as `9999-12-31T23:59:59Z`, because the E2B schema requires a date. The MCP tools report it as an absent `end_at` instead (the key is omitted, not sent as `null` or empty), and `anona-compute info` shows `never (no time limit)`. A sandbox without a deadline that you pause and resume keeps having no deadline.

```python no_limit.py
from anona_compute import Sandbox

sbx = Sandbox.create("base", timeout=-1)
print(sbx.get_info().end_at)  # 9999-12-31 23:59:59+00:00
sbx.kill()
```

```bash no_limit_api.sh
# The REST API takes -1 directly; so do the dashboard and the MCP create_sandbox tool.
curl -sS https://api.compute.anonalabs.com/v2/sandboxes \
  -H "X-API-Key: $ANONA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"templateID": "base", "timeout": -1}' | jq -r .sandboxID > sandbox.id
curl -sS -X DELETE "https://api.compute.anonalabs.com/sandboxes/$(cat sandbox.id)" -H "X-API-Key: $ANONA_API_KEY"
```

No plan has a maximum lifetime. If Anona has set one on your team, `-1` and any longer timeout are refused with `400`, naming the limit. With the `anona-compute` CLI, `timeout ID never` sets no deadline; otherwise it takes a positive duration. To change the deadline of a sandbox that is already running, see [Extend a sandbox](#extend-a-sandbox).

> [!WARNING]
>
> The timeout action (delete, or pause with `autoPause`) runs within about a minute of `endAt`, not at the exact second, and running time is billed up to `endAt`, not up to when the action finished. Do not rely on a sandbox still answering after its deadline.
>
> A sandbox without a deadline is billed for as long as it runs. Let it [pause when idle](#pause-when-idle): paused sandboxes cost only snapshot storage.

## Extend a sandbox

Extending a sandbox means giving a running sandbox a new deadline. **Through the API, SDKs, CLI and MCP, the call replaces the deadline; it does not add to it.** `extend 1h` ends the sandbox one hour from the moment you call it, whatever time it had left, so it can also shorten the lifetime. The same call sets no deadline at all.

**The dashboard's Extend adds to the time left.** On a sandbox with 25 minutes left, **Extend → 10 minutes** makes it end in 35. A sandbox with no deadline has nothing to add to, so there the choice sets a deadline that long from now. Your plan's maximum lifetime applies to the total: an extension that would end the sandbox further out than the maximum allows is refused and says how much would fit, and the sandbox keeps its deadline.

| Where | How |
| - | - |
| Python SDK | `sbx.set_timeout(seconds)` |
| TypeScript SDK | `sbx.setTimeout(ms)` |
| CLI | `anona-compute timeout ID DURATION`, or its alias `anona-compute extend ID DURATION` |
| REST API | `POST /sandboxes/{sandboxID}/timeout` with `{"timeout": seconds}`; answers `204` |
| Dashboard | **Extend** on the sandbox's page (adds to the time left) |
| MCP | the `extend_sandbox` tool, with `timeout_seconds` |

```python extend.py
from anona_compute import Sandbox

sbx = Sandbox.connect("SANDBOX_ID")
sbx.set_timeout(3600)   # ends one hour from now, not one hour after the old deadline
sbx.set_timeout(-1)     # no deadline
```

```typescript extend.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.connect("SANDBOX_ID");
await sbx.setTimeout(3_600_000);  // ends one hour from now
await sbx.setTimeout(-1);         // no deadline
```

```bash extend.sh
anona-compute extend "$SANDBOX_ID" 1h      # also: 600, 10m, 2h
anona-compute extend "$SANDBOX_ID" never   # no deadline; "-- -1" works too
```

```bash extend_api.sh
curl -sS -X POST "https://api.compute.anonalabs.com/sandboxes/$SANDBOX_ID/timeout" \
  -H "X-API-Key: $ANONA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"timeout": 3600}'
```

The CLI takes a number of seconds or a duration such as `10m` or `2h`; the SDKs take seconds (Python) or milliseconds (TypeScript); the API and the MCP tool take seconds. The dashboard offers a list from 5 minutes to 30 days, plus **No limit**.

No plan limits how far ahead the deadline can be. If Anona has set a maximum lifetime on your team, a longer deadline, or `-1`, is refused with `400` naming the limit. The dashboard's **No limit (pauses when idle)** sets no deadline and an [idle pause](#pause-when-idle) together.

## Pause and resume

Pausing snapshots the sandbox's memory and disk and stops the VM. Resuming restores it: running processes, open files and `/dev/shm` carry on where they were. Paused sandboxes are kept until you delete them, except on Free, which deletes one 14 days after it was paused (we email you three days before). They count against your plan's paused-sandbox limit: at the limit a pause you ask for is refused with `403`, and an idle pause or a pause on timeout deletes the sandbox instead, with end reason `paused_limit`. Their snapshot storage is billed per GB-month. See [limits](/docs/concepts/limits.md).

```python pause_resume.py
from anona_compute import Sandbox

sbx = Sandbox.create("base")
sbx.commands.run("echo kept > /dev/shm/marker")
sbx.pause()

sbx = Sandbox.connect(sbx.sandbox_id)  # resumes a paused sandbox
print(sbx.commands.run("cat /dev/shm/marker").stdout)
sbx.kill()
```

```typescript pause_resume.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base");
await sbx.commands.run("echo kept > /dev/shm/marker");
await sbx.pause();

const again = await Sandbox.connect(sbx.sandboxId); // resumes a paused sandbox
console.log((await again.commands.run("cat /dev/shm/marker")).stdout);
await again.kill();
```

```bash pause_resume.sh
SANDBOX_ID=$(anona-compute create -t base --json | jq -r .sandbox_id)
anona-compute pause "$SANDBOX_ID"
anona-compute list --state paused
anona-compute resume "$SANDBOX_ID"
anona-compute delete "$SANDBOX_ID"
```

## Pause on timeout

Ask for pause instead of delete when the timeout runs out. The sandbox then waits, paused, until you resume it:

```python pause_on_timeout.py
from anona_compute import Sandbox

sbx = Sandbox.create("base", timeout=3600, lifecycle={"on_timeout": "pause"})
print(sbx.get_info().state)
sbx.kill()
```

```typescript pause_on_timeout.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base", { timeoutMs: 3_600_000, lifecycle: { onTimeout: "pause" } });
console.log((await sbx.getInfo()).state);
await sbx.kill();
```

```bash pause_on_timeout.sh
SANDBOX_ID=$(anona-compute create -t base --timeout 1h --auto-pause --json | jq -r .sandbox_id)
anona-compute info "$SANDBOX_ID"
anona-compute delete "$SANDBOX_ID"
```

`auto_resume` (resume when a request reaches the sandbox's URL) is accepted with pause-on-timeout, but waking on traffic is **Coming soon**: a request to a paused sandbox's URL gets `409` today. Resume with `connect`.

## Pause when idle

A sandbox can pause itself once nothing has used it for a while. This is not the same as **Pause on timeout** above: there is no deadline at all. The sandbox runs for as long as it is used, and pauses once it is not.

**What counts as use**, restarting the clock:

* a request to any of the sandbox's ports, for as long as it is open, so a long process stream, a WebSocket or an SSE response keeps it awake. The one exception is `envd`'s `GET /health`, which SDKs and monitors poll and which says nothing about use;
* an open terminal, live view, SSH session or byte pipe;
* any process started through `envd` that is still running — a background `commands.run`, a PTY shell, a dev server.

**What does not count**, which is the part that surprises people: CPU the guest burns on work it started by itself, outbound traffic the sandbox makes, and API calls *about* the sandbox such as `get` or `list`. A sandbox running a loop that nobody is watching **will** pause. Processes the template starts for itself, such as `sshd` or a desktop's VNC server, are not seen either — but their clients are, through the first two rules.

```python idle_pause.py
from anona_compute import Sandbox

sbx = Sandbox.create("base", timeout=-1)   # no deadline ...
sbx.idle_pause.set(15)                     # ... but pause after 15 idle minutes
print(sbx.idle_pause.get())                # 15
sbx.idle_pause.off()                       # back to running until something stops it
sbx.kill()
```

```typescript idle_pause.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base", { timeoutMs: -1 });  // no deadline ...
await sbx.idlePause.set(15);                                  // ... but pause after 15 idle minutes
console.log(await sbx.idlePause.get());                       // 15
await sbx.idlePause.off();
await sbx.kill();
```

```bash idle_pause_cli.sh
# At create time, or on a sandbox that is already running.
SANDBOX_ID=$(anona-compute create -t base --timeout never --idle-pause 15m --json | jq -r .sandbox_id)
anona-compute idle-pause "$SANDBOX_ID" 1h
anona-compute idle-pause "$SANDBOX_ID" off
anona-compute resume "$SANDBOX_ID"   # a paused sandbox comes back with its memory and files
```

```bash idle_pause_api.sh
# Or at create time, over the API: autoPause takes {"idleMinutes": n} (0 = off; {} = the team default, else 15).
curl -sS https://api.compute.anonalabs.com/v2/sandboxes -H "X-API-Key: $ANONA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"templateID": "base", "timeout": -1, "autoPause": {"idleMinutes": 30}}' | jq -r .sandboxID > sandbox.id
curl -sS "https://api.compute.anonalabs.com/v1/sandboxes/$(cat sandbox.id)/access" -H "X-API-Key: $ANONA_API_KEY" | jq .idlePauseMinutes
curl -sS -X DELETE "https://api.compute.anonalabs.com/sandboxes/$(cat sandbox.id)" -H "X-API-Key: $ANONA_API_KEY"
```

`idleMinutes` ranges from 1 to 10080 (one week); `0` turns it off, and `{}` takes your team's default, else 15. The object form also turns on pause at the timeout (it includes `autoPause: true`), so a sandbox that has a deadline as well is paused, not deleted, when the deadline comes; the same goes for `anona-compute create --idle-pause` with a duration. Resume a paused sandbox with `Sandbox.connect(id)`, `anona-compute resume`, or the dashboard.

In the dashboard, pick the lifetime **No limit (pauses when idle)** when creating a sandbox and an idle time appears beside it; on a running sandbox the same times are under **Extend**. A paused sandbox costs no compute — only snapshot storage — so idle pausing is the cheapest way to keep a sandbox you will come back to.

The SDK's `lifecycle={"on_timeout": "pause"}` (`autoPause: true` on the wire) is the other feature: it pauses at the **timeout**, and idles only if your organization has a default idle time. A sandbox can have both.

## Delete

Delete a sandbox with `anona-compute delete`, the dashboard, or `kill()` in the SDK: the SDK keeps the E2B method name, so code written for E2B works unchanged. It returns as soon as the gateway has the request (it waits up to 2 s for the engine) and finishes in the background with retries. The sandbox disappears from `list` at once.

## Fork

Fork copies a running sandbox - memory, files and running processes - into new sandboxes. Each copy starts from the exact state the original was in, which is the point: get an agent to an interesting state once, then try ten things from there.

The original is **briefly frozen** while its memory is written (about 0.1 s, longer right after it has touched a lot of memory), then keeps running on its own node with the same ID and the same deadline. The snapshot is taken once however many copies you ask for.

```python fork.py
from anona_compute import Sandbox

sbx = Sandbox.create("base", timeout=300)
sbx.files.write("/root/state.txt", "reached an interesting state")
sbx.commands.run("nohup sh -c 'while true; do date >> /root/ticks; sleep 1; done' >/dev/null 2>&1 &")

# Each entry is a Sandbox or the exception that stopped that one fork.
forks = sbx.fork(count=3, timeout=300)
for f in forks:
    if isinstance(f, Exception):
        print("fork failed:", f)
        continue
    print(f.sandbox_id, f.files.read("/root/state.txt"))   # the parent's file
    print(f.commands.run("wc -l < /root/ticks").stdout)    # the parent's process, still ticking
    f.kill()
sbx.kill()
```

```typescript fork.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base", { timeoutMs: 300_000 });
await sbx.files.write("/root/state.txt", "reached an interesting state");

const forks = await sbx.fork({ count: 3, timeoutMs: 300_000 });
for (const f of forks) {
  if (f instanceof Error) {
    console.log("fork failed:", f.message);
    continue;
  }
  console.log(f.sandboxId, await f.files.read("/root/state.txt"));
  await f.kill();
}
await sbx.kill();
```

```bash fork.sh
SANDBOX_ID=$(anona-compute create -t base --json | jq -r .sandbox_id)
anona-compute exec "$SANDBOX_ID" -- sh -c 'echo "reached an interesting state" > /root/state.txt'
anona-compute fork "$SANDBOX_ID" --count 3 --timeout 5m   # one sandbox ID per line
anona-compute delete "$SANDBOX_ID"
```

Each fork is a new sandbox and behaves like one: it takes a slot of your concurrent-sandbox limit, it is **billed like any other sandbox** for as long as it runs, and it inherits the original's template, metadata, timeout policy and network policy, with the lifetime you pass to `fork`.

A fork of ten on a plan with room for three is not an all-or-nothing failure. The copies that fit are created, and every other entry of the result says why it was not - `429` when your plan's limit is reached, `503` when the platform is at capacity. The SDK gives you those as exceptions in the same list, in request order. A non-`201` from the API means nothing was forked at all: the sandbox was not running (`409`), or there was no room for even one copy (`429`), in which case the original is not frozen either.

> [!NOTE]
>
> Forking needs the `sandboxes:create` scope, and an API key restricted to particular sandboxes cannot fork. In the dashboard, **Fork** on a running sandbox's page asks how many copies and how long they should live, shows what the batch will cost before you commit, and lists the outcome of each copy.

> [!WARNING]
>
> Each fork request keeps a **checkpoint** of the source sandbox, which the copies read from, and the platform cannot delete one yet - deleting the copies does not free it. So forking is capped per team (32 checkpoints by default); past that, `fork` answers `429` and says so. Ask support to raise it, and tell us what you are building with fork: the cap exists only until checkpoints can be reclaimed.

## Snapshots

**Coming soon:** named snapshots you can keep and create from later (`POST /sandboxes/{id}/snapshots`, `GET /snapshots`). Fork takes a snapshot for you and uses it immediately.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.