Executar Claude Code ou Agentes Gerenciados em um Sandbox Isolado

Execute agentes de codificação no estilo Claude Code ou gerenciados em um sandbox, atribuindo a cada agente um espaço de trabalho com escopo definido, permissões explícitas de arquivos, execução de shell controlada, uma política de rede e pacotes, limites claros de segredos, logs duráveis, artefatos capturados e revisão humana antes de mesclar ou enviar as alterações. O agente ainda pode ler código, editar arquivos, instalar dependências, executar testes e produzir um patch, mas o ambiente ao redor decide o que ele pode tocar, o que pode buscar, quais credenciais pode ver e quando uma pessoa deve aprovar o próximo passo.

O que precisa ser isolado

Um agente de codificação não é apenas um chatbot anexado a um repositório. Uma vez que ele pode editar arquivos e executar comandos, passa a se parecer com um worker de build júnior com raciocínio de modelo de linguagem no loop. Esse worker pode executar npm test, inspecionar arquivos gerados, iniciar um servidor de desenvolvimento ou tentar instalar um pacote porque uma mensagem de erro sugere isso. Se o espaço de trabalho for seu laptop, um runner de CI compartilhado ou uma VM de produção de longa duração, o raio de explosão é muito amplo.

O alvo de isolamento é todo o loop de trabalho do agente:

• O checkout do repositório e o branch que o agente pode ler ou modificar.
• Os caminhos do sistema de arquivos que o agente pode escrever.
• Os comandos que ele pode executar automaticamente.
• Os comandos que exigem aprovação.
• Os registros de pacotes, domínios e APIs que ele pode alcançar.
• As credenciais expostas à sessão.
• Os logs, diffs, saídas de teste, capturas de tela e artefatos preservados para revisão.
• O comportamento de limpeza após sucesso, falha ou timeout.

Claude Code e outros produtos de agentes de codificação gerenciados podem incluir seus próprios sistemas de permissão. A documentação do Claude Code da Anthropic, por exemplo, descreve configurações de permissão para ferramentas permitidas e negadas, comportamento de aprovação e orientações de sandbox para uso local. Trate esses controles como uma camada, não como o limite completo. Um design mais robusto coloca o agente dentro de um runtime isolado e, em seguida, aplica permissões de ferramentas dentro desse runtime.

Arquitetura de referência

Um fluxo de trabalho prático de agente em sandbox possui quatro camadas:

Camada	Propósito	Controle típico
Controlador do agente	Decide o plano de tarefa e as chamadas de ferramenta	Permissões de modelo/ferramenta, modo de aprovação, prompt da tarefa
Runtime do sandbox	Hospeda o espaço de trabalho onde os comandos são executados	Sistema de arquivos isolado, limites de processo, controles de ciclo de vida
Gateway de políticas	Decide quais ações são permitidas	Regras de comando, regras de egresso de rede, política de pacotes, escopo de segredos
Superfície de revisão	Permite que humanos inspecionem os resultados	Diff, logs, resultados de teste, artefatos, pull request

Mantenha essas camadas separadas. Se o controlador do agente for comprometido por injeção de prompt, o runtime do sandbox e o gateway de políticas ainda devem limitar o que acontece. Se uma instalação de pacote puxar código inesperado, os logs de rede e artefatos devem tornar isso visível. Se o agente produzir um patch plausível, a superfície de revisão deve mostrar exatamente o que mudou e quais testes foram executados.

Um objeto de política conceitual pode ser assim:

workspace:
  mode: ephemeral
  repo_ref: pull-request-branch
  writable_paths:
    - /workspace/project
  readonly_paths:
    - /workspace/reference
commands:
  auto_allow:
    - git status
    - npm test
    - npm run lint
    - pytest
  require_approval:
    - npm install
    - pip install
    - docker build
    - git push
  deny:
    - rm -rf /
    - curl ... | sh
network:
  default: deny
  allow:
    - registry.npmjs.org
    - pypi.org
    - files.pythonhosted.org
secrets:
  expose:
    - READ_ONLY_PACKAGE_TOKEN
  deny:
    - PRODUCTION_DATABASE_URL
    - CLOUD_ADMIN_TOKEN
artifacts:
  capture:
    - git diff
    - test-results/
    - screenshots/
    - command-log.jsonl

Isso não é intencionalmente um exemplo de SDK. O formato exato da política depende do seu framework de agente e provedor de sandbox. O ponto importante é que as permissões devem ser expressas fora do raciocínio livre do modelo e, em seguida, aplicadas pelo runtime ou pela camada de orquestração.

Configuração do espaço de trabalho e repositório

