Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt

Use this file to discover all available pages before exploring further.

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. 
from: "python:3.11"           // Docker Hub
from: "ghcr.io/myorg/foo:v1"  // any OCI registry
Constraints:
  • Must be a linux/amd64 image
  • Alpine and distroless bases are rejected at validation time (musl/busybox incompat with build tooling)

​
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

{ run: "pip install -r requirements.txt" }
Wrapped in /bin/sh -c inside the build VM.

​
env: environment variable

{ env: { key: "DEBUG", value: "1" } }
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

{ workdir: "/srv/app" }
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

{ user: { name: "appuser", sudo: true } }
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

startCmd: "python server.py"
The snapshot captures the running process, so sandboxes restored from this template come up with it already live.

​
readyCmd: readiness probe

readyCmd: "curl -f http://localhost:8080/health"
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.
FieldMinMaxDefault
vcpu141
memoryMib25640961024
diskMib102481924096

​
Build error codes

On failure, BuildError.code is one of these stable identifiers (parsed from errorMessage):
CodeMeaning
image_pull_failedBase image couldn’t be pulled or resolved
step_failedA build step exited non-zero
boot_failedBuild VM failed to boot
snapshot_failedSnapshot bundle couldn’t be produced
start_cmd_failedstartCmd exited non-zero before snapshot
ready_cmd_failedreadyCmd didn’t exit 0 within 10 minutes
too_many_buildsTeam’s concurrent build limit reached (raised as RateLimitError, not BuildError)
too_many_templatesTeam’s total template count limit reached (raised as RateLimitError)
build_failedCatch-all when no specific code applies