Sandbox de Agente de Codificação: Como Executar Código Gerado por Agente com Segurança

Um sandbox de agente de codificação permite que comandos e alterações de código gerados pelo agente sejam executados em um espaço de trabalho com escopo definido, onde arquivos, processos, acesso à rede, segredos, logs e artefatos de revisão podem ser controlados. O objetivo prático não é fingir que código gerado arbitrariamente é inofensivo. O objetivo é tratar o agente como um colaborador não confiável com uma máquina de desenvolvimento descartável, limites claros, execução observável e um caminho de aprovação humana antes que qualquer coisa chegue à produção.

O que um sandbox de agente de codificação precisa isolar

Um agente de codificação se torna útil quando pode inspecionar um repositório, editar arquivos, executar testes, instalar dependências e devolver um patch. Essas também são as ações que tornam o ambiente arriscado. Uma instalação de dependência por injeção de prompt, um comando de shell destrutivo ou um segredo acidentalmente exposto podem causar mais danos do que uma resposta textual ruim.

Projete o sandbox em torno dos recursos que um agente de codificação pode tocar:

Superfície	O que controlar	Por que é importante
Checkout do repositório	Branch, commit SHA, escopo de escrita, submódulos, arquivos gerados	Impede que o agente altere a base de código errada ou esconda alterações fora do caminho de revisão.
Sistema de arquivos	Raiz do espaço de trabalho, arquivos montados, caminhos ignorados, diretórios de saída	Previne acesso amplo a arquivos do host, credenciais, caches e projetos não relacionados.
Execução de shell	Comandos permitidos, diretório de trabalho, tempo limite, captura de saída, portões de aprovação	Dá ao agente poder suficiente para construir e testar, limitando ações de alto risco.
Instalações de pacotes	Política de registro, arquivos de bloqueio, versões fixadas, estratégia de cache, logs de instalação	Reduz a ambiguidade na cadeia de suprimentos quando o agente solicita novas dependências.
Acesso à rede	Egresso padrão, listas de permissão, comportamento DNS, destinos de API, mirrors de pacotes	Ajuda a prevenir movimentação não intencional de dados e torna as chamadas externas revisáveis.
Segredos	Credenciais com escopo, tokens de curta duração, redação, sem chaves de produção padrão	Impede que o agente leia ou vaze credenciais que não precisa.
Artefatos	Relatórios de teste, saídas de build, capturas de tela, arquivos gerados, logs	Fornece evidências aos revisores sem depender apenas do resumo do agente.
Ciclo de vida	Pausar, retomar, instantâneo, redefinir, limpar, política de retenção	Torna as execuções do agente repetíveis e descartáveis, em vez de máquinas misteriosas de longa duração.

Use esta tabela como uma lista de verificação de projeto. Ela se aplica independentemente de seu sandbox ser construído em contêineres, máquinas virtuais, microVMs, sandboxes gerenciados em nuvem ou um runner interno. A camada exata de isolamento importa, mas os controles operacionais em torno da camada também importam.

Fluxo de trabalho de referência para executar código gerado por agente

O fluxo de trabalho mais seguro para agentes de codificação se parece menos com um chatbot e mais com um pipeline de pull request controlado.

1. Crie um espaço de trabalho novo para a tarefa.
2. Faça checkout do repositório alvo em uma branch ou commit específico.
3. Dê ao agente uma tarefa estreita, comando de teste e escopo de arquivo.
4. Deixe o agente inspecionar arquivos e propor um plano.
5. Execute comandos de baixo risco e somente leitura automaticamente.
6. Exija aprovação ou verificações de política para comandos arriscados.
7. Capture cada comando, código de saída, stdout, stderr, escrita de arquivo e artefato gerado.
8. Execute testes, verificações de tipo, linters, builds ou scripts direcionados dentro do sandbox.
9. Exporte um patch, diff, saída de teste e pacote de artefatos.
10. Redefina ou destrua o espaço de trabalho após a revisão, a menos que um instantâneo seja intencionalmente salvo.

O detalhe importante é que o sandbox não é apenas um lugar para executar código. Ele também é o gravador de evidências. Um revisor deve ser capaz de responder: qual repositório foi verificado, o que mudou, quais comandos foram executados, o que falhou, o que passou, quais arquivos foram produzidos e quais recursos externos foram contatados.

Para agentes simples, isso pode ser implementado como uma fila de ações com verificações de política em torno de cada ação. Para agentes mais capazes, mantenha os mesmos limites, mas torne o plano de controle mais explícito: um componente decide o que o agente pode solicitar, um componente executa ações aprovadas e um componente registra a execução.

tarefa do usuário
  -> agente propõe leituras de arquivo, edições e comandos
  -> camada de política classifica cada ação
  -> sandbox executa ações aprovadas
  -> logs, diffs e artefatos são capturados
  -> humano revisa o patch antes de merge ou implantação

