# Tempo de execução e sandbox

Ciclo de vida do sandbox, ambiente injetado, famílias de tokens e a imagem a partir da qual uma sessão é iniciada.

Canonical page: https://beeuni.ai/docs/pt/work/runtime

Cada sessão é executada em seu próprio ambiente isolado. Esta página é a referência para o ciclo de vida do sandbox, o ambiente que o Beeuni injeta na inicialização, as famílias de tokens e a própria imagem do sandbox. Para entender o conceito de sessão, consulte [Sessions](/docs/pt/work/sessions).

<a id="sandbox-lifecycle"></a>

## Ciclo de vida do sandbox

Uma linha de sessão contém um `status`. O enum define `queued`, `branching`, `provisioning`, `running`, `stopped`, `failed`, `completed`, mas o Beeuni grava apenas 4 deles.

| Status | Definido quando |
| --- | --- |
| `provisioning` | Ao criar a sessão. O Beeuni cria o branch da sessão e solicita o sandbox. |
| `running` | Quando o sandbox está ativo e acessível. |
| `stopped` | Ao parar explicitamente ou pela limpeza de inatividade que hiberna sandboxes inativos. |
| `failed` | Se o provisionamento falhar. |

`queued`, `branching` e `completed` existem no enum, mas não são usados no fluxo da sessão. Não os trate como estados ativos.

O próprio sandbox tem um `status` separado em sua própria linha, com seu próprio enum.

| Status | Definido quando |
| --- | --- |
| `provisioning` | O provedor inicializa o sandbox. |
| `active` | O provedor confirma que o sandbox está ativo. |
| `stopped` | Parada explícita, parada automática por inatividade ou durante uma reinicialização. |
| `error` | O provedor informa uma falha de inicialização ou de execução. |
| `archived` | Terminal. Você excluiu a sessão e o provedor destruiu o sandbox, em vez de pausá-lo. |

O Beeuni não limita quantas sessões podem ser executadas ao mesmo tempo por conta ou projeto. Sessões em execução cobram pelo uso de computação; uma conta sem créditos recebe `402` ao criar uma sessão.

<a id="branch-model"></a>

### Modelo de branches

- O branch da sessão tem o nome do ID da sessão (um UUID). `BEEUNI_SESSION_ID` e `BEEUNI_BRANCH_NAME` têm o mesmo valor.
- O Beeuni cria o branch a partir de `base_ref`, que por padrão é o branch padrão do projeto, no momento da criação da sessão.
- Os gatilhos criam o branch da sessão da mesma forma que uma sessão interativa.
- Nada grava diretamente no branch padrão. Isso só acontece com uma [solicitação de alteração](/docs/pt/work/change-requests) mesclada.

<a id="reconcile-a-session-branch"></a>

### Reconciliar um branch de sessão

Use **Ask Agent: Sync Branch & Reload** na paleta de comandos da sessão quando o branch base mudar. O agente inspeciona o branch da sessão, preserva o trabalho local, busca o `base_ref` mais recente, resolve conflitos, executa os testes relevantes e confirma a reconciliação. O Beeuni não escolhe um dos lados de um conflito nem redefine a árvore de trabalho.

O agente termina com `beeuni sessions reload "$BEEUNI_SESSION_ID" --project "$BEEUNI_PROJECT_ID" --no-repo --force --yes`. `--no-repo` é necessário porque o agente já reconciliou o branch. A recarga substitui o runtime do harness padrão depois que a substituição fica saudável. Ela encerra o turno atual; portanto, envie `continue` depois que o runtime retornar.

O cabeçalho da sessão informa em tempo real cada fase de recarga confirmada pelo servidor. Uma recarga pela web verifica a sessão, compila a configuração do agente, aplica e valida a substituição do runtime e, em seguida, confirma a configuração ativa. Ela não atualiza o repositório. A CLI pode atualizar o repositório, a menos que você passe `--no-repo`.

<a id="config-convergence"></a>

### Convergência da configuração

<a id="where-a-box-gets-the-release"></a>

Cada sessão usa a configuração da sua branch base. Envie as alterações para ela e recarregue a sessão. Atualizações aguardam o fim do turno ativo. Config Releases não tem mais uma flag separada.

