Sandboxes

Quickstart

This guide takes you from zero to a sandbox running real code in about five minutes. By the end you'll have run a command, written and read files, streamed output from a long-running process, and paused / resumed a session.

Private beta
Sandboxes are currently in private beta. Mint your token only once an admin has approved your waitlist signup - request access here.

1. Install the SDK

Pick the language your agent runs in. The Python and JS SDKs ship the same surface; field names are snake_case in Python and camelCase in JS.

terminal
pip install orkestr

2. Mint an API token

Sign in to the orkestr console, open Settings, and create a new API token scoped to sandboxes:read and sandboxes:write. Sandbox-scoped tokens cannot reach the rest of the platform - use them in agent runtimes where credentials may end up in stack traces or LLM contexts.

Export the token:

terminal
export ORKESTR_API_KEY="ork_..."

3. Run your first sandbox

The with / withTemp pattern auto-terminates the sandbox on exit, which keeps your bill bounded if the agent loop crashes before it gets to call terminate explicitly.

agent
from orkestr import Sandbox

with Sandbox.create(template="python-3.12") as sbx:
    sbx.files.write("/workspace/main.py", "print(sum(range(1_000_000)))")
    result = sbx.exec("python /workspace/main.py")
    print(result.stdout)        # 499999500000
    print(result.duration_ms)   # ~120

4. Stream long-running output

For commands that take longer than a few seconds, use streaming so the SDK doesn't hold all the bytes in memory and you can react to output as it arrives.

for chunk in sbx.exec_stream("python long_task.py"):
    if chunk.stream == "stdout":
        print(chunk.data, end="", flush=True)
    if chunk.is_final:
        print(f"exit={chunk.exit_code} in {chunk.duration_ms}ms")

5. Work with files

Every sandbox has a writable /workspace directory. Reads and writes go through the SDK as base64 over HTTPS; the SDK handles encoding so you can pass plain strings or bytes.

# Write
sbx.files.write("/workspace/data.json", '{"x": 1}')
sbx.files.write_bytes("/workspace/blob.bin", b"\x00\x01\x02")

# Read
content = sbx.files.read("/workspace/out.txt")
raw = sbx.files.read_bytes("/workspace/blob.bin")

# List
for entry in sbx.files.list("/workspace"):
    print(entry.name, entry.is_dir, entry.size)

6. Pause and resume across requests

Long-lived agent sessions can pause a sandbox between turns to stop the compute meter and resume from the same state minutes or hours later. pause() returns the sandbox id; persist it wherever your agent keeps state and pass it back to Sandbox.resume().

sbx = Sandbox.create(template="node-22", network="restricted")
sandbox_id = sbx.pause()
# Persist sandbox_id somewhere (Redis, DB, agent state).

# Later, anywhere:
sbx = Sandbox.resume(sandbox_id)
result = sbx.exec("node server.js --status")
Snapshot retention
Snapshot retention is plan-capped (free: 1, pro: 3, team: 10). Calling pause() over the cap raises SnapshotCapReached; terminate or resume an older snapshot first.

Next steps