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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

superserve-0.8.1.tar.gz (58.5 kB view details)

Uploaded Jul 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

superserve-0.8.1-py3-none-any.whl (44.5 kB view details)

Uploaded Jul 21, 2026 Python 3

File details

Details for the file superserve-0.8.1.tar.gz.

File metadata

Download URL: superserve-0.8.1.tar.gz
Upload date: Jul 21, 2026
Size: 58.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.11.30 {"installer":{"name":"uv","version":"0.11.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for superserve-0.8.1.tar.gz
Algorithm	Hash digest
SHA256	`b1be02a96467b3146d3abd1508deba3ff769b6b226c8b9028964b1033aa6f7dd`
MD5	`2f4527bf344dc7af57ebf4fc68c93f9f`
BLAKE2b-256	`b7f2cd502fd5b625ba59dc83f79442c44627988b302acce8b43a0ff7696b299d`

See more details on using hashes here.

File details

Details for the file superserve-0.8.1-py3-none-any.whl.

File metadata

Download URL: superserve-0.8.1-py3-none-any.whl
Upload date: Jul 21, 2026
Size: 44.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.11.30 {"installer":{"name":"uv","version":"0.11.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for superserve-0.8.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`c5e2a09d9d0df105fb895f5813ab07dae1d4cf731d7f7f4bda095e9349276c8a`
MD5	`2862704fa629edbde62a8011fd9b9881`
BLAKE2b-256	`5a88e2032f6bdc805cbd76ab00b037ca3584c751bf5178f7c379a366f90d85d2`