Sandbox lifecycle

Create

Python

from ai2in import Sandbox

sbx = Sandbox(api_key="ai2in_live_…")   # boots immediately
print(sbx.id)                            # "sbx_…"

JavaScript

import { Sandbox } from "@ai2in/sdk";

const sbx = await Sandbox.create({ apiKey: "ai2in_live_…" });
console.log(sbx.id); // "sbx_…"

Use the Python context manager (with Sandbox(...) as sbx:) to auto-kill on exit.

Lifetime & timeouts

By default a sandbox lives until you kill it (idle ones are auto-reaped after 30 minutes of inactivity). Give it a hard lifetime to control cost:

Python

sbx = Sandbox(api_key="…", timeout=300)   # auto-killed after 5 minutes
sbx.set_timeout(3600)                      # extend: now 1h from *now* (max 24h)
sbx.get_info()["end_at"]                   # when it will die

JavaScript

const sbx = await Sandbox.create({ apiKey: "…", timeoutMs: 300_000 });
await sbx.setTimeout(3_600_000); // extend; capped at 24h
(await sbx.getInfo()).end_at;

Reconnect from anywhere

A sandbox outlives your process — reconnect to it by id (works across cluster nodes; pairs with pause/resume for long-lived agent sessions):

Python

sbx = Sandbox.connect("sbx_…", api_key="…")
sbx.resume()          # if it was paused
sbx.run_code("x")     # kernel state is whatever the sandbox last had

JavaScript

const sbx = await Sandbox.connect("sbx_…", { apiKey: "…" });
await sbx.resume();

Sandbox.list() returns every sandbox on the engine (running + paused).

Pause & resume

Pausing stops the container — it uses no CPU or RAM — while preserving the entire filesystem (not just a mounted volume). Resuming starts it again and re-maps its ports. In-memory process state is lost; everything on disk survives.

This is the feature agent builders reach for: park a long-lived session between turns without paying for idle compute.

Python

sbx.pause()     # -> {"status": "paused"}
# ... minutes or hours later ...
sbx.resume()    # -> {"status": "running"}
sbx.run_code("print(open('/home/sandbox/notes.txt').read())")  # file still there

JavaScript

await sbx.pause();
await sbx.resume();
await sbx.runCode("print('still here')");

Paused sandboxes don't count against your concurrent-running cap, and the idle reaper never touches them — pausing is deliberate.

Memory-preserving pause (roadmap)

Today's pause keeps the filesystem; in-memory process state is lost on resume. Memory-snapshot pause — resuming mid-computation with RAM intact — is proven on AI2IN's gVisor substrate (via native checkpoint/restore) and is coming as an opt-in mode. No bare-metal required.

Kill

Python

sbx.kill()

JavaScript

await sbx.kill();

Destroys the container and its filesystem. To keep the workspace, pause instead.

What's next

• Running code — rich outputs and streaming
• Commands — background processes
• Preview URLs — expose a port