Melhores práticas de sandbox para Claude Code em execuções headless

As melhores práticas de sandbox para Claude Code começam com uma regra: se o Claude Code puder editar arquivos e executar comandos sem que um humano aprove cada etapa, ele deve ser executado dentro de um workspace isolado, e não em um laptop ou em um runner de CI compartilhado. Isso é ainda mais importante no modo headless, porque o objetivo de uma execução headless é que o agente possa continuar avançando por edições de arquivos, comandos de shell e instalações de dependências sem esperar que uma pessoa clique em “permitir”. O guia de sandbox para Claude Code da Novita é a fonte de verdade para os comandos e flags exatos do template. Este artigo foca na parte que as equipes geralmente precisam em seguida: por que usar sandbox com Claude Code em primeiro lugar, o que pode dar errado se você não usar, e quais controles de produção adicionar ao template antes de conectá-lo a um fluxo de trabalho real.

Por que o Claude Code precisa de um sandbox no modo headless

O Claude Code é útil porque faz mais do que apenas rascunhar código. Ele lê arquivos, edita arquivos, executa comandos de shell e itera após ver a saída dos testes. Essa mesma capacidade é o motivo pelo qual ele precisa de um sandbox quando você passa de uma sessão interativa de desenvolvimento para automação não supervisionada.

Em um terminal local, um humano normalmente percebe ideias ruins cedo. Você vê o repositório que abriu. Você nota quando um comando alcança o diretório errado. Você pode interromper uma instalação que pareça suspeita. Em um fluxo de trabalho headless, esses pontos de verificação naturais desaparecem. O agente vê apenas as instruções e o ambiente que você forneceu.

Por isso, a comparação correta não é “Claude Code vs. sem Claude Code”. É “Claude Code em uma máquina real” vs. “Claude Code dentro de um limite de execução isolado”. Quando o agente pode agir de forma autônoma, o workspace passa a fazer parte do modelo de segurança.

A superfície de risco é bastante concreta:

Área de risco	O que pode dar errado sem um sandbox	O que um sandbox muda
Escopo do repositório	O agente edita o repositório, branch ou arquivos locais não rastreados errados	Cada tarefa recebe um checkout com escopo, commit base conhecido e branch descartável
Execução de shell	Comandos são executados contra a máquina host ou runner compartilhado	Os comandos permanecem dentro de um limite isolado de filesystem e processos
Instalações de dependências	Instalações de pacotes npm, pip ou outras executam scripts arbitrários no host	As instalações de pacotes ocorrem em um ambiente descartável com política e logs
Segredos	Variáveis de ambiente visíveis ao agente podem incluir credenciais amplas de desenvolvimento ou produção	Segredos com escopo de tarefa podem ser limitados à sessão do sandbox
Revisão	O único registro é um resumo do chat ou transcrição do terminal	Diff, logs, stdout, stderr e artefatos podem ser capturados para revisão

Se você quiser uma checklist de design de sandbox mais ampla que não seja específica do Claude, leia Sandbox para Coding Agents: Como Executar Código Gerado por Agentes com Segurança e Execute Claude Code ou Managed Agents em um Sandbox Isolado. A diferença aqui é que o Claude Code já tem um fluxo de trabalho CLI concreto, então a questão de infraestrutura se torna mais específica: como executar essa CLI com segurança quando não há uma pessoa no circuito?

O que muda quando você usa --dangerously-skip-permissions

Essa flag é o motivo pelo qual muitas equipes começam a fazer perguntas sobre sandbox. No uso interativo normal, o Claude Code pode perguntar antes de editar arquivos ou executar ferramentas. Na automação não supervisionada, os prompts de aprovação interrompem o fluxo, então a documentação da Novita mostra o padrão headless com claude --dangerously-skip-permissions -p "<prompt>" dentro do template claude-code.

Isso não significa que a flag seja insegura por definição. Significa que a camada de segurança mudou de lugar.

Quando você usa --dangerously-skip-permissions, você deve presumir:

• O Claude Code pode editar arquivos imediatamente.
• O Claude Code pode executar comandos imediatamente.
• O Claude Code pode continuar uma tarefa de várias etapas sem pausar para revisão.

A resposta correta não é usar a flag em uma estação de trabalho real e torcer para o melhor. A resposta correta é usá-la apenas dentro de um sandbox onde o workspace, o repositório, os comandos, os segredos e a superfície de rede já estejam restritos. O limite do sandbox se torna o lugar onde você reduz o raio de explosão.

É também por isso que você deve manter o texto preciso ao documentar essa configuração. --dangerously-skip-permissions não é uma recomendação para conveniência em máquina local. É um padrão operacional exclusivo de sandbox para automação headless. Se o seu fluxo de trabalho ainda aponta o Claude Code para um laptop de desenvolvedor, bastion compartilhado ou runner semelhante a produção, você removeu o prompt de aprovação humano sem adicionar o controle de infraestrutura que deveria substituí-lo.

Se a sua equipe ainda está decidindo se pode confiar em instalações de pacotes nesse ambiente, combine este artigo com Como Permitir com Segurança Instalações de Pacotes em Sandboxes de Agentes de IA e Checklist de Limites de Isolamento para Sandbox de Agentes de IA.