Comece cada execução de agente a partir de um espaço de trabalho limpo. Um agente gerenciado não deve herdar o histórico de shell, agente SSH, dotfiles, login de CLI na nuvem ou arquivos locais não rastreados de um desenvolvedor, a menos que haja um motivo deliberado.

Para trabalhos com repositórios, use um checkout dedicado:

• Clone ou monte apenas o repositório necessário para a tarefa.
• Faça checkout de um novo branch de tarefa em vez de editar o branch padrão.
• Fixe o commit base para que a revisão possa reproduzir o ponto de partida.
• Mantenha caches de dependências separados dos caminhos de código-fonte graváveis.
• Armazene artefatos gerados fora da árvore de origem, a menos que façam parte do diff pretendido.

O isolamento de branch é importante porque agentes de codificação frequentemente tentam várias abordagens antes de decidir por uma. Um branch de tarefa limpo oferece aos revisores um diff de pull request normal, em vez de um espaço de trabalho misto contendo experimentos temporários. Se o agente precisar comparar com uma implementação de referência, monte essa referência como somente leitura.

Para agentes gerenciados de longa duração, decida se o sandbox é efêmero, pausado ou snapshotado. Espaços de trabalho efêmeros são mais fáceis de raciocinar. Snapshots e pausa/retomada são úteis para trabalhos longos, sessões de navegador e etapas de configuração caras, mas ainda devem preservar uma trilha de auditoria clara: quando o snapshot foi criado, quais arquivos estavam presentes e quais credenciais estavam disponíveis.

Permissões do sistema de arquivos

O escopo do sistema de arquivos deve ser mais restrito do que “o agente pode ler a máquina inteira”. A maioria das tarefas de codificação precisa de:

• Acesso de leitura/escrita ao espaço de trabalho do repositório.
• Acesso somente leitura a itens de contexto selecionados, fixtures ou documentação.
• Um diretório temporário para saída de build e arquivos temporários.
• Nenhum acesso a diretórios home do host, repositórios não relacionados, credenciais de nuvem, perfis de navegador ou despejos de dados de produção.

Permissões de escrita merecem cuidado especial. Um agente de codificação que pode editar um repositório também pode editar scripts, testes, lockfiles, configuração de CI e arquivos de implantação. Isso pode ser exatamente o que a tarefa exige, mas deve ser visível na revisão. Para caminhos sensíveis, como .github/workflows/, manifestos de implantação ou configuração de publicação de pacotes, exija uma etapa de aprovação mais forte ou uma revisão final de propriedade humana.

Use listas de permissão de arquivos quando a tarefa for estreita. Por exemplo, um agente de documentação pode precisar apenas de docs/ e um diretório de pré-visualização gerado. Um agente de atualização de dependências pode precisar de package.json, lockfiles e snapshots de teste. Uma refatoração ampla precisa de acesso mais amplo, mas a revisão deve então esperar um diff maior e testes mais completos.

Política de execução de shell

O acesso ao shell é onde os agentes de codificação se tornam úteis e arriscados. Eles precisam de execução de comandos para executar testes, formatar código, inspecionar erros de build e verificar correções. Eles não precisam de autoridade irrestrita para executar qualquer comando sem pausa.

Uma boa política de shell tem três categorias:

Categoria	Exemplos	Por que é importante
Permitido automaticamente	git status, npm test, pytest, go test ./..., npm run lint	Mantém loops normais de edição-teste rápidos
Requer aprovação	instalações de pacotes, migrações, serviços de longa duração, CLIs externas, git push	Adiciona atrito onde estado, custo ou risco de rede mudam
Negado	comandos destrutivos do host, dumping de credenciais, piping de shell inseguro, escritas fora do espaço de trabalho	Bloqueia ações que não devem ser delegadas

Não confie apenas na correspondência de texto do comando. Agentes podem executar comandos por meio de scripts, hooks do gerenciador de pacotes ou shells aninhados. Para ambientes de maior risco, combine a política de comandos com limites de sistema de arquivos em nível de runtime, limites de recursos e controles de rede.

Comandos de longa duração precisam de comportamento de timeout. Um servidor de teste, execução de automação de navegador ou watcher de build podem permanecer ativos depois que o agente avançou. Capture IDs de processo, stdout, stderr, status de saída, tempo de execução e motivo de terminação. Se um comando abrir uma porta de pré-visualização, registre o mapeamento de porta e desligue-o durante a limpeza.

Instalações de pacotes e egresso de rede

A instalação de pacotes é um dos recursos mais úteis de um espaço de trabalho de agente e um dos lugares mais fáceis para o risco entrar. Um agente de codificação pode instalar um pacote porque uma resposta do Stack Overflow, README ou plano gerado pelo modelo sugeriu. Isso pode alterar o gráfico de dependências, executar scripts de instalação e alcançar registros externos.

