Skip to main content
A BuildSpec is the canonical declaration of how to build a template. The SDK flattens it onto TemplateCreateOptions for convenience: from / steps / startCmd / readyCmd are top-level options.

​
from: base image

An OCI image reference. Resolved to a digest at build time for reproducibility.
Constraints:
  • Must be a linux/amd64 image
  • Must include a shell at /bin/sh and the mkdir, mount, chmod, and sync commands, which every template boots and builds with. Debian, Ubuntu, Alpine, and BusyBox images all qualify; distroless and scratch-based images don’t.
Image settings: the image’s own ENV, WORKDIR, and USER carry over, as they do with docker run. Build steps see the image’s env vars and start in its working directory, but run as root. Sandbox commands, startCmd, and readyCmd also run as the image’s user. env, workdir, and user steps override the image.

​
steps: ordered build steps

A list of tagged objects executed in order inside the build VM. Exactly one of run / env / workdir / user must be set per step.

​
run: shell command

Wrapped in /bin/sh -c inside the build VM.

​
env: environment variable

Sets an env var for subsequent build steps AND as a runtime default. Caller-supplied envVars on sandbox create override on conflict.

​
workdir: working directory

Working directory for subsequent build steps and the runtime default cwd. Auto-created and chowned to the current build user. Per-exec workingDir overrides at runtime.

​
user: switch user

Switches the user for subsequent build steps and sets the runtime default exec user, in place of the image’s own USER. User is created if not present. sudo: true grants passwordless sudo.

​
startCmd: process to start after build

The snapshot captures the running process, so sandboxes restored from this template come up with it already live.

​
readyCmd: readiness probe

Polled every 2s after startCmd until it exits 0 or 10 minutes elapse. Use this to wait for a server to bind its port before snapshotting.

​
Resource limits

Templates specify the VM shape; sandboxes inherit these and cannot override them per-sandbox. memoryMib takes a value in MiB (1 GiB = 1024 MiB). Limits depend on your team’s plan. For larger sandboxes, email support@superserve.ai.

​
Build error codes

When a build lands on failed, BuildError.code carries one of these stable identifiers (the SDK parses it from the "<code>: <detail>" prefix on errorMessage): Template.create / rebuild can also be rejected before a build starts with a RateLimitError — too_many_builds (team’s concurrent-build limit) or too_many_templates (team’s template-count limit). These are not BuildError codes; see Errors.