Como o template claude-code da Novita se mapeia para um fluxo de trabalho de produção

A parte útil da documentação da Novita é que ela não fica abstrata. Ela mostra a mecânica real que um fluxo de trabalho de produção precisa.

1. Modo headless -p e --print

A documentação usa o Claude Code em modo -p não interativo, para que a execução possa aceitar um prompt, imprimir o resultado e sair. Isso é importante porque a automação headless precisa de um contrato programático limpo. Você não quer um terminal interativo de longa duração preso a uma sessão humana; você quer uma execução orientada a tarefas que possa ser iniciada, observada e encerrada.

Essa é a mesma divisão discutida em Documentação CLI do Claude Code: o Claude Code interativo é para um condutor humano, enquanto -p com saída estruturada é o que torna a CLI útil em scripts e pipelines de agentes.

2. Roteamento de modelo personalizado via ~/.claude/settings.json

A documentação da Novita também mostra um detalhe prático que muitas equipes perdem: escrever ~/.claude/settings.json dentro do sandbox para que o Claude Code receba seu token de API, base URL e configuração do modelo por meio do bloco env. Esse padrão é importante por dois motivos.

Primeiro, ele mantém o runtime autocontido. O sandbox pode iniciar com a configuração exata voltada para o Claude que a tarefa precisa, em vez de herdar o que estiver presente na máquina do desenvolvedor.

Segundo, ele suporta controle explícito de ambiente. Se o seu fluxo de trabalho usa Claude Code com um backend personalizado, a configuração do sandbox passa a fazer parte da configuração revisada, em vez de um estado de shell pessoal oculto.

3. Clonagem real de repositório com credenciais com escopo

A documentação mostra sandbox.git.clone(...) com um caminho de destino, profundidade de clone shallow e token do GitHub para repositórios privados. Esse não é um recurso de conveniência menor. É a diferença entre um workspace de tarefa reproduzível e um agente trabalhando em um diretório ambíguo.

Para uso em produção, o padrão mais seguro é:

1. Clone apenas o repositório necessário para a tarefa.
2. Fixe a ref ou commit inicial quando o seu fluxo de trabalho exigir reprodutibilidade.
3. Use uma branch de tarefa para as alterações do agente.
4. Passe credenciais Git com escopo que possam ler ou escrever apenas o que a tarefa precisa.

Se um repositório ainda não precisa de acesso de escrita, não dê acesso de escrita apenas porque o agente pode eventualmente abrir um PR.

4. Saída estruturada mais session_id para trabalho em várias etapas

A documentação mostra um segundo padrão útil: iniciar o Claude Code com --output-format json, analisar o session_id retornado e continuar com --resume <session_id>. É isso que transforma uma edição de código única em um fluxo de trabalho em várias etapas que você pode gerenciar programaticamente.

Isso é adequado para tarefas como:

• Etapa 1: inspecionar o repositório e produzir um plano de refatoração
• Etapa 2: retomar a mesma sessão e implementar uma parte
• Etapa 3: retomar novamente para executar verificação ou limpeza de acompanhamento

A melhor prática importante não é “sempre usar resume”. É “retomar intencionalmente”. Se o seu fluxo de trabalho se beneficia da continuidade, retome a mesma sessão no mesmo sandbox. Se a tarefa deve ser revisável de forma independente, inicie um sandbox novo em vez de carregar estado implicitamente.

5. Encerre o workspace após a tarefa

A documentação da Novita termina os exemplos encerrando o sandbox. Esse é exatamente o hábito que você quer em produção. Um agente de codificação headless não deve acumular silenciosamente workspaces obsoletos, processos em segundo plano ou credenciais remanescentes. Um ambiente descartável é mais fácil de entender do que uma máquina misteriosa com histórico.

Se você quiser uma visão arquitetural mais ampla desse modelo de runtime, Construindo um Coding Agent com o Agent Sandbox da Novita é a leitura complementar certa.

Checklist de melhores práticas de sandbox para Claude Code

A checklist a seguir é a versão de produção do fluxo de trabalho da documentação. Ela mantém a mecânica exata do template da Novita e adiciona os controles que um pipeline automatizado geralmente precisa.