Para guias de implementação e fluxos de trabalho de produção, comece com uma postura de rede de negação padrão e, em seguida, permita o que a tarefa precisa:

• Registros de pacotes como npm ou PyPI, de preferência através de um espelho ou cache de registro.
• Hosts de origem necessários para o repositório e submódulos.
• Domínios de documentação necessários para a tarefa.
• APIs internas somente quando o sandbox tiver a classificação de dados correta.

Evite dar a cada agente acesso amplo à internet por padrão. Se acesso amplo for necessário para pesquisa ou automação de navegador, separe essa execução de execuções de modificação de código e rotule o artefato de acordo.

Para instalações de pacotes, registre:

• O comando do gerenciador de pacotes.
• O host do registro.
• Alterações no lockfile.
• Nomes e versões dos pacotes baixados, quando disponíveis.
• Quaisquer scripts de instalação que foram executados.
• Se um humano aprovou a instalação.

Isso não torna pacotes arbitrários seguros. Torna a alteração revisável.

Limites de segredos

Segredos devem ser escopo da tarefa, de curta duração e ausentes por padrão. O sandbox mais seguro não é aquele que promete que um modelo nunca revelará um segredo; é aquele onde o segredo não está presente, a menos que a tarefa realmente exija.

Use estes padrões:

• Nenhuma credencial de banco de dados de produção em espaços de trabalho de agente.
• Nenhum token de administração de nuvem.
• Nenhuma chave SSH pessoal ou credenciais de máquina do desenvolvedor.
• Credenciais somente leitura quando possível.
• Tokens separados para leitura de pacotes, fixtures de teste ou APIs exclusivas de staging.
• Redação em logs antes de compartilhar artefatos.

Se o agente precisar chamar um serviço externo, forneça um token restrito e registre qual ferramenta ou comando o usou. Evite colocar credenciais amplas em arquivos que o agente possa editar. Variáveis de ambiente são convenientes, mas ainda podem ser impressas por comandos, incluídas em logs ou copiadas em arquivos gerados. Trate-as como expostas ao processo do agente.

Logs, artefatos e trilhas de auditoria

A revisão humana só é útil quando os revisores podem ver o que aconteceu. Uma execução de agente de codificação em sandbox deve preservar mais do que o patch final.

Capture pelo menos:

• O prompt da tarefa ou resumo da instrução.
• O commit base e o branch.
• Arquivos lidos e escritos, quando sua ferramenta puder registrá-los.
• Comandos executados, com timestamps, diretório de trabalho, status de saída, stdout e stderr.
• Resumos de instalação de pacotes e acesso à rede.
• Resultados de teste e build.
• Arquivos gerados, capturas de tela, relatórios ou links de pré-visualização.
• O diff final.

Armazene logs em uma superfície de revisão que sobreviva ao sandbox. Se o sandbox for destruído imediatamente após a execução, as evidências ainda devem estar disponíveis no pull request, no armazenamento de artefatos de CI ou no registro da plataforma do agente.

Para equipes que usam agentes gerenciados, essa trilha de auditoria também ajuda a comparar o desempenho do agente. Você pode ver se as falhas vieram de dependências ausentes, um comando negado, um prompt pouco claro, testes instáveis ou um problema real de código.

Limpeza e reinicialização

A limpeza do sandbox é uma questão de segurança e controle de custos, não apenas de organização. Ao final de uma execução:

• Pare processos em segundo plano.
• Feche portas expostas.
• Revogue tokens de escopo da tarefa.
• Exporte artefatos necessários.
• Exclua arquivos temporários que não fazem parte da revisão.
• Destrua, pause ou faça snapshot do sandbox de acordo com o tipo de execução.

A reinicialização efêmera é o padrão mais limpo para trabalhos não confiáveis ou exploratórios. Para agentes de longa duração, faça snapshot apenas após uma etapa de configuração conhecida como boa, não após atividade arbitrária do agente. Se uma execução falhada precisar de investigação, preserve o sandbox ou snapshot com um prazo de expiração claro.

Onde o Novita Agent Sandbox se encaixa

Novita Agent Sandbox é projetado para fluxos de trabalho de execução de agentes de IA onde o código é executado dentro de espaços de trabalho em nuvem isolados, em vez de no laptop do desenvolvedor ou em um host compartilhado. A documentação do Sandbox da Novita descreve primitivas principais que mapeiam para o padrão neste guia: gerenciamento de ciclo de vida do sandbox, operações de sistema de arquivos, execução de comandos, modelos e gerenciamento de runtime para cargas de trabalho de agente.

