porter-sandbox

Python SDK for the Porter Sandbox API.

Pre-release. Pilot for Porter's multi-language SDK rollout.

Install

pip install porter-sandbox

Usage

from porter_sandbox import Porter

with Porter() as porter:
    sb = porter.sandboxes.create(
        image="python:3.11-alpine",
        command=["python", "-c", "print('hi')"],
    )
    print(sb.logs())
    sb.terminate()

Inside a sandbox-enabled Porter cluster, the SDK connects to the in-cluster sandbox API at http://sandbox-api.porter-sandbox-system.svc.cluster.local:8080 automatically, with no configuration needed.

From outside the cluster, set a Porter API token (created from Settings > API tokens in the Porter Dashboard) and the cluster where sandboxes are enabled:

export PORTER_SANDBOX_API_KEY=<porter-api-token>
export PORTER_CLUSTER_ID=<cluster-id>

The SDK reads the project from the token and calls the sandbox API through the Porter API at dashboard.porter.run. To target a specific URL instead, set PORTER_SANDBOX_BASE_URL or pass base_url - both take precedence over everything above.

Async

For async code (FastAPI handlers, concurrent sandbox fan-out, etc.) use AsyncPorter — same surface, awaitable methods:

import asyncio
from porter_sandbox import AsyncPorter

async def main():
    async with AsyncPorter() as porter:
        sb = await porter.sandboxes.create(image="python:3.11-alpine", command=["python", "-c", "print('hi')"])
        print(await sb.logs())
        await sb.terminate()

asyncio.run(main())

Async is also the right choice when launching many sandboxes in parallel:

async with AsyncPorter() as porter:
    results = await asyncio.gather(*[
        porter.sandboxes.create(image="python:3.11", command=cmd) for cmd in commands
    ])

Layout

• porter_sandbox/porter.py, resource namespace modules like porter_sandbox/sandboxes.py, porter_sandbox/_client.py, _models.py, enums.py, _errors.py, resources/ — generated from the sandbox-api OpenAPI spec via the sdk-gen workspace. Do not edit by hand.
• porter_sandbox/sandbox.py — hand-written rich sandbox handle used by the generated sandboxes namespace
• porter_sandbox/_base_client.py / _async_base_client.py — hand-written sync and async HTTP transports
• porter_sandbox/_config.py, _retries.py — hand-written runtime (env-var resolution, retry/backoff)

Development

pip install -e ".[dev]"
pytest
ruff check .
mypy

To pull in a fresh generation from the sdk-gen workspace:

./scripts/sync-generated.sh /path/to/workstation/code/sandbox/sdk-gen/out/python