SDK & CLI Guide

Use SDKs for application integrations. Use raw HTTP when verifying HTTP routes, auth headers, or SDK behavior.

Recommended Integration Shape

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.

Install

SDK	Install
Node	npm install @seacloudai/sandbox
Python	pip install seacloud-sandbox
Go	go get github.com/SeaCloudAI/sandbox-go

Configure

export SEACLOUD_BASE_URL="https://sandbox-service.real-cloud.seaart.ai/api/v1/sandbox"
export SEACLOUD_API_KEY="YOUR_API_KEY"

Variable	Required	Purpose
SEACLOUD_BASE_URL	yes	API base URL.
SEACLOUD_API_KEY	yes	API key sent as X-API-Key.

SDK Surface

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	CLI / HTTP API	CLI / HTTP API	CLI / HTTP API

When To Use SDKs Or HTTP

Task	Prefer
Product backend creates and operates sandboxes	SDK
Agent orchestration with files, commands, and previews	SDK
Listing and pinning official templates	SDK or raw HTTP
Building custom templates from local source	CLI, or HTTP API for backend integrations
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

Raw HTTP Auth

SeaCloud Sandbox API 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.

Sandbox API Endpoints

Method	Path	Purpose
POST	/sandboxes	Create a sandbox.
GET	/sandboxes	List visible sandboxes.
GET	/sandboxes/:sandboxID	Fetch detail.
POST	/sandboxes/:sandboxID/connect	Reconnect runtime access.
POST	/sandboxes/:sandboxID/pause	Pause runtime.
POST	/sandboxes/:sandboxID/refreshes	Refresh TTL.
POST	/sandboxes/:sandboxID/timeout	Set timeout in seconds.
DELETE	/sandboxes/:sandboxID	Delete sandbox.
GET	/usage/limits	Read sandbox quota usage.
GET	/observability/summary	Read caller usage, quota checks, endpoint availability, and suggested actions.

Response Fields To Store

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, when returned	Store the resolved template for audit and reproducibility. Create requests may omit it to use base.
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.

Template Endpoints

Method	Path	Purpose
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.

Runtime API Groups

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/*

Logs, Metrics, And Errors

Surface	Route	Notes
Sandbox logs	GET /sandboxes/:sandboxID/logs	Supports cursor, direction, level, search, and limit up to 1000.
Sandbox metrics	GET /sandboxes/:sandboxID/metrics	Dashboard metric snapshot.
Fleet metrics	GET /sandboxes/metrics	Batch current metrics for visible sandboxes.
Runtime metrics	GET {envdUrl}/metrics	Direct runtime snapshot with X-Access-Token.

API errors use this shape:

{
  "code": 400,
  "message": "timeoutMs is no longer supported in sandbox create requests; use timeout seconds",
  "requestID": "req-..."
}

For 429, inspect details.usageEndpoint and show scope, resource, metric, used, limit, and remaining to the user.

CLI Status

CLI availability

The SeaCloud CLI includes sandbox lifecycle commands, runtime command execution, logs, metrics, network policy, volumes, events, webhooks, team metrics, observability, and template build commands. Use --output json or --format json for automation, and use the global --dry-run flag before write/delete/replay operations.

CLI Quick Reference

Sandbox and template commands use the SeaCloud login session:

seacloud auth login
seacloud auth status

Core sandbox workflow:

seacloud sandbox create base --no-connect --wait --output json --metadata app=agent
seacloud sandbox list --state running,paused --output json
seacloud sandbox exec <sandbox_id> "python --version"
seacloud sandbox logs <sandbox_id> --limit 100 --direction backward --output json
seacloud sandbox metrics <sandbox_id> --output json
seacloud sandbox connect <sandbox_id> --shell bash
seacloud sandbox pause <sandbox_id>
seacloud sandbox timeout <sandbox_id> --seconds 3600
seacloud --dry-run sandbox kill <sandbox_id>
seacloud sandbox kill <sandbox_id>

Network and storage helpers:

seacloud sandbox network update <sandbox_id> --allow-internet-access=false --allow-out 1.1.1.1/32
seacloud sandbox volume create cache
seacloud sandbox create base --volume-mount cache:/cache --no-connect --wait --output json

Events, webhooks, and observability:

seacloud sandbox events --type sandbox.lifecycle.created --limit 20
seacloud sandbox webhook create --name lifecycle --url https://example.com/webhook --secret <secret> --event sandbox.lifecycle.created
seacloud sandbox webhook deliveries --status failed --limit 20
seacloud sandbox observability

Template projects and builds:

seacloud template init --language typescript --name my-template
seacloud template build my-template --dockerfile Dockerfile --tag v1
seacloud template list --format json
seacloud template get <template_id>
seacloud template logs <template> <build_id> --limit 100

For the full command list, see SeaCloud CLI command reference.