Skip to main content

PandaStack Python SDK

Python SDK for PandaStack, open-source Firecracker microVM sandboxes for AI agents and code execution.

Install

pip install pandastack

Auth

Create a token in the PandaStack dashboard, then export it:

export PANDASTACK_API_KEY=pds_...
# Optional for self-hosted/dev:
export PANDASTACK_API=http://localhost:8080

Client() also reads ~/.config/pandastack/config.json when environment variables are unset.

Quickstart

from pandastack import Sandbox

with Sandbox.create(template="code-interpreter") as sb:
    result = sb.run_code("print(2 + 2)")
    print(result.stdout.strip())

Explicit client

from pandastack import Client

client = Client(api_key="pds_xxx", api_url="https://api.pandastack.ai")
sb = client.sandboxes.create(template="code-interpreter")
try:
    print(sb.exec("ls -la").stdout)
finally:
    sb.kill()

Capacity retries

When the platform is briefly out of room, the SDK retries sandboxes.create, Sandbox.create, fork and fork_tree for you. It resends a create only after a refusal that the platform sends before any sandbox exists:

Response Retried?
503 no compute capacity available with Retry-After: 5 (the scheduler found no host) Yes
503 sandbox host unavailable with Retry-After: 15 (a fork whose parent's host is down) Yes
507 insufficient host memory/storage for sandbox (the host's admission gate) Yes
429 with Retry-After (the per-workspace rate limiter, Retry-After: 1) Yes
429 without Retry-After (quotas such as max sandboxes reached) No, raised at once
503 without Retry-After or without a JSON error body, such as the load balancer's own 503 when an API edge drops a connection No
500, 502, any other status, a dropped connection, a timeout No

The responses that are not retried can follow a create that went through, so resending them could make a second sandbox.

Schedule. Each wait is the server's Retry-After plus a random jitter whose cap doubles per retry: 1 s, 2 s, 4 s, 8 s, then 15 s. A scheduler refusal (Retry-After: 5) therefore waits 5–6 s, then 5–7 s, 5–9 s, 5–13 s, then 5–20 s, which is about 5 to 9 retries (usually 6 to 8) in the default 60-second budget. A 507 carries no Retry-After, so it waits 0.5 s plus the jitter (0.5–1.5 s, then 0.5–2.5 s, … up to 15.5 s). A Retry-After that does not fit in the budget left ends the retry at once. A wait that would overrun the budget is shortened to end at it, but never below Retry-After or 1 s. When the budget runs out, the last refusal is raised unchanged (same exception type and message: ServerError for 503/507).

import logging
from pandastack import Client

logging.basicConfig()
logging.getLogger("pandastack").setLevel(logging.INFO)  # one log line per retry

client = Client(
    max_create_retry_seconds=120,  # 0 disables; env: PANDASTACK_MAX_CREATE_RETRY_SECONDS
    on_create_retry=lambda e: print(f"retry {e.attempt}: HTTP {e.status_code} {e.error}, waiting {e.delay_seconds:.1f}s"),
)

If on_create_retry raises, the exception propagates and retrying stops. It is not called for a refusal that arrives after you set cancel.

Blocking and cancellation. The budget limits when the last attempt can start. An attempt already running keeps its full timeout, so a create can block for up to about max_create_retry_seconds + timeout. If you run creates under your own deadline, set the budget below it. If you may abandon the call (a futures timeout, asyncio.wait_for around run_in_executor), also pass a cancel event and set it when you give up. No attempt is sent after that, a pending wait ends at once, and the call raises CreateCancelled:

import threading
from concurrent.futures import ThreadPoolExecutor, TimeoutError

pool = ThreadPoolExecutor()
cancel = threading.Event()
future = pool.submit(client.sandboxes.create, template="agent", cancel=cancel)
try:
    sb = future.result(timeout=20)
except TimeoutError:
    cancel.set()  # the worker stops retrying now instead of 60 s later

cancel takes a threading.Event or a multiprocessing.Event (anything with is_set() and a blocking wait(timeout)). An asyncio.Event raises TypeError before anything is sent: the create blocks its thread, so run it with asyncio.to_thread or run_in_executor and pass a threading.Event.

An attempt already in flight cannot be interrupted. If it succeeds after you set cancel, the call still returns that sandbox, so delete it from the future if you no longer want it.

What this does not cover. The retry relies on how the platform answers today, not on an idempotency key. If a create's response is lost (a timeout, a dropped connection, a 502), the SDK raises and the sandbox may still exist. Tag creates with metadata you can recognise, then list and reconcile before creating again.

Filesystem

sb.filesystem.write("/home/panda/hello.txt", "hello")
print(sb.filesystem.read("/home/panda/hello.txt"))
sb.filesystem.upload("local.csv", "/home/panda/local.csv")
sb.filesystem.download("/home/panda/out.png", "out.png")

Commands and logs

result = sb.commands.run("python3 --version", timeout=10)
for line in sb.logs(stream="both", follow=False):
    print(line)

Lifecycle

sb.set_ttl(600)
sb.set_persistent(True)
print(sb.lifecycle())
sb.pause()
sb.resume()
snapshot_id = sb.snapshot()

Templates

from pandastack import templates

print(templates.list())
build = templates.build("my-template", rootfs_tar="rootfs.tar", size_mb=2048)
print(build.status)
templates.delete("my-template")

Tokens

from pandastack import tokens

new_token = tokens.create("ci")
print(new_token.token)
for token in tokens.list():
    print(token.prefix, token.name)
tokens.revoke(new_token.prefix)

The old pandastack import remains as a deprecated compatibility alias. Use pandastack for new code.

Metadata

Release files for pandastack 0.10.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 pandastack 0.10.0
File Size Uploaded Provenance Actions
pandastack-0.10.0.tar.gz 87.5 kB Without provenance Details for pandastack-0.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pandastack 0.10.0
File Interpreter ABI Platform Actions
pandastack-0.10.0-py3-none-any.whl Python 3 none any Details for pandastack-0.10.0-py3-none-any.whl

Total release size: 151.3 kB

Release files / pandastack-0.10.0.tar.gz

Download URL pandastack-0.10.0.tar.gz
Size 87.5 kB
Tags Source
SHA-256 checksum
How to use checksums
a20841b6085b61f4e431cd5993602da9fbfc46f93ae3ac08afc4ddac56edc087
BLAKE2b-256 checksum
How to use checksums
26e17ee793365ee18e8ec76f2e1134713e51bb3e7fb26d4fe9474b01238fe307
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / pandastack-0.10.0-py3-none-any.whl

Download URL pandastack-0.10.0-py3-none-any.whl
Size 63.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
46e15a7e258b5ce72f2382e7e3dbf00560e52c486bb6fad0e2b54bca6cabf6c0
BLAKE2b-256 checksum
How to use checksums
1cf5cf896fb60c739ecad1ea375e1cedca665e153a92349431ceaad024e061de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for pandastack 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page