Use **Reload config** ou `beeuni sessions reload <session id>`. Se o carregamento falhar, consulte os detalhes do erro e corrija a configuração do projeto.

<a id="workspace-is-where-you-edit-the-base-branch-is-what-runs"></a>

#### `/workspace` é onde você edita; a branch base é o que é executado

Uma sessão SEMPRE executa a configuração atual da branch base. Não existe modo de configuração por sessão.

`/workspace` é o checkout editável. Leia a configuração ali e altere-a ali — a alteração chega à sessão em execução quando é **enviada para a branch base**, depois do que a convergência normal a incorpora. Uma edição que está apenas em `/workspace` não altera o comportamento da sessão, e o agente em execução é informado disso: suas instruções identificam o commit de onde vem sua configuração e dizem que `/workspace` pode estar atrás dele.

A cópia do release é somente leitura, portanto uma edição na cópia errada falha com um erro de permissão em vez de não fazer nada silenciosamente.

<a id="when-the-configuration-no-longer-declares-a-sessions-agent"></a>

#### Quando a configuração deixa de declarar o agente de uma sessão

Uma sessão é criada com um agente. Se um commit posterior remover ou renomear esse agente, a sessão passará para o agente padrão do projeto — uma vez, e somente quando o proprietário da sessão puder usar esse agente. A Beeuni registra a mudança no log de auditoria e a informa nas instruções do agente em execução, para que a sessão diga o que aconteceu.

Se o proprietário não puder usar o agente padrão, ou se o projeto não declarar um padrão, a sessão fica sem agente e sem acesso a agentes. Ela ainda é inicializada e informa o motivo. Declare o agente novamente, defina um agente padrão para o projeto ou peça acesso ao agente padrão a um gerente do projeto.

<a id="what-the-session-header-shows"></a>

#### O que o cabeçalho da sessão mostra

| Estado | Condição | Cabeçalho |
| --- | --- | --- |
| Atual | Não obsoleto, sem fallback | Nada |
| Atualização disponível | `stale: true` | O badge de atualização, com **Recarregar configuração** |
| Fallback | `fallback_reason` definido | Um chip vermelho: **Falha ao carregar a configuração** |

Um recarregamento que termina em fallback informa um erro, não um sucesso.

<a id="reload-config"></a>

#### Recarregar configuração

**Recarregar configuração** — e `beeuni sessions reload <session id>` — faz duas coisas em uma única etapa e informa o que aconteceu com cada uma:

1. Move a sessão em execução para os agentes, skills e ferramentas atuais da branch base.
2. Faz fast-forward do checkout `/workspace`, para que os arquivos lidos ali correspondam à configuração executada pela sessão.

O pull do checkout usa apenas fast-forward, na branch da própria sessão, portanto não descarta nada. Passe `--no-repo` na CLI para ignorá-lo. Para trazer o CÓDIGO de `base_ref` para a branch da sessão, use **Pedir ao agente para sincronizar**.

<a id="turning-it-off"></a>

#### Desativando

Os releases de configuração são um recurso por projeto, **Releases de configuração**, em **Configurações → Sinalizadores de recursos**. Ele vem desativado por padrão. Com o sinalizador desativado, uma sessão lê sua configuração de `/workspace`: o harness padrão lê o diretório de configuração dali, e o harness experimental lê `skills/` dali. Nenhum release é criado, e o cabeçalho da sessão mostra o estado anterior, baseado em etag. A alteração entra em vigor na próxima inicialização ou no início da box de cada sessão; uma sessão em execução continua funcionando até lá. Ativá-lo novamente faz cada sessão convergir outra vez na próxima inicialização ou início.

<a id="injected-environment"></a>

## Ambiente injetado

A Beeuni injeta estas variáveis na inicialização. Somente um segredo do projeto configurado explicitamente para entrega `runtime` entra no sandbox. As credenciais de conectores e provedores de modelos permanecem no servidor da Beeuni.

