Metadata-Version: 2.4
Name: superserve
Version: 0.5.0
Summary: Python SDK for the Superserve sandbox API
Project-URL: Homepage, https://superserve.ai
Project-URL: Repository, https://github.com/superserve-ai/superserve
Project-URL: Issues, https://github.com/superserve-ai/superserve/issues
License-Expression: Apache-2.0
Keywords: firecracker,microvm,sandbox,sdk,superserve
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Description-Content-Type: text/markdown

# Superserve Python SDK

Python SDK for the [Superserve](https://superserve.ai) sandbox API — spin up isolated sandboxes, run commands in them, and tear them down from code.

## Install

```bash
pip install superserve
# or
uv add superserve
# or
poetry add superserve
```

Requires Python 3.9+.

## Quick start

```python
import os
from superserve import Superserve

client = Superserve(api_key=os.environ["SUPERSERVE_API_KEY"])

sandbox = client.sandboxes.create_sandbox(name="hello-world")

try:
    result = client.exec.command(
        sandbox_id=sandbox.id,
        body={"command": "echo 'Hello from Superserve!'"},
    )
    print(result.stdout)
finally:
    client.sandboxes.delete_sandbox(sandbox.id)
```

Get an API key from the [Superserve console](https://console.superserve.ai).

## Resource clients

The `Superserve` client exposes four resource groups:

- **`client.sandboxes`** — create, list, get, patch, pause, resume, and delete sandboxes
- **`client.exec`** — run commands inside a sandbox (`command`) or stream output (`command_stream`)
- **`client.files`** — upload and download files to and from a sandbox
- **`client.system`** — health check

## Configuration

```python
from superserve import Superserve
from superserve.environment import SuperserveEnvironment

client = Superserve(
    api_key="ss_live_...",                            # required
    environment=SuperserveEnvironment.PRODUCTION,     # optional
    base_url="http://localhost:8080",                 # optional, overrides environment
    timeout=60.0,                                     # optional, default 60
    httpx_client=None,                                # optional, inject a custom httpx.Client
)
```

## Async client

`AsyncSuperserve` mirrors every method on `Superserve` with `async`/`await`:

```python
import asyncio
import os
from superserve import AsyncSuperserve

async def main():
    client = AsyncSuperserve(api_key=os.environ["SUPERSERVE_API_KEY"])

    sandbox = await client.sandboxes.create_sandbox(name="async-example")
    try:
        result = await client.exec.command(
            sandbox_id=sandbox.id,
            body={"command": "uname -a"},
        )
        print(result.stdout)
    finally:
        await client.sandboxes.delete_sandbox(sandbox.id)

asyncio.run(main())
```

## Error handling

```python
from superserve import Superserve
from superserve.errors import BadRequestError, NotFoundError

client = Superserve(api_key=os.environ["SUPERSERVE_API_KEY"])

try:
    client.sandboxes.get_sandbox("sbx_missing")
except NotFoundError:
    print("sandbox does not exist")
except BadRequestError as err:
    print("invalid request:", err.body)
```

Available error classes: `BadRequestError`, `UnauthorizedError`, `NotFoundError`, `ConflictError`, `InternalServerError`.

## Documentation

Full docs: [docs.superserve.ai](https://docs.superserve.ai)

## License

Apache-2.0
