> ## 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 et opérations

## Build

Une fois qu’une définition de template est prête, utilisez `Template.build(...)` pour la builder. Le build accepte un nom de template ainsi que des paramètres de build facultatifs, tels que le CPU, la mémoire, les tags, le comportement du cache et un callback de journal de build.

<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 vous souhaitez créer un build sans bloquer sur l’ensemble du processus, utilisez `Template.buildInBackground(...)` / `Template.build_in_background(...)`, puis inspectez ultérieurement le statut du build.

## Noms

Chaque build nécessite un nom de template. Gardez des noms stables pour une famille logique de templates, par exemple :

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

Considérez le nom comme l’identité durable de la famille de templates. L’ID de template renvoyé est la sortie de build immuable que vous utilisez à l’exécution.

## Tags et versionnement

Les tags vous permettent de libeller les builds pour la gestion des releases sans modifier le nom de template sous-jacent.

Les motifs courants incluent :

* des versions sémantiques telles que `v1.0.0`
* des libellés de promotion tels que `staging` ou `production`
* des canaux mobiles tels que `latest`

Vous pouvez assigner des tags pendant le build ou après le build avec les API de tags de template.

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

Utilisez les noms pour la famille de templates et les tags pour les marqueurs de release. Cela simplifie les workflows de roll-forward et de rollback.

## Journalisation

Les journaux de build vous aident à inspecter la progression du provisionnement et à diagnostiquer les échecs.

En JavaScript et TypeScript, passez `onBuildLogs` à `Template.build(...)`. Le SDK exporte également `defaultBuildLogger(...)` pour un logger console standard.

<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 vous buildez en arrière-plan, utilisez `Template.getBuildStatus(...)` / `Template.get_build_status(...)` pour interroger le statut et récupérer les entrées de journal ultérieurement.

## Gestion des erreurs

Les builds de templates peuvent échouer pour plusieurs raisons courantes :

* identifiants non valides pour un registre privé
* échecs d’installation de packages dans `runCmd(...)` / `run_cmd(...)`
* une commande de démarrage qui se termine de manière inattendue
* une commande de disponibilité qui ne réussit jamais
* des paramètres CPU et mémoire qui ne respectent pas les limites de la plateforme

Lorsqu’un build échoue :

1. inspectez d’abord les journaux de build
2. validez l’image source ou le Dockerfile du template
3. relancez avec le cache désactivé si vous soupçonnez une couche obsolète
4. réduisez le template à la plus petite séquence d’instructions qui échoue

Pour les flux de build asynchrones, vérifiez le statut de build renvoyé. Le SDK expose des statuts tels que `building`, `waiting`, `ready` et `error`.