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

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.2

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.2
File	Size	Uploaded
superserve-0.9.2.tar.gz	78.3 kB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for superserve 0.9.2
File	Interpreter	ABI	Platform	Reset
superserve-0.9.2-py3-none-any.whl 56.8 kB Sep 29, 2026	Python 3	none	any	Details

Total release size: 135.1 kB

Release files / superserve-0.9.2.tar.gz

Download URL	superserve-0.9.2.tar.gz
Size	78.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`548fbc49b4c5537b2a89cdb7ed0c437c0b36ce549bb668e652be597f87644810`
BLAKE2b-256 checksum How to use checksums	`4b54b2022a09118cd321e692af388f0a816dc618afe0c65a12fa6b72f21511a4`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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.2-py3-none-any.whl

Download URL	superserve-0.9.2-py3-none-any.whl
Size	56.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f622f0ed13115c62de4b5b2ed320699292a5afbb9b269686a9fda5ecb9b00a0e`
BLAKE2b-256 checksum How to use checksums	`dddf94a1833c969f311ed5186fdd7b348247d4928b4df1d0b8af1690bf4714bf`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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}`