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

# Compilación y operaciones

## Compilación

Una vez que la definición de una plantilla esté lista, usa `Template.build(...)` para compilarla. La compilación acepta un nombre de plantilla más ajustes de compilación opcionales, como CPU, memoria, tags, comportamiento de caché y un callback de registro de compilación.

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

Si quieres crear una compilación sin bloquearte durante todo el proceso, usa `Template.buildInBackground(...)` / `Template.build_in_background(...)` y revisa el estado de la compilación más tarde.

## Nombres

Cada compilación necesita un nombre de plantilla. Mantén nombres estables para una familia lógica de plantillas, por ejemplo:

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

Trata el nombre como la identidad duradera de la familia de plantillas. El ID de plantilla devuelto es el resultado de compilación inmutable que usas en tiempo de ejecución.

## Tags y versionado

Los tags te permiten etiquetar compilaciones para la gestión de versiones sin cambiar el nombre de la plantilla subyacente.

Los patrones típicos incluyen:

* versiones semánticas como `v1.0.0`
* etiquetas de promoción como `staging` o `production`
* canales móviles como `latest`

Puedes asignar tags durante la compilación o después de la compilación con las APIs de tags de plantilla.

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

Usa nombres para la familia de plantillas y tags para los marcadores de versión. Eso mantiene simples los flujos de trabajo de avance y reversión.

## Registro

Los registros de compilación te ayudan a inspeccionar el progreso del aprovisionamiento y diagnosticar errores.

En JavaScript y TypeScript, pasa `onBuildLogs` a `Template.build(...)`. El SDK también exporta `defaultBuildLogger(...)` para un logger de consola estándar.

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

Si compilas en segundo plano, usa `Template.getBuildStatus(...)` / `Template.get_build_status(...)` para consultar el estado y recuperar entradas de registro más tarde.

## Manejo de errores

Las compilaciones de plantillas pueden fallar por varias razones comunes:

* credenciales no válidas para un registro privado
* fallos de instalación de paquetes dentro de `runCmd(...)` / `run_cmd(...)`
* un comando de inicio que finaliza inesperadamente
* un comando de preparación que nunca se completa correctamente
* ajustes de CPU y memoria que no satisfacen los límites de la plataforma

Cuando una compilación falla:

1. inspecciona primero los registros de compilación
2. valida la imagen de origen o el Dockerfile de la plantilla
3. vuelve a ejecutar con la caché deshabilitada si sospechas de una capa obsoleta
4. reduce la plantilla a la secuencia de instrucciones fallida más pequeña

Para flujos de compilación asíncronos, comprueba el estado de compilación devuelto. El SDK expone estados como `building`, `waiting`, `ready` y `error`.