Skip to main content
Build a reusable sandbox environment in three steps: define the template, wait for the build to finish, then create sandboxes from it.

​
Create the template

Pass a base image via from and (optionally) a list of build steps that run inside the build VM. 
import { Template } from "@superserve/sdk"

const template = await Template.create({
  name: "my-python-env",
  vcpu: 2,
  memoryMib: 2048,
  from: "python:3.11",
  steps: [
    { run: "pip install numpy pandas" },
    { env: { key: "DEBUG", value: "1" } },
    { workdir: "/app" },
  ],
})
Template.create returns once the template is registered and the first build is queued, not when the build is finished. Call waitUntilReady() (TS) / wait_until_ready() (Python) to block until the build reaches a terminal state.

​
Stream build logs

waitUntilReady accepts an onLog callback that receives each SSE event as the build runs. 
await template.waitUntilReady({
  onLog: (event) => {
    if (event.stream === "system") return  // skip system messages
    process.stdout.write(event.text)
  },
})
On success, waitUntilReady returns the refreshed TemplateInfo with status = "ready". On failure, it raises BuildError with a machine-readable code (e.g. step_failed, image_pull_failed).

​
Create a sandbox from the template

Once ready, create sandboxes by passing the Template instance, the name, or the UUID. 
import { Sandbox, Template } from "@superserve/sdk"

// Create the template first (see the section above)
const template = await Template.create({
  name: "my-python-env",
  from: "python:3.11",
})
await template.waitUntilReady()

// Option 1: pass the Template instance
const sandbox = await Sandbox.create({
  name: "run-1",
  fromTemplate: template,
})

// Option 2: pass the name
const sandbox2 = await Sandbox.create({
  name: "run-2",
  fromTemplate: "my-python-env",
})

// Option 3: pass the ID
const sandbox3 = await Sandbox.create({
  name: "run-3",
  fromTemplate: "8b050452",
})
The sandbox’s vCPU, memory, and disk size are inherited from the template; they cannot be overridden at sandbox creation (the snapshot dictates VM shape).