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

# Conceitos

## Como funciona

Em alto nível, uma compilação de template funciona assim:

1. Resolve a origem do template, como uma imagem base padrão, uma imagem existente, um Dockerfile ou outro template.
2. Aplica instruções do template, como `runCmd`, `copy`, `makeDir`, `setEnvs` e auxiliares de instalação de pacotes.
3. Se configurado, inicia o comando de inicialização do template.
4. Aguarda até que o [comando ready](/docs/pt-BR/guides/sandbox-template-authoring#start--ready-commands) seja concluído com sucesso.
5. Salva o ambiente preparado como um template reutilizável.

A compilação produz um `templateId` / `template_id` e um `buildId` / `build_id`. Use o ID do template posteriormente com `Sandbox.create(...)`.

## Usuário e diretório de trabalho

Templates podem definir o usuário Linux padrão e o diretório de trabalho usados por etapas de compilação posteriores e pelo ambiente final.

Use `setUser(...)` / `set_user(...)` quando os comandos de compilação precisarem ser executados como um usuário específico. Use `setWorkdir(...)` / `set_workdir(...)` quando comandos posteriores e arquivos copiados devem ser resolvidos em relação a um diretório específico.

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

  const template = Template()
    .fromUbuntuImage("24.04")
    .setUser("root")
    .setWorkdir("/app")
    .runCmd("apt-get update && apt-get install -y curl")
    .copy("package.json", "/app/package.json")
  ```

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

  template = (
      Template()
      .from_ubuntu_image("24.04")
      .set_user("root")
      .set_workdir("/app")
      .run_cmd("apt-get update && apt-get install -y curl")
      .copy("package.json", "/app/package.json")
  )
  ```
</CodeGroup>

Se você não definir esses valores, a sandbox usará os padrões da imagem base selecionada.

## Cache

Compilações de templates armazenam em cache camadas concluídas anteriormente, para que compilações repetidas não precisem executar novamente todas as instruções.

Geralmente, isso é o que você deseja para uma iteração rápida. Quando precisar de uma compilação totalmente nova, desative o cache para toda a compilação com `skipCache: true` / `skip_cache=True`, ou marque a cadeia de templates com `skipCache()` / `skip_cache()`.

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

  const template = Template()
    .fromPythonImage("3.12")
    .skipCache()
    .runCmd("pip install -U pip")

  const build = await Template.build(template, "my-template-no-cache", {
    skipCache: true,
  })
  ```

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

  template = (
      Template()
      .from_python_image("3.12")
      .skip_cache()
      .run_cmd("pip install -U pip")
  )

  build = Template.build(
      template,
      "my-template-no-cache",
      skip_cache=True,
  )
  ```
</CodeGroup>

Use a invalidação de cache intencionalmente. Ela torna as compilações mais lentas e normalmente deve ser reservada para atualização de dependências, depuração ou alterações em entradas que não são visíveis apenas pela definição do template.