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
  • Alpine bases are rejected
  • Distroless bases are rejected — they ship no shell, so run steps can’t execute

​
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. 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. The Max column is the platform ceiling. New teams start with a lower per-team cap (2 vCPU, 2048 MiB memory); email support@superserve.ai to raise it.

​
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.