Skip to main content

ai-sandbox (Python SDK)

Section 8.3 / Build Order 41.

from ai_sandbox import Client

client = Client()  # reads credentials written by `ai-sandbox login`
sandbox = client.launch(template="llama-3-8b")  # gpu/provider/hours auto-defaulted
print(sandbox.jupyter_url)

Install

pip install -e .

Auth

Client() resolves credentials in this order: an explicit api_key= argument, the AI_SANDBOX_API_KEY environment variable, then ~/.ai-sandbox/credentials.json (written by ai-sandbox login — see the cli/ package — or by calling client.device_login() directly). There is never a manual API-key copy/paste step; login is always the browser-based device-authorization flow described in Section 8.2. base_url resolves the same way, via AI_SANDBOX_API_URL or the credentials file, falling back to http://localhost:8000.

Token refresh

Access tokens are deliberately short-lived. device_login() and the CLI's ai-sandbox login both also store a refresh_token alongside the access token. When any request gets a 401, Client transparently exchanges the refresh token for a new access token (POST /auth/refresh) and retries the request exactly once — this happens automatically, with no code required on your end. The backend rotates the refresh token on every use, so the new one is persisted back to ~/.ai-sandbox/credentials.json immediately.

If the retry also 401s, the refresh token itself is gone (revoked by ai-sandbox logout, or expired) and the original NotAuthenticatedError propagates — that's a real "please log in again", not a transient failure to retry around.

This exists because a live launch on 2026-07-27 had its access token expire mid-poll and died with "Not logged in" while the GPU it had provisioned kept billing, with no way to recover the instance id. Long-running calls (launch()'s poll loop in particular) are safe across a token expiry now.

Live progress

client.launch(...) blocks and streams progress via an on_progress callback (defaults to printing [ai-sandbox] <stage> lines) while the request is in flight, and continues polling GET /sandbox/instances/{id} if the server hands the launch off to background provisioning (rare — only when the synchronous wait exceeds its own patience window, controlled by poll_timeout_seconds / poll_interval_seconds). See client.py's module docstring for the full design and its limits.

Errors

Every exception this SDK raises inherits from ai_sandbox.AiSandboxError, so except AiSandboxError is always a safe catch-all. Beyond that, catch the specific type when you need to react differently:

Exception Cause Notes
NotAuthenticatedError No credentials, or refresh also failed Run ai-sandbox login, pass api_key=, or set AI_SANDBOX_API_KEY
QuotaExceededError HTTP 402 — Gate A rejection Projected cost exceeds remaining balance
TemplateNotFoundError HTTP 404 on launch Unknown template_id
MissingExplicitGpuError HTTP 422 custom-docker/benchmarking launches require an explicit gpu=
InvalidLaunchRequestError HTTP 400 Malformed request — e.g. neither/both of template/free_text_request set
ProvisioningFailedError HTTP 503, or a definite RUNTIME_FAILED Every provider in the routing order failed
FreeTextReviewQueuedError Section 7.4 Tier 2 Not an HTTP error (still a 202) — no instance was created; the request is queued for admin review. Carries review_queue_id
ProvisioningTimeoutError Client-side poll budget exhausted after a 202 handoff The instance is real and still provisioning server-side — this is your poll timeout expiring, not a server failure. Carries sandbox_instance_id; keep polling with client.get_instance(...) yourself
DeviceLoginTimeoutError device_login()'s device code expired (10 minute window)
DeviceLoginDeniedError The user explicitly denied the device authorization request
AiSandboxAPIError Catch-all for any other non-2xx response Carries .status_code and .body so nothing is silently swallowed

QuotaExceededError, TemplateNotFoundError, MissingExplicitGpuError, InvalidLaunchRequestError, and ProvisioningFailedError are all AiSandboxAPIError subclasses, so they carry .status_code and .body too. The mapping from HTTP status to exception type lives in client.py's _raise_for_status() — see exceptions.py for the full hierarchy and each type's docstring.

from ai_sandbox import Client, QuotaExceededError, ProvisioningTimeoutError

client = Client()
try:
    sandbox = client.launch(template="llama-3-8b")
except QuotaExceededError as e:
    print(f"Over budget: {e}")
except ProvisioningTimeoutError as e:
    # The instance kept provisioning past our poll budget — it isn't lost.
    sandbox = client.get_instance(e.sandbox_instance_id)

Metadata

Release files for ai-sandbox-platform 0.1.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 ai-sandbox-platform 0.1.0
File Size Uploaded Provenance Actions
ai_sandbox_platform-0.1.0.tar.gz 31.4 kB With provenance Details for ai_sandbox_platform-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-sandbox-platform 0.1.0
File Interpreter ABI Platform Actions
ai_sandbox_platform-0.1.0-py3-none-any.whl Python 3 none any Details for ai_sandbox_platform-0.1.0-py3-none-any.whl

Total release size: 54.2 kB

Release files / ai_sandbox_platform-0.1.0.tar.gz

Download URL ai_sandbox_platform-0.1.0.tar.gz
Size 31.4 kB
Tags Source
SHA-256 checksum
How to use checksums
859ff7371aebb9ded49b5491cee3409690462c83a4132354964e8a68c5c3294f
BLAKE2b-256 checksum
How to use checksums
6c7ceab7978524f21175b7b388b5f0d8dc0e2b70a212303202d562e0d82a1f1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.

Transparency log

Release files / ai_sandbox_platform-0.1.0-py3-none-any.whl

Download URL ai_sandbox_platform-0.1.0-py3-none-any.whl
Size 22.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
afa640f177ce2ce132d3a603fe748c1b3ab8ce981418256ca3e534d3fcb78733
BLAKE2b-256 checksum
How to use checksums
16ac97529a374355a8212d3e40d1c66bbdb2249b8c1f7414c6a016387e8acbf8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.

Transparency log

Security for ai-sandbox-platform 0.1.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ai_sandbox_platform-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

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