> ## 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 & Betrieb

## Build

Sobald eine Template-Definition bereit ist, verwenden Sie `Template.build(...)`, um sie zu bauen. Der Build akzeptiert einen Template-Namen sowie optionale Build-Einstellungen wie CPU, Arbeitsspeicher, Tags, Cache-Verhalten und einen 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>

Wenn Sie einen Build erstellen möchten, ohne auf den vollständigen Prozess zu blockieren, verwenden Sie `Template.buildInBackground(...)` / `Template.build_in_background(...)` und prüfen Sie später den Build-Status.

## Namen

Jeder Build benötigt einen Template-Namen. Halten Sie Namen für eine logische Template-Familie stabil, zum Beispiel:

* `my-python-template`
* `agent-runtime-base`
* `sandbox-webapp`

Betrachten Sie den Namen als die langlebige Identität der Template-Familie. Die zurückgegebene Template-ID ist die unveränderliche Build-Ausgabe, die Sie zur Laufzeit verwenden.

## Tags & Versionierung

Mit Tags können Sie Builds für das Release-Management kennzeichnen, ohne den zugrunde liegenden Template-Namen zu ändern.

Typische Muster sind:

* semantische Versionen wie `v1.0.0`
* Promotion-Labels wie `staging` oder `production`
* bewegliche Kanäle wie `latest`

Sie können Tags während des Builds oder nach dem Build mit den Template-Tag-APIs zuweisen.

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

Verwenden Sie Namen für die Template-Familie und Tags für Release-Markierungen. So bleiben Roll-forward- und Rollback-Workflows einfach.

## Logging

Build-Logs helfen Ihnen, den Provisionierungsfortschritt zu überprüfen und Fehler zu diagnostizieren.

In JavaScript und TypeScript übergeben Sie `onBuildLogs` an `Template.build(...)`. Das SDK exportiert außerdem `defaultBuildLogger(...)` für einen standardmäßigen Konsolen-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>

Wenn Sie im Hintergrund bauen, verwenden Sie `Template.getBuildStatus(...)` / `Template.get_build_status(...)`, um den Status abzufragen und Log-Einträge später abzurufen.

## Fehlerbehandlung

Template-Builds können aus mehreren häufigen Gründen fehlschlagen:

* ungültige Anmeldedaten für eine private Registry
* Fehler bei der Paketinstallation innerhalb von `runCmd(...)` / `run_cmd(...)`
* ein Startbefehl, der unerwartet beendet wird
* ein Ready-Befehl, der nie erfolgreich ist
* CPU- und Arbeitsspeichereinstellungen, die die Plattformgrenzen nicht erfüllen

Wenn ein Build fehlschlägt:

1. prüfen Sie zuerst die Build-Logs
2. validieren Sie das Template-Quell-Image oder Dockerfile
3. führen Sie den Build mit deaktiviertem Cache erneut aus, wenn Sie eine veraltete Schicht vermuten
4. reduzieren Sie das Template auf die kleinste fehlgeschlagene Befehlssequenz

Prüfen Sie bei asynchronen Build-Flows den zurückgegebenen Build-Status. Das SDK stellt Statuswerte wie `building`, `waiting`, `ready` und `error` bereit.