Run an AI agent's code¶

The reason Sistemo exists: an LLM writes code, and you need to run it without trusting it. A shared-kernel container is a scary boundary for code a model just generated — a real microVM with its own kernel is the right one.

The pattern is always: create → run → read output → destroy.

import shlex
from sistemo import Sandbox

def run_untrusted(code: str) -> str:
    with Sandbox(stack="python") as sb:
        # Write a file — LLM output is multiline. python3 -c is a trap.
        w = sb.run(f"printf %s {shlex.quote(code)} > /tmp/run.py")
        if not w.ok:
            return w.stderr or f"write failed ({w.exit_code})"
        r = sb.run("python3 /tmp/run.py", timeout=30)
        return r.stdout if r.ok else (r.stderr or f"exit {r.exit_code}")

print(run_untrusted("print(sum(range(100)))"))   # "4950"

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

async function runUntrusted(code: string): Promise<string> {
  const sb = await Sandbox.create({ stack: "node" });
  try {
    const r = await sb.run(`node -e ${JSON.stringify(code)}`);
    return r.exitCode === 0 ? r.stdout : `Error:\n${r.stderr}`;
  } finally {
    await sb.close();            // always destroy
  }
}

Why this is safe¶

• Own kernel. A guest→host escape has to break out of a VM, not just a container namespace.
• Throwaway. Each run gets a fresh VM; destroy it and the blast radius is gone.
• No host access. The code runs inside the VM's network namespace; it can't see your other sandboxes, the host, or cloud metadata.

Handle failures and timeouts¶

Untrusted code crashes, loops, or floods output. Plan for it:

from sistemo import Sandbox

with Sandbox(stack="python") as sb:
    r = sb.run("python3 -c 'while True: pass'", timeout=10)   # capped
    if not r.ok:
        print("non-zero exit:", r.exit_code, r.stderr[:500])

run() waits until the command finishes (default 120 s, max 24 h). For a build or a test suite, raise timeout — long-running.

Reuse one sandbox for a multi-step agent¶

If your agent runs several steps, keep one sandbox alive so state (files, installed packages) persists between calls:

from sistemo import Sandbox

with Sandbox(stack="python") as sb:
    sb.run("pip install requests", timeout=180)
    sb.run("cat > /tmp/data.py <<'EOF'\nimport requests\nprint(requests.__version__)\nEOF")
    print(sb.run("python3 /tmp/data.py").stdout)

Next: Connect an LLM so the agent generates the code itself.