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.

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.

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.

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.

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.

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

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.

Convergência da configuração

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.

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

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.

O que o cabeçalho da sessão mostra

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

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.

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.

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.

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 abaixo. A Beeuni rejeita um segredo do usuário cujo nome tenha o prefixo BEEUNI_*, pois reserva esse prefixo para variáveis da plataforma.

Credencial da sessão

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

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.

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.

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.

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.

Declarar um modelo

Faça referência ao Dockerfile como um modelo nomeado em sandbox.templates dentro de beeuni.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. Lista completa de campos: referência do manifesto.

Restrições

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.

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.

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.

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

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.

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 é mesclada.