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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.