Skip to content
sistemo.io beta
GitHub Docs Quickstart

Sandbox API (Python)

from sistemo import Sandbox

Sandbox(...)

Creating a Sandbox provisions a real microVM and blocks until it boots.

Sandbox(
    *,
    client=None,            # reuse a Client (advanced)
    api_key=None,           # defaults to SISTEMO_API_KEY
    base_url=None,          # defaults to SISTEMO_BASE_URL or https://api.sistemo.io
    name="",                # optional label
    vcpus=1,
    memory_mb=1024,
    rootfs_size_gb=10,
    stack="base",           # base | python | node | debian13 | ubuntu24.04
    metadata=None,          # dict of arbitrary key/values
)
Argument Default Notes
api_key SISTEMO_API_KEY Must be a full-scope key to create/run
base_url https://api.sistemo.io Override for self-hosted
vcpus 1 Virtual CPUs
memory_mb 1024 RAM in MB
rootfs_size_gb 10 Root disk in GB
stack "base" Base image; see Images
metadata {} Stored with the machine

Attributes: sb.id (machine UUID), sb.state (e.g. "running").

sb.run(script, timeout=30)

Run a shell command/script inside the sandbox.

r = sb.run("ls -la /", timeout=60)

Returns an ExecResult:

Field Type Meaning
exit_code int Process exit code (-1 if unknown)
stdout str Standard output
stderr str Standard error
ok bool True when exit_code == 0

timeout is seconds (default 30, server clamps to 120).

sb.close(preserve_storage=False)

Destroy the sandbox. Pass preserve_storage=True to keep its disk.

sb.close()                        # destroy disk too
sb.close(preserve_storage=True)   # keep the volume

Context manager

with Sandbox() as sb:
    sb.run("...")
# sb.close() called automatically, even on exception

Low-level Client (advanced)

For endpoints the Sandbox helper doesn't cover, use the raw client:

from sistemo import Client

c = Client()                       # reads SISTEMO_API_KEY / SISTEMO_BASE_URL
machines = c.request("GET", "/v1/machines")

Client(api_key=None, base_url=None, timeout=120.0) exposes request(method, path, body=None). See the API reference for paths.