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

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.0
File	Size	Uploaded
superserve-0.9.0.tar.gz	70.5 kB	Sep 14, 2026	Details

Built distribution (wheel)

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

Total release size: 120.6 kB

Release files / superserve-0.9.0.tar.gz

Download URL	superserve-0.9.0.tar.gz
Size	70.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`c617c323c44bdfbece4405a28b8aebfec4342b9889c4896b881164a950a43237`
BLAKE2b-256 checksum How to use checksums	`df81a9045bd7f38674a07fe1fcab7a960af3bdbd323f84ff5e48f73bdeefc5c9`
Upload date	Sep 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","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.0-py3-none-any.whl

Download URL	superserve-0.9.0-py3-none-any.whl
Size	50.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`91a3f8ac708878f0f242d932dff9a3cd47a1b2b065e1f61bc61d4ffe924d307d`
BLAKE2b-256 checksum How to use checksums	`0653f25eb83d0ae2de911fa7984e087b10eeb564ed98e8db210a38914baa82e7`
Upload date	Sep 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","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}`