# Build & operations - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/guides/sandbox-template-build-operations

# Build & operations

##

[​](#build)

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.

JavaScript & TypeScript

Python

```
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()
```

```
from novita_sandbox.core import Sandbox, Template

template = Template().from_image("python:3.12")

build = Template.build(
template,
"my-python-template",
cpu_count=2,
memory_mb=1024,
)

sandbox = Sandbox.create(build.template_id)
print(sandbox.sandbox_id)

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)

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

JavaScript & TypeScript

Python

```
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)
```

```
from novita_sandbox.core import Template

template = Template().from_python_image("3.12")

build = Template.build(
template,
"agent-runtime-base",
tags=["v1.0.0", "latest"],
)

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

tags = Template.get_tags(build.template_id)
print(tags)
```

Use names for the template family and tags for release markers. That keeps roll-forward and rollback workflows simple.

##

[​](#logging)

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.

JavaScript & TypeScript

Python

```
import { Template, defaultBuildLogger } from "novita-sandbox"

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

await Template.build(template, "my-logged-template", {
onBuildLogs: defaultBuildLogger({ minLevel: "info" }),
})
```

```
from novita_sandbox.core import Template

template = Template().from_python_image("3.12")

build = Template.build(template, "my-logged-template")
print(build.build_id)
```

If you build in background, use `Template.getBuildStatus(...)` / `Template.get_build_status(...)` to poll status and retrieve log entries later.

##

[​](#error-handling)

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:

- inspect build logs first

- validate the template source image or Dockerfile

- rerun with cache disabled if you suspect a stale layer

- 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 4, 2026