superserve 0.8.0

Python SDK for the Superserve sandbox API

superserve

Python SDK for the Superserve sandbox API — run code in isolated Firecracker MicroVMs.

Installation

pip install superserve
# or
uv add superserve
# or
poetry add superserve

Requires Python ≥ 3.9.

Quick Start

from superserve import Sandbox

sandbox = Sandbox.create(name="my-sandbox")

result = sandbox.commands.run("echo hello")
print(result.stdout)

sandbox.files.write("/app/data.txt", b"content")
text = sandbox.files.read_text("/app/data.txt")

sandbox.kill()

Authentication

Set the SUPERSERVE_API_KEY environment variable:

export SUPERSERVE_API_KEY=ss_live_...

Or pass it explicitly:

sandbox = Sandbox.create(
    name="my-sandbox",
    api_key="ss_live_...",
    base_url="https://api.superserve.ai",  # optional
)

Async usage

import asyncio
from superserve import AsyncSandbox

async def main():
    sandbox = await AsyncSandbox.create(name="async-example")
    try:
        result = await sandbox.commands.run("echo hello")
        print(result.stdout)
    finally:
        await sandbox.kill()

asyncio.run(main())

Streaming command output

result = sandbox.commands.run(
    "pip install numpy",
    on_stdout=lambda data: print(data, end=""),
    on_stderr=lambda data: print(data, end=""),
    timeout_seconds=120,
)

Error handling

from superserve import (
    SandboxError,
    AuthenticationError,     # 401
    ValidationError,         # 400
    NotFoundError,           # 404
    ConflictError,           # 409 — invalid state for operation
    SandboxTimeoutError,     # request timed out (does not shadow builtin TimeoutError)
    ServerError,             # 500
)

try:
    sandbox.pause()
except ConflictError:
    # Sandbox is not in a pausable state
    pass

Full documentation

docs.superserve.ai

Development

# From repo root:
bunx turbo run build --filter=@superserve/python-sdk
bunx turbo run typecheck --filter=@superserve/python-sdk
bunx turbo run lint --filter=@superserve/python-sdk

License

Apache License 2.0.