Isso torna a Novita adequada para equipes que constroem fluxos de trabalho de agente de codificação, análise de dados, agente de navegador, avaliação ou agentes de longa duração que precisam de um ambiente de execução junto com APIs de modelo. Mantenha o limite claro, no entanto: este artigo é um padrão de implementação geral para agentes de codificação no estilo Claude Code e gerenciados. Não está reivindicando uma integração oficial com Claude Code, uma parceria ou compatibilidade universal com todos os produtos de agente gerenciado.

Se você está projetando um fluxo de trabalho baseado na Novita, use os documentos do produto para a superfície de API exata lançada e mantenha sua camada de política explícita. O sandbox pode fornecer o espaço de trabalho de execução isolado; seu aplicativo ainda deve decidir aprovações de comando, política de rede, escopo de segredos, retenção de artefatos e portões de revisão humana.

Lista de verificação de revisão de segurança

Use esta lista de verificação antes de permitir que um agente de codificação seja executado além de um repositório de brinquedo:

Pergunta	O que procurar
Qual é o limite de isolamento?	Espaço de trabalho dedicado, limites de processo, separação de sistema de arquivos e documentação clara do provedor
O que o agente pode ler?	Acesso apenas ao repositório por padrão, sem diretório home do host, sem repositórios não relacionados
O que o agente pode escrever?	Caminhos de origem graváveis são explícitos; caminhos de configuração sensíveis recebem revisão extra
Quais comandos são executados automaticamente?	Comandos de teste e formatação são permitidos; comandos que alteram estado exigem aprovação
Que acesso à rede existe?	Negação padrão ou egresso com escopo; registros de pacotes e domínios de documentação são intencionais
Como as instalações de pacotes são tratadas?	Alterações de lockfile, hosts de registro e scripts de instalação são registrados
Quais segredos estão presentes?	Credenciais de escopo da tarefa, curta duração e privilégio mínimo apenas
O que acontece com os logs?	Comandos, saídas, diffs e artefatos sobrevivem à limpeza do sandbox
Como a limpeza é aplicada?	Processos em segundo plano, portas, tokens e arquivos temporários são fechados ou revogados
Quem aprova a mesclagem ou o envio?	Um revisor humano verifica código, testes, arquivos sensíveis à segurança e artefatos gerados

A regra mais importante é simples: não confunda “o agente pediu permissão” com “o sistema impôs um limite”. O modelo pode ajudar a explicar o que deseja fazer. O runtime e a camada de política devem decidir o que ele tem permissão para fazer.

FAQ

É possível executar Claude Code em um sandbox?

Sim, desde que sua configuração coloque o agente no estilo Claude Code dentro de um espaço de trabalho com escopo e aplique políticas de sistema de arquivos, shell, rede, segredos, registro e revisão ao redor dele. Não presuma que um prompt de permissão local é suficiente para produção ou repositórios sensíveis.

Um contêiner é suficiente para isolamento de agente de codificação?

Às vezes, mas a resposta depende do seu modelo de ameaça. Contêineres podem ser úteis para builds repetíveis e separação de dependências, mas cargas de trabalho sensíveis à segurança devem avaliar o limite do kernel, montagens do host, padrões de rede, privilégios de runtime e documentação do provedor antes de tratar um contêiner como o limite completo do sandbox.

Os agentes devem ter permissão para instalar pacotes?

Eles podem, mas as instalações de pacotes devem ser tratadas como eventos controlados de cadeia de suprimentos. Prefira listas de permissão de registro ou espelhos, revisão de lockfile, registro de scripts de instalação e aprovação para novas dependências ou comandos que buscam e executam código remoto.

O que um revisor humano deve verificar antes da mesclagem?

Revise o diff final, comandos executados, testes executados, alterações de pacotes e lockfiles, arquivos de CI/implantação tocados, artefatos gerados e quaisquer ações negadas ou que exigiram aprovação. Para repositórios sensíveis à segurança, revise a própria política do sandbox como parte da alteração.

O Novita Agent Sandbox se integra oficialmente com Claude Code?

Este artigo não faz essa afirmação. O Novita Agent Sandbox fornece primitivas de execução isoladas para fluxos de trabalho de agente, enquanto Claude Code e produtos de agente gerenciado têm suas próprias interfaces e modelos de permissão específicos do produto. Valide o caminho exato de integração com a documentação atual do produto antes de publicar comandos executáveis.

Artigos recomendados

• Construindo um Agente de Codificação com o Agent Sandbox da Novita
• Execute Avaliações de Agente Harbor no Novita Agent Sandbox
• Como Usar o Codex com Modelos Novita AI