> ## 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 e operações

## Build

Quando uma definição de template estiver pronta, use `Template.build(...)` para criá-la. O build aceita um nome de template mais configurações opcionais de build, como CPU, memória, tags, comportamento de cache e um callback de log 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>

Se você quiser criar um build sem bloquear durante todo o processo, use `Template.buildInBackground(...)` / `Template.build_in_background(...)` e inspecione o status do build posteriormente.

## Nomes

Todo build precisa de um nome de template. Mantenha os nomes estáveis para uma família lógica de templates, por exemplo:

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

Trate o nome como a identidade duradoura da família de templates. O ID do template retornado é a saída imutável do build que você usa em runtime.

## Tags e versionamento

Tags permitem rotular builds para gerenciamento de releases sem alterar o nome do template subjacente.

Padrões comuns incluem:

* versões semânticas, como `v1.0.0`
* rótulos de promoção, como `staging` ou `production`
* canais móveis, como `latest`

Você pode atribuir tags durante o build ou depois dele com as APIs 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>

Use nomes para a família de templates e tags para marcadores de release. Isso mantém simples os workflows de roll-forward e rollback.

## Logs

Os logs de build ajudam você a inspecionar o progresso de provisionamento e diagnosticar falhas.

Em JavaScript e TypeScript, passe `onBuildLogs` para `Template.build(...)`. O SDK também exporta `defaultBuildLogger(...)` para um logger de console padrão.

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

Se você fizer o build em segundo plano, use `Template.getBuildStatus(...)` / `Template.get_build_status(...)` para consultar o status e recuperar entradas de log posteriormente.

## Tratamento de erros

Builds de template podem falhar por vários motivos comuns:

* credenciais inválidas para um registry privado
* falhas de instalação de pacotes dentro de `runCmd(...)` / `run_cmd(...)`
* um comando de inicialização que encerra inesperadamente
* um comando de prontidão que nunca é bem-sucedido
* configurações de CPU e memória que não atendem aos limites da plataforma

Quando um build falhar:

1. inspecione primeiro os logs de build
2. valide a imagem de origem do template ou Dockerfile
3. execute novamente com o cache desabilitado se você suspeitar de uma camada desatualizada
4. reduza o template à menor sequência de instruções que falha

Para fluxos de build assíncronos, verifique o status de build retornado. O SDK expõe status como `building`, `waiting`, `ready` e `error`.