Sandbox as a Service — Python SDK
Official, dependency-free Python client for the Sandbox as a Service REST API: create a disposable cloud VM, run commands in it, move files, expose a port, and destroy it. Built on the standard library, so there is nothing to install alongside it.
Install
pip install sandbox-as-a-service
The client is on the Python Package Index: https://pypi.org/project/sandbox-as-a-service/. It is built on the standard library only, so pip pulls in nothing alongside it.
Alternative / offline: the archive is a standard PEP 517 source distribution built and served by the site itself; pip needs no extra index:
pip install https://sandbox-as-a-service.com/sdk/sandbox-as-a-service-python.tar.gz
To install a pinned build instead, use
https://sandbox-as-a-service.com/sdk/sandbox_as_a_service-0.2.0.tar.gz.
Quickstart
import os
from sandbox_as_a_service import Client
client = Client(api_key=os.environ["AAS_API_KEY"]) # key starts with aas_sk_
sandbox = client.create_sandbox(size="small", timeout_minutes=10)
try:
result = sandbox.exec("python3 -c 'print(6 * 7)'")
print(result.stdout.strip()) # -> 42
print(result.exit_code) # -> 0
finally:
sandbox.destroy()
Both objects are context managers, and the sandbox destroys itself on the way out — a sandbox left running is a sandbox being billed for:
with Client() as client: # reads AAS_API_KEY
with client.create_sandbox(timeout_minutes=5) as sandbox:
sandbox.write_file("job.py", "print(sum(range(10)))\n")
print(sandbox.exec("python3 job.py").stdout.strip()) # -> 45
What is covered
| Area | Methods |
|---|---|
| Lifecycle | create_sandbox, get_sandbox, list_sandboxes, iter_sandboxes, Sandbox.extend, Sandbox.refresh, Sandbox.destroy |
| Commands | Sandbox.exec (blocking or streaming via on_stdout/on_stderr), Sandbox.get_execution |
| Files | Sandbox.write_file, read_file, list_files, delete_file |
| Preview URLs | Sandbox.expose_port, list_ports, close_port |
| Account | get_usage, get_account |
Streaming output
Pass on_stdout or on_stderr to Sandbox.exec and the call streams: the
callback fires per chunk as the sandbox produces output, and the return value
is the same Execution object a blocking call returns:
import sys
result = sandbox.exec(
"for i in 1 2 3; do echo tick $i; sleep 1; done",
on_stdout=lambda chunk: print(chunk, end=""),
on_stderr=lambda chunk: print(chunk, end="", file=sys.stderr),
)
# callbacks fire as output arrives; result is the usual Execution object
Dropping the connection mid-stream — the process exiting, Ctrl-C, an exception
raised inside a callback — closes the stream, which kills the remote command;
the platform records it as status: "cancelled". A failure inside the sandbox
after streaming started surfaces through the same typed exceptions as any API
error. See https://sandbox-as-a-service.com/docs/execution#streaming-output
for the event contract, the heartbeat, and the storage-cap rule (output past
1 MiB per stream keeps arriving live but is not stored; truncated is set).
Errors map onto typed exceptions in sandbox_as_a_service.errors — for example
AuthenticationError (401), PaymentRequiredError (402), NotFoundError (404),
ConflictError (409) and RateLimitError (429). Every API error keeps the
platform's request_id, which is what support needs to trace a request:
from sandbox_as_a_service import RateLimitError
try:
client.create_sandbox()
except RateLimitError as err:
print("retry in", err.retry_after, "seconds", err.request_id)
Notes
create_sandboxblocks until the machine is ready. The default client timeout is 600 seconds, which covers a cold boot with room to spare.exectakes its owntimeout_ms(1 000–600 000); the HTTP timeout is raised to match so a command that hits its limit still returns a result.- Retries of a create are safe when you pass the same
idempotency_key; a key is generated per call when you do not.
API reference: https://sandbox-as-a-service.com/docs/api · SDK docs: https://sandbox-as-a-service.com/docs/sdk
Metadata
Release files for sandbox-as-a-service 0.2.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 |
|---|---|---|---|---|
| sandbox_as_a_service-0.2.0.tar.gz | 18.4 kB | Without provenance | Details for sandbox_as_a_service-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sandbox_as_a_service-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for sandbox_as_a_service-0.2.0-py3-none-any.whl |
Total release size: 31.4 kB
Release files / sandbox_as_a_service-0.2.0.tar.gz
| Download URL | sandbox_as_a_service-0.2.0.tar.gz |
|---|---|
| Size | 18.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
437b4c5119a13c11560da10b72c42df8e5e7441aa4d073590e0d122037661135
|
|
BLAKE2b-256 checksum How to use checksums |
6da6a9dbbede6a7edfd1461908c6ecd4c7035706c4be4018633417b2b656b5d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.12
|
Release files / sandbox_as_a_service-0.2.0-py3-none-any.whl
| Download URL | sandbox_as_a_service-0.2.0-py3-none-any.whl |
|---|---|
| Size | 12.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8183c37e31a0487cfe13a7b0998e21729cdd5217a24a7663635157f1d954a8aa
|
|
BLAKE2b-256 checksum How to use checksums |
7e3323546f3fbf1478857b9fad15a0869ba35fb5cae62b1dab1f0a79dc1f86bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.12
|
Security for sandbox-as-a-service 0.2.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.