Skip to main content

​
Build

Once a template definition is ready, use Template.build(...) to build it. The build accepts a template name plus optional build settings such as CPU, memory, tags, cache behavior, and a build log callback. 
import { Sandbox, Template } from "novita-sandbox"

const template = Template().fromImage("python:3.12")

const build = await Template.build(template, "my-python-template", {
  cpuCount: 2,
  memoryMB: 1024,
})

const sandbox = await Sandbox.create(build.templateId)
console.log(sandbox.sandboxId)

await sandbox.kill()
If you want to create a build without blocking on the full process, use Template.buildInBackground(...) / Template.build_in_background(...) and later inspect the build status.

​
Names

Every build needs a template name. Keep names stable for a logical template family, for example:
  • my-python-template
  • agent-runtime-base
  • sandbox-webapp
Treat the name as the long-lived identity of the template family. The returned template ID is the immutable build output you use at runtime.

​
Tags & versioning

Tags let you label builds for release management without changing the underlying template name. Typical patterns include:
  • semantic versions such as v1.0.0
  • promotion labels such as staging or production
  • moving channels such as latest
You can assign tags during build or after build with the template tag APIs. 
import { Template } from "novita-sandbox"

const template = Template().fromPythonImage("3.12")

const build = await Template.build(template, "agent-runtime-base", {
  tags: ["v1.0.0", "latest"],
})

await Template.assignTags("agent-runtime-base:v1.0.0", "production")

const tags = await Template.getTags(build.templateId)
console.log(tags)
Use names for the template family and tags for release markers. That keeps roll-forward and rollback workflows simple.

​
Logging

Build logs help you inspect provisioning progress and diagnose failures. In JavaScript and TypeScript, pass onBuildLogs to Template.build(...). The SDK also exports defaultBuildLogger(...) for a standard console logger. 
import { Template, defaultBuildLogger } from "novita-sandbox"

const template = Template().fromPythonImage("3.12")

await Template.build(template, "my-logged-template", {
  onBuildLogs: defaultBuildLogger({ minLevel: "info" }),
})
If you build in background, use Template.getBuildStatus(...) / Template.get_build_status(...) to poll status and retrieve log entries later.

​
Error handling

Template builds can fail for several common reasons:
  • invalid credentials for a private registry
  • package install failures inside runCmd(...) / run_cmd(...)
  • a start command that exits unexpectedly
  • a ready command that never succeeds
  • CPU and memory settings that do not satisfy platform limits
When a build fails:
  1. inspect build logs first
  2. validate the template source image or Dockerfile
  3. rerun with cache disabled if you suspect a stale layer
  4. reduce the template to the smallest failing instruction sequence
For asynchronous build flows, check the returned build status. The SDK exposes statuses such as building, waiting, ready, and error.
Last modified on June 12, 2026