Essa separação impede que o modelo seja tanto o planejador quanto a autoridade final sobre operações perigosas.

Pontos de verificação de segurança antes da execução de comandos

Comece com a suposição de que comandos gerados podem estar errados, excessivamente amplos ou influenciados pelo conteúdo do repositório. Um agente de codificação pode ler uma instrução maliciosa de um fixture de teste, README, corpo de issue, script de pacote ou página web. O sandbox deve tornar essas falhas visíveis e contidas.

Antes da execução do shell, defina classes de comando:

Classe de comando	Exemplos	Política padrão
Inspeção somente leitura	pwd, ls, git status, rg, cat package.json	Geralmente permitir e registrar.
Verificação local	npm test, pytest, go test, cargo test	Permitir com tempo limite e captura de saída.
Build ou geração	npm run build, geração de código, geração de documentação	Permitir quando os caminhos de saída são esperados.
Alterações de dependência	instalação de gerenciador de pacotes, atualização de lockfile	Exigir verificações de política ou aprovação.
Comandos de rede	buscar URLs, chamar APIs, clonar repositórios extras	Exigir política de destino e registro.
Comandos destrutivos	deletar, reset forçado, limpeza de disco, chmod/chown amplo	Bloquear ou exigir aprovação humana explícita.
Acesso a segredos	ler arquivos env, armazenamentos de credenciais, configs de implantação	Bloquear a menos que seja específico da tarefa e com escopo.

Isso não requer um analisador estático perfeito. Mesmo controles simples ajudam: restrições de diretório de trabalho, padrões de negação explícitos, timeouts de comando, limites de tamanho de saída e um prompt de aprovação para comandos que alteram dependências, tocam em credenciais ou contatam hosts externos.

Os limites do sistema de arquivos devem ser igualmente concretos. Monte apenas o repositório e os diretórios temporários de que o agente precisa. Evite montar o diretório home do operador, chaves SSH, config de nuvem, credenciais de gerenciador de pacotes, perfis de navegador ou arquivos de ambiente de produção. Se caches forem necessários para velocidade, prefira caches somente leitura ou com escopo de tarefa e retenção clara.

Como lidar com instalações de pacotes e acesso à rede

A instalação de pacotes é uma das partes mais difíceis do sandboxing de agentes de codificação porque é útil e arriscada. Os agentes precisam reproduzir builds e executar testes, mas scripts de instalação podem executar código, puxar dependências transitivas e contatar infraestrutura externa.

Use uma política mais rigorosa para trabalho com pacotes:

• Prefira instalações baseadas em lockfile em vez de resolução de dependência livre.
• Registre o comando do gerenciador de pacotes, URL do registro, nomes de pacotes, versões e alterações de lockfile.
• Roteie downloads de dependências através de registros ou mirrors aprovados quando possível.
• Trate novas adições de dependência como alterações de código que exigem revisão.
• Bloqueie scripts de instalação para fluxos de trabalho de alto risco, a menos que o projeto os exija explicitamente.
• Mantenha caches de dependência separados de segredos e repositórios não relacionados.

A saída de rede merece o mesmo tratamento. Um agente de codificação pode precisar de acesso à internet para registros de pacotes, documentação de API, verificações de navegador ou testes de integração. Isso não significa que precisa de acesso de saída irrestrito.

No mínimo, defina o padrão:

Pergunta de rede	Padrão mais seguro
O sandbox pode alcançar a internet?	Não, a menos que a tarefa exija.
Pode resolver nomes DNS arbitrários?	Restringir ou registrar DNS e hosts de destino.
Pode chamar APIs de produção?	Usar endpoints de staging ou serviços mock por padrão.
Pode buscar dependências de pacotes?	Usar registros, mirrors e lockfiles aprovados.
Pode enviar arquivos ou logs?	Bloquear, a menos que o destino seja esperado e revisado.

Não descreva esses controles como uma garantia de que exfiltração ou comprometimento de dependência não pode acontecer. A afirmação realista é mais restrita: política, isolamento, registro e revisão reduzem o raio de explosão e tornam o comportamento arriscado mais fácil de detectar antes que o patch seja confiável.

Diffs, artefatos e logs para revisão humana

A revisão humana é mais eficaz quando o sandbox produz um pacote de revisão compacto, não uma longa transcrição de chat.

Para cada execução, capture:

• A URL do repositório, branch e commit SHA usados para checkout.
• O prompt da tarefa ou resumo da issue.
• Arquivos lidos e arquivos escritos.
• Cada comando, diretório de trabalho, hora de início, hora de fim, código de saída, stdout e stderr.
• Comandos de instalação de dependência e alterações de lockfile.
• Resultados de teste, lint, verificação de tipo e build.
• Artefatos gerados, como capturas de tela, relatórios, cobertura, binários ou URLs de pré-visualização.
• Diff final em formato de patch ou pull request padrão.

