Sandbox
Run untrusted code in an isolated session with its own files, packages and quotas.
The Sandbox gives each user an isolated session to run code in: a place for an agent to execute Python, install packages and work with files without touching anything else. It's Python only for now.
Install
cd aice_sdks/python/sandbox
pip install -e .Import it as aice_sandbox. The project is still packaged under its older name, sandbox-sdk, and isn't part of the umbrella.
Sessions
The Sandbox doesn't use the project key. You name the organization and user when you create a session, and the session carries them from then on.
from aice_sandbox import SandboxClient
sandbox = SandboxClient("http://localhost:8080")
session = sandbox.session.create(tenant_id="acme-corp", user_id="alice")
try:
result = session.exec(["python3", "-c", "print(6 * 7)"])
print(result.stdout) # "42"
session.write("data.txt", b"some content")
print(session.read("data.txt"))
print(session.list("*.txt"))
finally:
session.destroy()Always destroy a session when you're done; each one holds quota until it's gone.
| Method | Does |
|---|---|
session.create(tenant_id, user_id, manifest=None) | starts a session. The manifest can grant network access, among other things. Not retried, so a timeout can't create two |
session.exec(cmd, timeout_s=None, env=None) | runs a command and returns its output |
session.install(packages) | installs packages. Needs network access in the manifest |
session.write(path, content) / read(path) | puts and gets a file |
session.list(glob="*") | lists files |
session.cancel() | stops what's running |
session.destroy() | ends the session |
sandbox.health() / doctor() | service checks |
AsyncSandboxClient offers the same with await.
Errors
Every error derives from SandboxSDKError, which is also an AiceError:
| Error | When |
|---|---|
QuotaExceededError | 429. .scope says whether the organization or the user hit the limit, and .limit what it is |
SessionNotFoundError | 404 on a session call: it expired or was destroyed |
NetworkNotPermittedError | 403 from install(): the manifest didn't allow network access |
SandboxSDKError | anything else |
Access
The Sandbox doesn't authenticate requests. Anyone who can reach it can create sessions for any organization, and change isolation settings through its admin routes. Only expose it on a private network, reachable from your backend and the Agent Platform.