SB-Box Python SDK

Cloud sandboxes for AI agents — create an isolated Linux machine in about a second, run commands and code in it, read and write files, freeze it when idle and resume it later with memory intact.

pip install genspark-sbbox
# until the first PyPI release:
pip install "git+https://github.com/genspark-ai/sb-box-sdk.git#subdirectory=python"

Python 3.9+. The only dependency is httpx. Sync (sbbox.Client) and async (sbbox.AsyncClient) clients expose the same surface.

Quickstart

import sbbox

client = sbbox.Client()  # reads SBBOX_API_KEY (or GSK_API_KEY)

with client.sandboxes.create() as sb:  # public "base" image; killed on exit
    print(sb.exec("python3 --version").stdout)

    sb.files.write("/home/user/hello.py", "print('hi from the sandbox')")
    print(sb.exec(["python3", "/home/user/hello.py"]).stdout)

    result = sb.run_code("import math; math.pi * 2")  # stateful interpreter (base image)
    print(result.text)  # "6.283185307179586"

    print(sb.port_url(8000))  # public URL for a service listening on :8000

Keep a machine around between sessions:

sb = client.sandboxes.create("base", timeout=0)  # no deadline; the idle timer still applies
sb.exec("git clone https://github.com/you/project /home/user/project")
sb.freeze()  # memory + disk kept, no compute billed
...
sb = client.sandboxes.get("sbx-…")  # later, anywhere
sb.resume()  # ~1 s, processes still there
sb.exec("cd /home/user/project && make test")
sb.kill()

Get an API key from the Genspark console and keep it in SBBOX_API_KEY. Full guide: https://www.genspark.ai/sb-box/docs.

What you can do

A str command runs through /bin/sh -c; a list is executed as-is. All timeouts are seconds. A non-zero exit code is returned in CommandResult.exit_code, not raised.

Streaming output:

for ev in sb.exec_stream("for i in 1 2 3; do echo $i; sleep 1; done"):
    if ev.kind == "stdout":
        print(ev.data, end="")
    elif ev.kind == "exit":
        print("exit", ev.exit_code)

Async:

async with sbbox.AsyncClient() as client:
    sb = await client.sandboxes.create()
    print((await sb.exec("uname -a")).stdout)
    await sb.kill()

Errors

Every error derives from sbbox.SbBoxError and carries status, code, message, detail (the raw response body), retry_after and request_id.

API keys are redacted from every error message.

Configuration

License

MIT