• Um sandbox por tarefa: Não aponte várias tarefas não relacionadas para um ambiente Claude Code de longa duração. Workspaces novos tornam o estado inicial do repositório óbvio e facilitam o encerramento.
• Acesso Git com escopo: Se o Claude Code só precisa clonar e inspecionar um repositório, use um token somente leitura. Se ele precisar enviar uma branch, use um token com escopo para esse repositório e esse fluxo de trabalho. Evite credenciais pessoais herdadas.
• Instalações de pacotes no sandbox: O Claude Code muitas vezes precisa de dependências para reproduzir uma build ou teste com falha. Isso é aceitável, mas as instalações devem ocorrer dentro do sandbox com logs e política, não na máquina do operador. Revise alterações no lockfile como qualquer outra alteração de código.
• Trate a saída do shell como evidência: Capture stdout, stderr, códigos de saída e os comandos que realmente foram executados. Um resumo final do agente é útil, mas não é suficiente para revisão por si só.
• Sem segredos de produção por padrão: Prefira credenciais de curta duração ou apenas de staging. Um agente de codificação que pode ler o repositório e executar comandos não precisa de tokens amplos de administrador da nuvem ou credenciais de banco de dados de produção por padrão.
• Revise o diff, não apenas o resultado: O sucesso headless significa apenas que o Claude Code concluiu o loop que você forneceu. Não significa que a alteração está correta ou pronta para envio. Revise os arquivos alterados, mudanças de dependências, saída de comandos e quaisquer artefatos gerados.
• Mantenha --dangerously-skip-permissions local ao sandbox: Esta é a regra operacional mais importante na configuração. A flag pertence a um workspace isolado e descartável. Ela não deve ser seu atalho para executar Claude Code não supervisionado em uma máquina real.
• Separe execução de release: O Claude Code pode ter permissão para inspecionar, editar, testar e preparar um patch. Isso não significa que ele também deva ser dono das decisões de merge, publicação ou deploy. Mantenha essas ações atrás de um humano ou de um controle de política explícito.
• Retome intencionalmente: Use --resume <session_id> quando a tarefa realmente se beneficiar da continuidade. Reinicie o sandbox quando precisar de um teste limpo de reprodutibilidade ou quando uma tarefa não deve herdar o estado de outra.
• Compare toda a superfície do provedor: Se você está escolhendo onde hospedar esse fluxo de trabalho, olhe além de saber se o ambiente pode iniciar o Claude Code. Compare o ciclo de vida da sessão, a ergonomia do repositório, logs, comportamento de pausa e retomada e tradeoffs operacionais. Para esse ângulo, E2B vs. Daytona: Comparação de Sandbox para Agentes de IA e Novita Sandbox: uma alternativa econômica ao E2B Pro com compatibilidade perfeita são as leituras comparativas relevantes.

Erros comuns a evitar

Os erros mais comuns com sandbox do Claude Code são operacionais, não conceituais.

Erro 1: Tratar o exemplo da documentação como uma política de produção completa

A documentação mostra como iniciar o template claude-code corretamente. Ela não tenta ser sua política completa de revisão, rede ou gerenciamento de segredos. Use-a para a sintaxe e mecânica de runtime e depois adicione seus próprios limites de repositório e aprovação.

Erro 2: Reutilizar uma estação de trabalho de desenvolvedor como “sandbox”

Executar o Claude Code a partir de um terminal no seu laptop é um fluxo de trabalho de desenvolvedor válido. Não é a mesma coisa que um runtime descartável e isolado para automação não supervisionada.

Erro 3: Deixar o estado da sessão implícito

Se você usa --resume, saiba qual estado está carregando adiante e por quê. Se a resposta for “não temos certeza, mas foi conveniente”, você está criando um problema de revisão mais difícil.

Erro 4: Misturar segredos reais com trabalho exploratório de código

Um sandbox existe para reduzir o raio de explosão. Se o workspace ainda pode alcançar sistemas de produção com credenciais amplas, você enfraqueceu o limite mais importante.

Erro 5: Confiar mais em uma execução bem-sucedida do que nas evidências

Um agente pode concluir uma tarefa e ainda assim fazer a alteração errada, tocar nos arquivos errados ou adicionar uma dependência que você não queria. Revise o diff e os logs, não apenas o resumo narrativo.

FAQ

--dangerously-skip-permissions significa que o Claude Code não tem nenhuma segurança?

Significa que o Claude Code não está mais esperando aprovações interativas dentro da sessão. A camada de segurança pretendida em um fluxo de trabalho headless é o limite do sandbox ao redor da sessão: repositório isolado, credenciais limitadas, execução de comandos dentro do sandbox, logs capturados e revisão humana antes do merge.

Toda automação do Claude Code deve ser executada em um sandbox novo?

Sandboxes novos são o padrão mais limpo para tarefas independentes. Fluxos de trabalho baseados em resume são úteis quando a mesma tarefa em várias etapas precisa de continuidade, mas o estado deve ser deliberado e revisável, não acidental.

O Claude Code pode instalar pacotes com segurança em um sandbox?

Pode se tornar mais seguro, mas não é automaticamente seguro. Use política de pacotes, revisão do lockfile, acesso de rede com escopo e logs de auditoria. As instalações de pacotes são uma das etapas de maior risco em um fluxo de trabalho de codificação não supervisionado.

A página de documentação da Novita é suficiente para implementar o fluxo de trabalho?

É suficiente para a sintaxe do template publicado e a mecânica suportada do Claude Code: execuções headless, configuração de settings.json, sandbox.git.clone, saída JSON e retomada de sessão. Para o rollout em produção, você ainda precisa das suas próprias decisões de revisão, credenciais e política em torno desse runtime.

Artigos recomendados

• Execute Claude Code ou Managed Agents em um Sandbox Isolado
• Sandbox para Coding Agents: Como executar código gerado por agentes com segurança
• Construindo um Coding Agent com o Agent Sandbox da Novita