Python SDK reference

pip install orkestr

import os
from orkestr import Sandbox

# 1) Implicit: SDK reads ORKESTR_API_KEY from env
sbx = Sandbox.create(template="python-3.12")

# 2) Explicit: per-call api_key
sbx = Sandbox.create(template="python-3.12", api_key="ork_...")

# 3) Reusable client (good for long-running agents)
from orkestr import OrkestrClient
client = OrkestrClient(api_key="ork_...", base_url="https://api.orkestr.eu")
sbx = Sandbox.create(template="python-3.12", client=client)

from orkestr import Sandbox

sbx = Sandbox.create(
    template="python-3.12",
    size="small",
    network="off",
    timeout_seconds=600,
    env={"OPENAI_API_KEY": "sk-..."},
    metadata={"agent_run": "r_42"},
    region="fsn1",
)
print(sbx.id, sbx.status)

# Reattach from another process
sbx = Sandbox.get("sbx_01HXYZ...")

# List your sandboxes
for sbx in Sandbox.list(status="running"):
    print(sbx.id, sbx.template, sbx.created_at)

limits = Sandbox.limits()
limits.plan                        # "free"
limits.allowed_sizes               # ["small"]
"medium" in limits.allowed_sizes   # False
limits.max_concurrent_memory_mb    # 1536 (concurrent RAM budget, MB)
limits.max_concurrent              # 3    (budget as a count of small boxes)
limits.usage_gb_hours_used         # 2.5  (memory used of the trial)
limits.usage_gb_hours_included     # 10.0 (one-time trial allowance)
limits.usage_cpu_hours_used        # 0.42 (CPU used of the trial)
limits.usage_cpu_hours_included    # 2.0  (one-time trial allowance)
limits.usage_resets_at             # None - the trial does not reset
for s in limits.sizes:             # full menu, each with .allowed
    print(s.size, s.cpu, s.memory_mb, s.allowed)

result = sbx.exec("python /workspace/main.py", timeout_seconds=60)
result.stdout       # str
result.stderr       # str
result.exit_code    # int
result.duration_ms  # int

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

# Text I/O
sbx.files.write("/workspace/script.py", "print('hello')")
content = sbx.files.read("/workspace/output.txt")

# Binary I/O
sbx.files.write_bytes("/workspace/blob.bin", b"\x00\x01\x02")
raw = sbx.files.read_bytes("/workspace/blob.bin")

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

# Remove
sbx.files.delete("/workspace/output.txt")

from orkestr import Sandbox, Volume

# Attach a volume by name - created on first use (default 10 GB).
# Anything under /persist survives terminate.
sbx = Sandbox.create(template="python-3.12", volume="my-cache")
sbx.run("echo trained-weights-v1 > /persist/model.txt")
sbx.terminate()

# A brand-new sandbox re-attaches the same volume and sees the data:
sbx = Sandbox.create(template="python-3.12", volume="my-cache")
print(sbx.run("cat /persist/model.txt").stdout)   # trained-weights-v1

# Manage volumes explicitly (custom size, a region pin, listing, cleanup):
vol = Volume.create("datasets", size_gb=50, region="rbx")
for v in Volume.list():
    print(v.name, v.size_mb, v.status, v.region)
Volume.move(vol.id, "hel1")   # re-home a detached volume to another region
Volume.delete(vol.id)   # rejected while attached to a running sandbox

m = sbx.metrics()
m.sandbox_status        # "running" (usage is null when paused / terminated)
m.cpu.cores             # 1.0
m.cpu.usage_percent     # 94.0  (% of allocated cores; 1-core pegged = 100)
m.cpu.usage_cores       # 0.94  (cores in use)
m.memory.usage_bytes    # 188743680  (working set, excludes reclaimable cache)
m.memory.usage_percent  # 35.2  (% of m.memory.limit_bytes)
m.lifetime.cpu_seconds  # 12.84 (on-CPU seconds since the sandbox started)
for s in m.samples:     # rolling ~60s window, oldest first
    print(s.t, s.cpu_percent, s.mem_bytes)

sbx = Sandbox.create(template="node-22", network="open")

# Start a server on a port inside the sandbox (in the background):
sbx.exec("nohup python3 -m http.server 3000 >/tmp/srv.log 2>&1 &")

host = sbx.get_host(3000)     # "3000-01hxyz....sbx.orkestr.run"
url = f"https://{host}"       # open in a browser or embed it in your app

# Pause: returns the sandbox id, stops compute meter
sandbox_id = sbx.pause()

# ... later ...
sbx = Sandbox.resume(sandbox_id)

with Sandbox.create(template="python-3.12") as sbx:
    result = sbx.exec("python -c 'print(2+2)'")
    print(result.stdout)
# sbx.terminate() is called automatically on exit (including on exceptions)

from orkestr import (
    OrkestrError,
    AuthError,
    SandboxNotFound,
    ExecTimeout,
    SnapshotCapReached,
)

try:
    sbx = Sandbox.create(template="python-3.12")
    result = sbx.exec("sleep 9999", timeout_seconds=5)
except ExecTimeout:
    print("Command exceeded timeout - the sandbox is still running.")
except AuthError as e:
    print(f"Auth failed ({e.status_code}): {e.detail}")
except OrkestrError as e:
    print(f"Something else broke: {e}, request_id={e.request_id}")