> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build & operations

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

<CodeGroup>
  ```ts JavaScript & TypeScript icon="js" theme={"system"}
  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()
  ```

  ```python Python icon="python" theme={"system"}
  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()
  ```
</CodeGroup>

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.

<CodeGroup>
  ```ts JavaScript & TypeScript icon="js" theme={"system"}
  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)
  ```

  ```python Python icon="python" theme={"system"}
  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)
  ```
</CodeGroup>

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.

<CodeGroup>
  ```ts JavaScript & TypeScript icon="js" theme={"system"}
  import { Template, defaultBuildLogger } from "novita-sandbox"

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

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

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Template

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

  build = Template.build(template, "my-logged-template")
  print(build.build_id)
  ```
</CodeGroup>

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