The unified sandbox interface
ArenAPI separates portable operations from optional provider capabilities. The core remains predictable while the request can still express richer infrastructure.
Portable operations
| Operation | Route | Guarantee |
|---|---|---|
| Create | POST /api/v1/sandboxes | Returns one ArenAPI identifier |
| Inspect | GET /api/v1/sandboxes/:id | Normalized lifecycle state |
| Destroy | DELETE /api/v1/sandboxes/:id | Idempotent resource release |
| Execute | POST /api/v1/sandboxes/:id/exec | Output, error output, and exit code |
| Files | GET or PUT /api/v1/sandboxes/:id/files/*path | Binary-safe reads and writes |
| Archive | POST /api/v1/sandboxes/:id/archive | Gzip-compressed tar archive |
Normalized sandbox request
{
"provider": "auto",
"image": "python:3.13-slim",
"template": null,
"snapshot_id": null,
"region": "eu-central",
"resources": {"cpu": 2, "memory_mb": 4096},
"environment": {"MODE": "preview"},
"secrets": ["github-token"],
"network": {"outbound": "deny"},
"ports": [3000],
"required_capabilities": ["ports", "network_policy"]
}
Adapters translate supported fields to provider-native concepts. The original request is retained in
spec
for auditing and portable retries.
Routing semantics
- Load enabled provider configurations in ascending priority order.
- Filter candidates against every required capability.
- Try each eligible adapter until creation succeeds.
- Return a clear failure if no configured provider satisfies the request.