O revisor deve inspecionar o diff primeiro, depois usar logs e artefatos para responder perguntas direcionadas. Os testes realmente foram executados? O agente modificou arquivos fora do escopo solicitado? Ele adicionou uma dependência? Ele reescreveu arquivos gerados? Ele chamou um serviço de rede? Ele deixou artefatos grandes ou sensíveis?

Para equipes de produção, torne o portão de revisão explícito:

• O agente pode propor um patch.
• O sandbox pode executar a verificação.
• O sistema pode abrir um pull request.
• Um humano ou política aprovada deve decidir se deve fazer merge, implantar ou conceder permissões mais amplas.

Esse limite é especialmente importante para repositórios que incluem caminhos de infraestrutura, faturamento, autenticação, implantação ou dados do cliente.

Onde o Novita Agent Sandbox se encaixa

O Novita Agent Sandbox é projetado para ambientes de execução isolados e com estado onde agentes podem executar código, instalar dependências, acessar arquivos, usar fluxos de trabalho de navegador e preservar o estado de execução entre sessões. A visão geral do Agent Sandbox descreve três blocos de construção principais: sandboxes para execução isolada de tarefas, templates para ambientes preparados e snapshots para reutilização de estado configurado.

Para fluxos de trabalho de agentes de codificação, esses primitivos mapeiam naturalmente para um espaço de trabalho de desenvolvimento controlado:

Necessidade do agente de codificação	Padrão de sandbox
Começar de um ambiente conhecido	Usar um template com o tempo de execução e ferramentas esperados.
Executar comandos e testes longe do host	Executar dentro de um sistema de arquivos e ambiente de tempo de execução específicos do sandbox.
Reutilizar uma configuração preparada	Salvar um snapshot após instalar dependências aprovadas ou ferramentas do projeto.
Depurar trabalho de agente de longa duração	Preservar o estado entre sessões quando o fluxo de trabalho precisa de continuidade.
Limpar após a revisão	Redefinir, parar ou descartar o sandbox de acordo com sua política de retenção.

Mantenha o uso do produto e a política de segurança separados. O Novita Agent Sandbox pode fornecer o ambiente de execução isolado para agentes que executam código, mas sua aplicação ainda precisa definir acesso ao repositório, política de comando, escopo de segredo, regras de rede, retenção de artefatos e portões de aprovação humana. Essas escolhas dependem do seu modelo de ameaça e devem ser revisadas por seus responsáveis de engenharia e segurança antes do uso em produção pública.

Desenvolvedores que desejam um exemplo prático também podem ler o guia da Novita para construir um servidor MCP de execução remota de código com Novita Sandbox. Para documentação do produto, comece com a documentação do Novita Agent Sandbox e o guia de instalação do SDK e CLI.

FAQ

Um sandbox de agente de codificação é suficiente para tornar o código gerado seguro?

Não. Um sandbox é uma camada de controle. Você ainda precisa de acesso ao repositório com escopo, política de comando, controles de dependência, restrições de rede, tratamento de segredos, logs, revisão de artefatos e aprovação humana antes de merge ou implantação.

Agentes de codificação devem ter acesso à internet?

Apenas quando a tarefa exigir. Muitos fluxos de trabalho de revisão de código, refatoração e teste podem ser executados sem acesso geral à internet após as dependências serem preparadas. Quando o acesso à internet for necessário, registre os destinos e prefira registros de pacotes, sites de documentação, APIs de staging ou mocks permitidos.

Agentes devem receber segredos de produção?

Evite dar segredos de produção a agentes de codificação por padrão. Use credenciais com escopo e de curta duração para a tarefa específica, prefira serviços de staging, redija logs e mantenha o acesso a segredos fora do espaço de trabalho do repositório, a menos que haja um motivo revisado.

O que deve ser revisado antes de confiar em um patch de agente?

Revise o diff, as dependências alteradas, os arquivos gerados, o log de comandos, os resultados de teste, a atividade de rede e quaisquer artefatos. Preste atenção extra a alterações em autenticação, autorização, implantação, faturamento, infraestrutura, acesso a dados e gerenciamento de pacotes.

Quando um sandbox deve ser redefinido?

Redefina ou destrua o espaço de trabalho após cada tarefa, a menos que você salve intencionalmente um snapshot. O estado persistente é útil para fluxos de trabalho de longa duração, mas deve ser uma escolha deliberada com regras de propriedade, retenção e limpeza.

Artigos recomendados

• Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library
• Building a Coding Agent with Novita’s Agent Sandbox
• Novita Agent Runtime: AgentCore-Compatible AI Agent Infrastructure