Examples (Python)¶

Every block below is copy-pasteable. Catalog guests have python3, not python.

Set this once:

python3 -m venv .venv && source .venv/bin/activate
pip install sistemo
export SISTEMO_API_KEY=sk_live_xxxxxxxxxxxxxxxx

Hello from a microVM¶

from sistemo import Sandbox

with Sandbox() as sb:
    r = sb.run("uname -a")
    print(r.stdout)
    print(r.exit_code)   # 0

One-liner (same thing):

python3 -c "from sistemo import Sandbox; sb=Sandbox(); print(sb.run('uname -a').stdout); sb.close()"

Run Python inside the guest¶

from sistemo import Sandbox

with Sandbox() as sb:
    r = sb.run("python3 -c 'print(2 + 2)'")
    print(r.stdout)      # 4
    if not r.ok:
        print(r.stderr)

Install a package, then import it¶

pip works on base and python. The install lives for the life of this sandbox only.

from sistemo import Sandbox

with Sandbox(stack="python") as sb:
    sb.run("pip install requests", timeout=180)
    r = sb.run("python3 -c 'import requests; print(requests.__version__)'")
    print(r.stdout)

Write a file, then execute it¶

from sistemo import Sandbox

script = "print('from a file')"
with Sandbox() as sb:
    sb.run(f"cat > /tmp/run.py <<'EOF'\n{script}\nEOF")
    print(sb.run("python3 /tmp/run.py").stdout)

Run AI-generated code¶

An LLM writes the string; you do not trust it. shlex.quote is required so the code cannot break out of python3 -c.

import shlex
from sistemo import Sandbox

code = "print(sum(range(100)))"   # stand-in for ask_the_llm(...)

with Sandbox(stack="python") as sb:
    r = sb.run(f"python3 -c {shlex.quote(code)}")
    if r.ok:
        print(r.stdout)           # 4950
    else:
        print("failed:", r.exit_code, r.stderr)

Timeouts and non-zero exits¶

from sistemo import Sandbox

with Sandbox() as sb:
    r = sb.run("python3 -c 'while True: pass'", timeout=5)
    print(r.ok, r.exit_code, r.stderr[:200])

timeout is enforced in the machine (exit 124). Ceiling 24 hours:

r = sb.run("pytest -q", timeout=3600)

See Long-running work.

Catch quota vs auth¶

Both are HTTP 403. Catch QuotaExceededError first — retrying a quota refusal works once you free the resource; retrying an auth failure never does.

from sistemo import Sandbox, AuthError, QuotaExceededError, APIError

try:
    with Sandbox() as sb:
        print(sb.run("uname -a").stdout)
except QuotaExceededError as e:
    print("quota:", e.detail)      # stop or destroy a machine, then retry
except AuthError:
    print("key missing, revoked, or read-only")
except APIError as e:
    print(e.status, e.detail, e.code)

Keep the disk after destroy¶

from sistemo import Sandbox

sb = Sandbox()
try:
    sb.run("echo important > /root/state.txt")
finally:
    sb.close(preserve_storage=True)   # disk kept as a volume

Point at another API¶

from sistemo import Sandbox

with Sandbox(
    base_url="https://your-own-host:8000",
    api_key="sk_live_your_key",
) as sb:
    print(sb.run("uname -a").stdout)

Or set SISTEMO_BASE_URL once.

Next: Sandbox API · Error handling · Connect an LLM