Overview
Quotas ?
own borrowed from the poolDetails
Activity by user
Nodes
Replicas
Sandboxes
Image builds ?
ImageTeam, ownerProgressStarted · took
Teams ?
Documentation
Access
Set the gateway URL and token:
export SANDBOX_GATEWAY_URL= export SANDBOX_GATEWAY_TOKEN=<token> curl -fsS -H "Authorization: Bearer $SANDBOX_GATEWAY_TOKEN" $SANDBOX_GATEWAY_URL/sandboxes
401 | Missing or invalid token. |
|---|---|
404 | Not found or access denied. Dashboard: all teams. Exec, files, delete and logs: own team or admin. |
| Proxy | Add the gateway host to NO_PROXY. |
Clients
Single-file clients. Download again after a gateway update.
| File | Install | Requires |
|---|---|---|
sandbox_gateway.pyPython SDK |
curl -fsSO /clients/sandbox_gateway.py pip install httpx | Python 3.12+ |
sandbox_gateway_harbor.pyHarbor environment |
curl -fsSO /clients/sandbox_gateway_harbor.py | Python 3.12+, Harbor 0.24+ |
Python SDK
from sandbox_gateway import Gateway
with Gateway().create("python:3.14.8", cpus=1, memory_mb=2048) as sbx: # deleted on exit
sbx.run(["pip", "install", "requests"]) # raises on a non-zero exit
print(sbx.exec("python -V").stdout) # str: sh -c; list: argv
sbx.fs.upload(b"print(1)\n", "/work/a.py")
s = sbx.sessions.start("python -u /work/a.py")
for chunk in s.logs(follow=True):
print(chunk)
Harbor
PYTHONPATH=. harbor run -p <task or dataset> -a <agent> -m <model> \ --env sandbox_gateway_harbor:SandboxGatewayEnvironment
task.toml | Required: cpus, memory_mb. Optional: storage_mb. |
|---|---|
| Image | docker_image, environment/Dockerfile (builds enabled), or environment/docker-compose.yaml (one Pod). Builds are cached by context. environment/ is always required. |
| Results | Local: jobs/<job>/<trial>/. |
| Agent keys | --ae KEY=value sets sandbox env. The cluster must reach the model API. |
Sandbox lifecycle
One sandbox = one Pod. Creation is asynchronous; Kueue admits within quota.
| State | Meaning |
|---|---|
| queued | Waiting for quota, including borrowing. |
| starting | Pulling images or starting containers. |
| ready | Accepts commands. ?wait=60 waits for ready or failed. |
| failed | Check reason and /events, then delete. |
| Resources | Required: cpus, memory_mb. storage_mb: disk request and limit. Team max applies to all containers combined. |
|---|---|
| Lease | Deleted after see Teams idle. Sandbox requests renew the lease; /activity does not. |
| Max lifetime | Deleted at see Teams, even while a command runs. |
| Images | Team image prefixes apply. Gateway-built images are allowed. |
| Network | Egress open. Inbound: cluster only. |
Commands and files
| Endpoint | Use for |
|---|---|
POST /sandboxes/{id}/run | JSON: {"argv", "env"?, "cwd"?, "timeout_sec"?} → exit code, stdout, stderr. Max 32 MiB. |
POST /sandboxes/{id}/exec | Binary: JSON line + stdin → stdout + stderr. Lengths: X-Stdout-Length, X-Stderr-Length. Result: X-Return-Code, X-Timed-Out. Gzip supported. |
/sandboxes/{id}/sessions | Start, stream output, write stdin, kill. |
GET|PUT /sandboxes/{id}/files?path= | File, or directory with tar=1. Upload creates parents. |
Raw argv. For a shell, use ["sh", "-c", "..."]; for a directory, cwd.
H="Authorization: Bearer $SANDBOX_GATEWAY_TOKEN"; U=$SANDBOX_GATEWAY_URL
id=$(curl -fsS -H "$H" $U/sandboxes -d '{"image":"python:3.14.8","cpus":1,"memory_mb":2048,"labels":{"tool":"my-rl"}}' | jq -r .id)
curl -fsS -H "$H" "$U/sandboxes/$id?wait=60"
curl -fsS -H "$H" $U/sandboxes/$id/run -d '{"argv":["python","-V"],"env":{"K":"v"},"cwd":"/tmp"}'
curl -fsS -H "$H" -T a.py "$U/sandboxes/$id/files?path=/work/a.py"
curl -fsS -H "$H" -X DELETE $U/sandboxes/$id
HTTP API
Swagger UI · openapi.json| Method | Path | Description |
|---|
Rules
- Secrets:
env.argvis logged and shown here. - Delete sandboxes when done; the lease deletes abandoned ones.
- Any replica serves any sandbox or build. Builds survive gateway restarts.
- No GPUs.