Use SDKs for application integrations. Use raw HTTP when debugging wire contracts, building internal tools, or validating gateway behavior.
| Layer | Recommendation |
|---|
| Browser or mobile app | Do not call Sandbox APIs directly. Call your backend. |
| Your backend | Owns SEACLOUD_API_KEY, creates sandboxes, stores sandbox IDs, and exposes product-specific actions. |
| Agent runner | Uses SDK helpers for commands/files and passes only task-specific data into the sandbox. |
| Sandbox runtime | Receives only the env vars, source files, and credentials needed for that workload. |
| Support dashboard | Reads sandbox detail, logs, metrics, usage limits, and observability summary. |
This shape keeps SEACLOUD_API_KEY and envdAccessToken out of browser code and model-visible logs.
| SDK | Install |
|---|
| Node | npm install @seacloudai/sandbox |
| Python | pip install seacloud-sandbox |
| Go | go get github.com/SeaCloudAI/sandbox-go |
export SEACLOUD_BASE_URL="https://sandbox-gateway.cloud.seaart.ai"
export SEACLOUD_API_KEY="YOUR_API_KEY"
| Variable | Required | Purpose |
|---|
SEACLOUD_BASE_URL | yes | Gateway base URL. |
SEACLOUD_API_KEY | yes | API key sent as X-API-Key. |
| Area | Node | Python | Go |
|---|
| Create | Sandbox.create(...) | Sandbox.create(...) | sandbox.Create(...) |
| Connect | Sandbox.connect(...) | Sandbox.connect(...) | sandbox.Connect(...) |
| Files | sandbox.files | sandbox.files | sbx.Files() |
| Commands | sandbox.commands | sandbox.commands | sbx.Commands() |
| Public URL | sandbox.getHost(port) | sandbox.get_host(port) | sbx.GetHost(port) |
| Code interpreter | sandbox.runCode(...) | sandbox.run_code(...) | RunCode |
| Template builds | Template.build(...) | Template.build(...) | sandbox.BuildTemplate(...) |
| Task | Prefer |
|---|
| Product backend creates and operates sandboxes | SDK |
| Agent orchestration with files, commands, and previews | SDK |
| Building custom templates from local source | SDK |
| Debugging route contracts or auth headers | Raw HTTP |
| Building a low-level dashboard or gateway proxy | Raw HTTP plus typed response models |
| Investigating SDK behavior | Raw HTTP reproduction with the same sandbox ID |
Control-plane calls:
X-API-Key: <SEACLOUD_API_KEY>
Runtime calls to envdUrl:
X-Access-Token: <envdAccessToken>
Runtime health endpoints are exceptions: GET {envdUrl}/health, GET {envdUrl}/, and OPTIONS * do not require runtime token auth.
| Method | Path | Purpose |
|---|
POST | /api/v1/sandboxes | Create a sandbox. |
GET | /api/v1/sandboxes | List visible sandboxes. |
GET | /api/v1/sandboxes/:sandboxID | Fetch detail. |
POST | /api/v1/sandboxes/:sandboxID/connect | Reconnect runtime access. |
POST | /api/v1/sandboxes/:sandboxID/pause | Pause runtime. |
POST | /api/v1/sandboxes/:sandboxID/refreshes | Refresh TTL. |
POST | /api/v1/sandboxes/:sandboxID/timeout | Set timeout in seconds. |
DELETE | /api/v1/sandboxes/:sandboxID | Delete sandbox. |
GET | /api/v1/usage/limits | Read sandbox quota usage. |
GET | /api/v1/usage/template-limits | Read template/build quota usage. |
GET | /api/v1/observability/summary | Read user/project usage, quota checks, endpoint availability, and suggested actions. |
Store opaque identifiers and public status fields. Do not parse IDs or derive infrastructure state from them.
| Field | Store? | Notes |
|---|
sandboxID | Yes | Primary key for detail, logs, metrics, connect, and delete. |
templateID | Yes | Required for audit and reproducibility. |
state / status | Yes | Display current lifecycle state. |
timeline | Yes, optional | Good for user-facing progress. |
diagnostic | Yes, optional | Good for troubleshooting copy and next actions. |
envdUrl | Short-lived only | Use through SDK/runtime helpers; do not treat as permanent. |
envdAccessToken | Secret | Never expose to browser, users, or model prompts. |
requestID | Yes for errors | Include in support tickets and logs. |
| Method | Path | Purpose |
|---|
POST | /api/v1/templates | Create custom template metadata. |
GET | /api/v1/templates | List visible templates. |
GET | /api/v1/templates/resolve/:ref | Resolve official aliases or tags. |
GET | /api/v1/templates/:id | Fetch template detail. |
POST | /api/v1/templates/:id/builds/:buildID | Start a build. |
GET | /api/v1/templates/:id/builds/:buildID/status | Poll build status. |
GET | /api/v1/templates/:id/builds/:buildID/logs | Read build logs. |
POST | /api/v1/templates/:id/rollback | Roll back to a ready build. |
| Group | Routes |
|---|
| REST helpers | GET /files, POST /files, POST /files/batch, POST /files/compose, POST /run, GET/POST /file |
| Filesystem RPC | POST /filesystem.Filesystem/* |
| Process RPC | POST /process.Process/* |
| Surface | Route | Notes |
|---|
| Sandbox logs | GET /api/v1/sandboxes/:sandboxID/logs | Supports cursor, direction, level, search, and limit up to 1000. |
| Build logs | GET /api/v1/templates/:id/builds/:buildID/logs | Supports cursor, direction, level, and limit up to 100. |
| Sandbox metrics | GET /api/v1/sandboxes/:sandboxID/metrics | Control-plane snapshot for dashboards. |
| Fleet metrics | GET /api/v1/sandboxes/metrics | Batch current metrics for visible sandboxes. |
| Runtime metrics | GET {envdUrl}/metrics | Direct runtime snapshot with X-Access-Token. |
Control-plane errors use this shape:
"message": "templateID is required",
For 429, inspect details.usageEndpoint and show scope, resource, metric, used, limit, and remaining to the user.
Use SDKs or raw HTTP for the MVP sandbox integration path.
