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

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

Volumes can be created up front and mounted into sandboxes at launch, and their contents browsed and read straight from the volume handle:

volume=porter.volumes.create(name="my-data")
sb=porter.sandboxes.create(
image="python:3.11-alpine",
volume_mounts={"/mnt/my-data": volume.id},
)
forfileinvolume.listdir("/checkpoints"):
print(file.path, file.size_bytes)
config=volume.read_text("/checkpoints/config.json")
withopen("model.safetensors", "wb") asout:
forchunkinvolume.stream("/checkpoints/model.safetensors"):
out.write(chunk)

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:

importasynciofromporter_sandboximportAsyncPorterasyncdefmain():
asyncwithAsyncPorter() asporter:
sb=awaitporter.sandboxes.create(image="python:3.11-alpine", command=["python", "-c", "print('hi')"])
print(awaitsb.logs())
awaitsb.terminate()
asyncio.run(main())

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

asyncwithAsyncPorter() asporter:
results=awaitasyncio.gather(*[
porter.sandboxes.create(image="python:3.11", command=cmd) forcmdincommands
])

Layout

Everything under porter_sandbox/ is generated from the Porter Sandbox OpenAPI spec. Do not edit it by hand - changes there are overwritten on the next release.

• porter_sandbox/sandbox.py, porter_sandbox/volume.py - sync and async Sandbox and Volume handles
• porter_sandbox/porter.py and resource namespace modules like porter_sandbox/sandboxes.py - public client and namespaces
• porter_sandbox/_client.py, _models.py, enums.py, _errors.py, resources/ - low-level client, models, and errors
• porter_sandbox/_base_client.py, _async_base_client.py, _config.py, _retries.py - sync and async HTTP transports, env-var resolution, retry/backoff

Development

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