| Variável | Descrição |
| --- | --- |
| `BEEUNI_PROJECT_ID` | UUID deste projeto. |
| `BEEUNI_SESSION_ID` | UUID desta sessão. Também é o nome da ramificação. |
| `BEEUNI_BRANCH_NAME` | Mesmo valor que `BEEUNI_SESSION_ID`. |
| `BEEUNI_REPO_URL` | URL de clone do repositório do projeto. |
| `BEEUNI_DEFAULT_BRANCH` | Ramificação padrão do projeto. |
| `BEEUNI_BASE_REF` | A referência da qual esta sessão criou uma ramificação. |
| `BEEUNI_API_URL` | URL base da API da plataforma (`.../v1`). |
| `BEEUNI_AGENT_NAME` | O agente com o qual a sessão foi criada. |
| `BEEUNI_MODEL` | O modelo a executar, quando definido. `BEEUNI_OPENCODE_MODEL` tem o mesmo valor para daemons criados antes da existência deste nome. |
| `BEEUNI_LLM_BASE_URL` | URL base do gateway LLM da Beeuni. O gateway resolve as credenciais do provedor no servidor. |
| `BEEUNI_TOKEN` | A credencial Beeuni vinculada à sessão. Veja abaixo. |

A Beeuni não injeta `BEEUNI_WORKSPACE`. A imagem inclui `/workspace`, e nenhuma etapa específica da sessão a define. A Beeuni também não injeta um token do Git — o daemon busca uma credencial de clone de curta duração quando precisa dela; veja [Enviando alterações de uma sessão](#pushing-from-a-session) abaixo. A Beeuni rejeita um segredo do usuário cujo nome tenha o prefixo `BEEUNI_*`, pois reserva esse prefixo para variáveis da plataforma.

<a id="session-credential"></a>

## Credencial da sessão

A Beeuni tem tokens externos que você mesmo cria e uma credencial dentro de cada sandbox.

<a id="external-tokens"></a>

### Tokens externos

Um token de acesso pessoal (PAT, com o prefixo `beeuni_pat_`) ou uma conta de serviço (com o prefixo `beeuni_sa_`) autentica chamadas à API, ao SDK e à CLI da Beeuni feitas de fora de uma sandbox. Consulte Autenticação para ver os escopos de PAT, a configuração de contas de serviço e como escolher entre eles.

<a id="in-sandbox-token"></a>

### Token dentro da sandbox

`BEEUNI_TOKEN` é emitido quando a Beeuni inicia o ambiente da sessão. Ele é vinculado ao usuário que inicia a sessão, ao projeto, à sessão e à autorização do agente. Cada rota da API ainda aplica sua própria verificação de capacidade.

Os identificadores do prompt inicial e do registro de turnos não são variáveis de ambiente. Após a inicialização, o daemon os obtém da API com `BEEUNI_TOKEN`.

<a id="pushing-from-a-session"></a>

## Enviando alterações de uma sessão

Nenhum token Git upstream entra na sandbox. `git push origin HEAD` envia os commits para a ramificação da sessão. Para integrar as alterações à ramificação padrão, é necessário mesclar uma [solicitação de alteração](/docs/pt/work/change-requests).

<a id="the-sandbox-image"></a>

## A imagem da sandbox

Seu Dockerfile define o ambiente base. A Beeuni fornece as ferramentas da sessão e a conexão com o painel.

<a id="declare-a-template"></a>

### Declarar um modelo

Faça referência ao Dockerfile como um modelo nomeado em `sandbox.templates` dentro de `beeuni.yaml`.

```yaml
sandbox:
  templates:
    - slug: dev
      name: Dev box
      dockerfile: Dockerfile.dev
  default: dev
```

Defina exatamente um de `dockerfile` ou `image` em cada entrada. Os caminhos do Dockerfile devem permanecer dentro do repositório. Defina `default` como o slug do modelo que suas sessões devem usar; omita-o para usar a imagem padrão da plataforma. Projetos antigos em `beeuni.toml` seguem os mesmos campos — consulte [legacy `beeuni.toml`](/docs/pt/project/legacy-toml). Lista completa de campos: [referência do manifesto](/docs/pt/project/manifest).

<a id="constraints"></a>

### Restrições

| Regra | Motivo |
| --- | --- |
| Não defina `ENTRYPOINT` nem `CMD`. | O Beeuni substitui ambos para iniciar o daemon. |
| Não use a porta `8000`. | Reservada para o proxy reverso do daemon. Execute servidores de desenvolvimento em outras portas. |
| Use `FROM` uma base Debian ou Ubuntu. | A camada de runtime executa `apt-get`. Alpine, Fedora e Arch causam falha na compilação. |
| Não execute `apt-get clean` sem `rm -rf /var/lib/apt/lists/*`. | A camada de runtime executa `apt-get update` novamente; um cache danificado causa falha na compilação. |
| Não inclua credenciais na imagem. | Declare o nome em `env:` e defina o valor como um segredo do projeto. O Beeuni o injeta no início da sessão. |

<a id="hardware-spec"></a>

### Especificações de hardware

`cpu`, `memory` e `disk` em uma entrada de modelo definem o tamanho do sandbox. Os três campos são opcionais; um campo omitido usa o padrão da plataforma: 2 vCPU, 4 GiB de memória e 20 GiB de disco.

```yaml
sandbox:
  templates:
    - slug: big
      image: ubuntu:24.04
      cpu: 4
      memory: 8
      disk: 50
```

`cpu` aceita de 1 a 32 núcleos, `memory` aceita de 1 a 128 GiB e `disk` aceita de 1 a 500 GiB. O Beeuni limita qualquer valor acima desses limites ao valor máximo. O Beeuni não oferece suporte a GPUs; uma chave `gpu` em um modelo gera um aviso, não um erro.

A especificação faz parte do snapshot do modelo, não é uma configuração por sessão. Alterá-la recompila o snapshot e se aplica à próxima sessão. A sessão atual mantém as especificações com que já foi iniciada.

<a id="docker-in-the-sandbox"></a>

### Docker no sandbox

Defina `container_runtime: true` em um modelo para executar o Docker dentro dos sandboxes: redes bridge e definidas pelo usuário, o driver de armazenamento `overlayfs` e saída NAT. Pilhas locais, como `supabase start` e `docker compose`, funcionam como em um laptop.

```yaml
sandbox:
  templates:
    - slug: dev
      dockerfile: .beeuni/Dockerfile.dev
      container_runtime: true
```

<a id="ports-and-preview-urls"></a>

### Portas e URLs de pré-visualização

O daemon escuta na porta `8000` e encaminha qualquer outra porta usada pelo seu app dentro do sandbox. Somente a própria porta `8000` é bloqueada pelo proxy.

O dashboard acessa uma porta do sandbox de duas formas:

- **Por caminho**: `https://<api-host>/v1/p/<sandbox-id>/<port>/...`. Este é o formato padrão e o único que oferece suporte a upgrades de WebSocket.
- **Por subdomínio**: `https://p<port>-<sandbox-id>.<api-host>/...`. Use este formato para apps que precisam de caminhos relativos à raiz ou cookies, como um servidor de desenvolvimento Next.js ou Vite. Ainda não há suporte a upgrades de WebSocket neste formato.

O proxy de pré-visualização remove `X-Frame-Options` e qualquer política `frame-ancestors`. Uma sessão pode incorporar a pré-visualização do seu app em um iframe sem nenhuma configuração da sua parte.

A pré-visualização de uma sessão também pode ser compartilhada por um link público, em modo somente leitura ou interativo. Os links públicos de compartilhamento bloqueiam as portas `22`, `4096`, `8000` e a porta de compartilhamento de arquivos estáticos.

<a id="snapshot-rebuilds"></a>

### Recompilações de snapshots

Alterações na imagem ou nas configurações do ambiente recompilam o ambiente para as sessões seguintes. Configurações inalteradas reutilizam a imagem existente. A primeira sessão que precisa de uma recompilação mostra "preparing image"; as seguintes reutilizam essa compilação.

Editar o Dockerfile dentro de uma sessão só terá efeito na próxima sessão, não na atual. A edição chega a `main` somente depois que a [solicitação de alteração](/docs/pt/work/change-requests) é mesclada.