Sandbox Templates

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

Use official templates for first runs. Build custom templates when repeated setup should become reusable infrastructure.

When To Build A Template

Build a custom template when you need to:

• install dependencies once instead of on every sandbox start
• copy source code into a reusable image
• pin versions of OS packages and language packages
• define startCmd and readyCmd
• attach persistent storage paths through template policy
• promote known-good builds through tags such as stable or prod

Official Template Selection

Goal	Start with
Shell commands and file operations	base
Code interpreter and data analysis	code-interpreter
Node frontend or API service	node or web-frontend
Python service or scripts	python
Browser automation	browser
Durable workspace	nfs, cloud, block, or a custom tpl-...
Production repeatability	concrete tpl-...

SDK Build Example

Node

import { Sandbox, Template, waitForPort } from "@seacloudai/sandbox";

const built = await Template.build(
  new Template()
    .fromNodeImage("20-alpine")
    .copy("./my-app", "/app", { forceUpload: true })
    .runCmd("cd /app && npm install")
    .runCmd("cd /app && npm run build")
    .setStartCmd("cd /app && npm start", waitForPort(3000)),
  "my-app:v1",
  { wait: true },
);

const app = await Sandbox.create(built.templateId, { waitReady: true });
console.log(app.getHost(3000));

Public Build Flow

1. Create template metadata with POST /api/v1/templates.
2. Package local source as .tgz.
3. Upload the archive through the build context handshake.
4. Start a build through /api/v1/templates/:templateID/builds/:buildID.
5. Poll status until ready.
6. Create sandboxes from the returned templateID.

Build Context Upload

The public build flow deduplicates local source archives by hash.

GET /api/v1/templates/:id/files/:hash
X-API-Key: <token>

The response may include a signed upload URL and maxContextBytes.

{
  "present": false,
  "url": "https://storage.googleapis.com/...",
  "maxContextBytes": 104857600
}

The default single archive limit is 100MiB. Exclude .git, node_modules, dist, .next, cache directories, and generated build output before upload.

Build Status

Status	Meaning
uploaded	Waiting for the referenced build context upload.
waiting	Build accepted and queued.
building	Build job is running.
ready	Build finished and the template image is usable.
error	Build failed.

Build status responses may include timeline, steps, logs, logEntries, and reason. Use timeline and steps for progress UI, then show logs for details.

Tags And Stable References

Tags are build-version pointers. A reference such as my-template:stable resolves to the build image bound to the stable tag, not necessarily the template’s latest currentBuildId.

POST /api/v1/templates/tags
X-API-Key: <token>
Content-Type: application/json

{
  "target": "my-template:v1",
  "tags": ["stable", "prod"]
}

Dockerfile Mapping

The public build route currently accepts structured build steps rather than raw Dockerfile bodies.

Dockerfile instruction	Build payload
FROM node:20	fromImage: "node:20" or official base reference
WORKDIR /app	WORKDIR step
COPY . /app	COPY step with filesHash
RUN npm install	RUN step
ENV NODE_ENV=production	ENV step
CMD npm start	startCmd

Production reference

Use base and other official aliases for experiments. Use a concrete tpl-... ID or promoted tag for production so future official template updates do not change behavior unexpectedly.

Runtime Modes

Mode	Meaning
managed	nano-executor runtime APIs are available on the runtime port, usually 9000.
plain	The image owns its foreground application process; nano-daemon can still provide probes and heartbeat.

workdir controls default process and file roots. It does not create persistent storage. Storage topology comes from template volumeMounts.

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 Build Issues

Symptom	Check
Build stays uploaded	Archive upload is missing, filesHash changed, or build started before upload completed.
COPY filesHash is required	Each COPY step using local source needs a filesHash.
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.