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

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.1
File	Size	Uploaded
superserve-0.9.1.tar.gz	71.5 kB	Sep 16, 2026	Details

Built distribution (wheel)

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

Total release size: 122.3 kB

Release files / superserve-0.9.1.tar.gz

Download URL	superserve-0.9.1.tar.gz
Size	71.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`567b38c1d973d5df6259831036eaea9d7fbc59c43db4be4984ea239422ee82eb`
BLAKE2b-256 checksum How to use checksums	`6f4d1240a597d5da05da49f79164f72f924e7f646ee40975f916937127a6acb4`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","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.1-py3-none-any.whl

Download URL	superserve-0.9.1-py3-none-any.whl
Size	50.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4a1edc663a81233c95b1cdb1b41e9b5106ee4d054f13d5a83a44f99009808e20`
BLAKE2b-256 checksum How to use checksums	`0e3bd5fcdcece26f81ea84dac3f4b94983bbcfd9e51ad9d938269938f71dde66`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","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}`