Sandbox Templates

Templates define the image, resources, env vars, startup behavior, and readiness checks used when a sandbox starts.

Use official templates for first runs. Pin a concrete template ID or promoted tag before production traffic.

When To Pin Or Request A Template

Move from a general official alias to a concrete template when you need to:

install dependencies once instead of on every sandbox start
reuse source code or prebuilt application assets
pin versions of OS packages and language packages
define startup behavior and readiness checks
promote known-good runtime behavior through a concrete tpl-... ID or tag

Official Template Selection

Goal	Start with
Shell commands and file operations	`base`
Code interpreter and data analysis	`code-interpreter` or `code-interpreter-lite`
Node frontend or API service	`node` or `web-frontend`
Python service or scripts	`python`
Browser automation	`browser`
Coding agents	`codex`, `claude`, `opencode`, `openclaw`, `amp`, or `openai-agents`
API, MCP, scraping, or DevOps tasks	`api-server`, `mcp-server`, `scraper`, or `devops`
Production repeatability	concrete `tpl-...`

Public Official Templates

The public documentation exposes these official template types. Availability can differ by environment, so list templates in the target environment before pinning one. Templates returned by the API but not listed here should be treated as environment-specific or internal templates, not as public integration targets.

Category	Official type	Typical CPU / memory	Use it for
Base runtime	`base`	`1 / 1024MB`	General shell commands, file APIs, PTY sessions, git operations, and lightweight services.
Language runtime	`node`	`2 / 2048MB`	Node.js scripts, package installs, API services, and JavaScript/TypeScript build or test jobs.
Language runtime	`python`	`2 / 2048MB`	Python scripts, small services, data preprocessing, dependency checks, and test jobs.
Language runtime	`go`	`2 / 4096MB`	Go build, test, CLI, and service workflows that need a prepared Go toolchain.
Web app	`web-frontend`	`2 / 4096MB`	Frontend previews, Vite/Next-style dev servers, and browser-openable web apps.
Code execution	`code-interpreter`	`2 / 4096MB`	Multi-language `runCode` workflows, data analysis, generated code execution, and artifact creation.
Code execution	`code-interpreter-lite`	`2 / 2048MB`	Lighter code execution jobs where startup cost and smaller resource reservation matter more than headroom.
Browser and desktop	`browser`	`2 / 4096MB`	Browser automation, web inspection, screenshot capture, and UI workflows that need browser dependencies.
Browser and desktop	`desktop`	`4 / 8192MB`	Computer-use style tasks, GUI tools, and heavier interactive desktop workflows.
Agent runtime	`codex`	`2 / 4096MB`	Codex-style coding agents that need a prepared command, file, and development environment.
Agent runtime	`claude`	`4 / 8192MB`	Claude coding-agent workflows that need larger memory headroom.
Agent runtime	`opencode`	`2 / 4096MB`	OpenCode-style coding agents and repository automation.
Agent runtime	`openclaw`	`4 / 8192MB`	Heavier OpenClaw agent workflows.
Agent runtime	`amp`	`2 / 4096MB`	AMP-style coding or automation agents.
Agent runtime	`openai-agents`	`2 / 4096MB`	Workflows built around the OpenAI Agents SDK or agent tool orchestration.
Service runtime	`api-server`	`2 / 2048MB`	Small HTTP APIs, callback servers, and service prototypes that expose a port.
Service runtime	`mcp-server`	`2 / 2048MB`	MCP server development, tool servers, and agent integration endpoints.
Automation runtime	`scraper`	`2 / 2048MB`	Scraping, extraction, and content collection jobs that need a prepared automation stack.
Automation runtime	`devops`	`2 / 2048MB`	Shell-heavy automation, deployment checks, infrastructure scripts, and operational probes.

List And Use Templates

GET /api/v1/templates?visibility=official&limit=200
X-API-Key: <token>

Use the returned templateID, alias, or promoted tag when creating a sandbox:

const sandbox = await Sandbox.create("base", {
  waitReady: true,
  timeout: 1800,
});

Official aliases may move as templates are patched. Production workloads should prefer a concrete tpl-... ID or an explicitly promoted tag.

Custom Template Builds

Projects with template build access can use the CLI or template API to build a reusable template from a Dockerfile, a prebuilt image, or an existing template:

seacloud template build my-template --dockerfile Dockerfile --cpu-count 2 --memory-mb 2048 --tag v1
seacloud template status <template_id> <build_id>
seacloud template logs <template_id> <build_id> --limit 100

After the build is ready, create sandboxes from the returned templateID, the template name, or a promoted tag. If the current account does not have build access, use a public official template or request a prepared platform template. Build logs and status are exposed through /api/v1/templates/:templateID/builds/:buildID/status and /api/v1/templates/:templateID/builds/:buildID/logs.

Runtime Modes

Mode	Meaning
`managed`	Runtime APIs are available on the runtime port, usually `9000`.
`plain`	The image owns its foreground application process; platform health checks can still run.

workdir controls default process and file roots. Production templates should set it explicitly so commands, file APIs, and app startup agree on the same directory.

`startCmd` And `readyCmd`

Use startCmd to start long-running application processes for future sandboxes. Use readyCmd to decide when a sandbox created from the template is usable.

Good readiness checks are local, bounded, and aligned with the port users will open:

wget -q -O- http://127.0.0.1:3000/ >/dev/null

Avoid checks that only prove a process exists but not that the app is ready:

ps aux | grep node

startCmd and readyCmd use shell semantics. The image should include /bin/sh, or the command should be written for the shell available in that image.

Pattern	Recommendation
HTTP app	`startCmd` starts the server; `readyCmd` curls the local app port.
Background worker	`readyCmd` checks a health file, PID, queue connection, or worker heartbeat.
Frontend preview	Bind `0.0.0.0`; `readyCmd` checks `127.0.0.1:<port>`; users open `getHost(port)`.
Heavy dependency setup	Move install steps into build `RUN` steps, not sandbox startup.

Common Template Issues

Symptom	Check
Sandbox never becomes `running`	Runtime mode, image entrypoint, readiness port, and health check configuration.
Sandbox starts but preview returns `502`	`startCmd` exited, wrong port, or app only binds localhost.
`readyCmd` times out	The service did not respond on the expected localhost port inside the sandbox.