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()

Preview URLs

Choose the default access for new ports, publish only the ports you intend to expose, and request a signed link for private browser access:

sandbox = Sandbox.create(name="private-preview", preview_access="private")
sandbox.publish_preview_port(3000, access="private")

browser_url = sandbox.get_signed_preview_url(3000, expires_in_seconds=300)
credential = sandbox.get_preview_token(3000)
# Machine clients: {credential.header: credential.token}

Each published port keeps its own public or private mode; preview_access is only the default for newly published ports. Omitting it defaults a new sandbox to strict public. legacy_public is returned only for pre-migration sandboxes. See the preview URL guide.

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())

Calls made on an AsyncSandbox reuse its connection. To reuse connections across other calls too, such as AsyncSandbox.create or AsyncSnapshot.get, make them inside async_connection_pool(). The connections close when the block ends.

from superserve import AsyncSandbox, AsyncSnapshot, async_connection_pool

async with async_connection_pool():
    sandbox = await AsyncSandbox.create(name="async-example")
    snapshots = await AsyncSnapshot.list(sandbox.id)

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.

Metadata

Release files for superserve 0.9.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for superserve 0.9.3
File	Size	Uploaded
superserve-0.9.3.tar.gz	83.4 kB	Oct 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for superserve 0.9.3
File	Interpreter	ABI	Platform	Reset
superserve-0.9.3-py3-none-any.whl 59.4 kB Oct 2, 2026	Python 3	none	any	Details

Total release size: 142.8 kB

Release files / superserve-0.9.3.tar.gz

Download URL	superserve-0.9.3.tar.gz
Size	83.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`1a27c71e766d91741360cf5df7940225d7b1ddff2e43c95a4bfa096d14bf9c15`
BLAKE2b-256 checksum How to use checksums	`7b76b5dee883c46e4b5096d190837e955622a0f6b6ee222065e7f7a93f394d0f`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.22 {"installer":{"name":"uv","version":"0.12.22","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}`

Release files / superserve-0.9.3-py3-none-any.whl

Download URL	superserve-0.9.3-py3-none-any.whl
Size	59.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1805a1c386ba9c10ed834ffb21a55d8ec6631dd9d2c45cb9caf27761718e11ea`
BLAKE2b-256 checksum How to use checksums	`dae91190d5d85419633a2e69d978294191838dd35258df9b312a449f1f58fada`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.22 {"installer":{"name":"uv","version":"0.12.22","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}`