Execute o Codex ou um Agente de Codificação em um Sandbox Seguro

Execute um agente de codificação em um sandbox fornecendo a ele um espaço de trabalho de repositório com escopo definido, um caminho controlado de execução de terminal, permissões de arquivo explícitas, políticas de rede e instalação de pacotes, segredos isolados, logs de comandos, artefatos e um caminho claro de aprovação para alterações de alto risco antes da mesclagem ou implantação. Esse padrão funciona seja o agente estilo Codex, conectado a IDE, acionado por CI ou incorporado à sua própria plataforma de desenvolvedor: o modelo pode planejar e editar, mas o sandbox decide o que ele pode tocar, o que pode executar, o que pode buscar e quais evidências um revisor recebe.

O que é um sandbox para agente de codificação?

Um sandbox para agente de codificação é um ambiente de execução isolado onde um sistema de IA pode inspecionar código, editar arquivos, executar comandos de terminal, instalar dependências quando a política permitir, executar testes, iniciar servidores de pré-visualização e retornar um diff revisável sem obter acesso amplo à máquina do desenvolvedor ou ao ambiente de produção.

A mudança importante é que o sandbox não é apenas um invólucro de chat em torno de um modelo. Ele é o limite operacional para o trabalho. O modelo propõe ações; o sandbox impõe o espaço de trabalho, ferramentas, permissões e trilha de evidências.

Para um assistente de código simples, um checkout local e copiar-colar manual podem ser suficientes. Para um agente que pode executar comandos ou continuar por muitas etapas, você precisa de limites mais fortes:

• Um espaço de trabalho dedicado para cada tarefa ou sessão.
• Um estado e branch conhecidos do repositório.
• Uma interface de execução de comandos com aprovações para operações arriscadas.
• Uma política de instalação de pacotes para npm, pip, cargo, apt e ferramentas similares.
• Regras de egresso de rede para registros, documentações, APIs e acesso de pré-visualização.
• Segredos com escopo definido para a tarefa e ocultados dos logs sempre que possível.
• stdout, stderr, códigos de saída, alterações de arquivos, artefatos gerados e URLs de pré-visualização capturados.
• Um portão de revisão antes de mesclagem, implantação ou lançamento externo.

É por isso que “executar o Codex em um sandbox” deve ser entendido como um padrão de infraestrutura, não apenas um hábito local de CLI. O próprio Codex CLI é documentado como um agente de codificação que executa por meio de um fluxo de trabalho de terminal, e o ambiente de execução ao redor se torna o plano de controle quando você o opera para uma equipe, sistema de CI ou fluxo de trabalho de produto. O template de primeira parte Codex Agent da Novita agora torna esse padrão concreto dentro do Novita Sandbox, em vez de deixá-lo como uma possibilidade conceitual.

Arquitetura do sandbox para agente de codificação

A arquitetura mais limpa separa o loop do modelo do limite de execução:

Camada	Responsabilidade	Perguntas a responder
Interface do agente	Transforma a intenção do usuário em planos, edições de arquivos, chamadas de ferramentas e resumos de revisão	Qual modelo ou agente de codificação é usado? Como os prompts, o contexto e os esquemas de ferramentas são gerenciados?
Gerenciador de espaço de trabalho	Cria o sandbox, faz checkout do repositório, define o branch e monta os arquivos permitidos	Cada tarefa é isolada? O commit base é conhecido? O espaço de trabalho pode ser redefinido?
Executor de terminal	Executa comandos aprovados e transmite os resultados de volta ao agente	Quais comandos são permitidos automaticamente, exigem aprovação ou são bloqueados?
Camada de política	Controla o escopo do sistema de arquivos, segredos, egresso de rede, instalações de pacotes, limites de tempo de execução e limpeza	O agente pode buscar pacotes? Pode acessar a internet pública? Pode ler credenciais?
Camada de evidências	Armazena logs, diffs, resultados de testes, pré-visualizações e artefatos	Um revisor pode reconstruir o que aconteceu sem confiar no resumo do modelo?
Portão de revisão	Exige uma etapa humana ou de automação confiável antes de mesclagem, publicação ou implantação	Quem aprova alterações arriscadas? Quais verificações devem passar primeiro?

Na prática, uma única plataforma pode combinar várias dessas camadas. A arquitetura ainda importa porque mantém as escolhas de produto honestas. Se uma ferramenta dá a um agente um terminal, mas não consegue mostrar logs de comandos, diffs de arquivos ou política de egresso, pode ser conveniente para prototipagem, mas frágil para revisão em produção.

Como o acesso ao terminal deve funcionar em um sandbox para agente de codificação?

O terminal é onde um agente de codificação se torna operacionalmente útil e operacionalmente arriscado. Ele pode executar testes, compilar ativos, inspecionar arquivos gerados, iniciar servidores locais e diagnosticar falhas. Também pode excluir arquivos, vazar variáveis de ambiente, executar scripts de instalação inesperados ou consumir grandes recursos computacionais.

Um bom modelo de terminal tem três partes.

Primeiro, defina classes de comando. Comandos seguros somente leitura, como ls, sed, rg, git diff e comandos de status de teste, podem geralmente ser executados automaticamente. Comandos de compilação e teste, como npm test, pytest, cargo test e npm run build, podem ser permitidos com timeouts. Comandos destrutivos ou de impacto externo, como rm -rf, git push, gh pr merge, CLIs de implantação, publicação de pacotes, migração de banco de dados ou mutação de recursos em nuvem, devem exigir aprovação explícita ou ser totalmente bloqueados.

Segundo, transmita os resultados com estrutura. O agente e o revisor devem ver o comando, diretório de trabalho, hora de início, código de saída, stdout, stderr, estado de timeout e política de saída truncada. Uma captura de tela do terminal não é suficiente; o sistema deve preservar logs legíveis por máquina.

Terceiro, lide com sessões de longa duração deliberadamente. Agentes de codificação frequentemente precisam de um servidor de desenvolvimento em segundo plano, um watcher, um processo de automação de navegador ou uma pilha de testes de integração. Trate processos de longa duração como recursos com identificadores: inicie-os, transmita logs, exponha apenas a porta de pré-visualização necessária e pare-os durante a limpeza. Não deixe que um processo em segundo plano se torne um efeito colateral não rastreado de uma sessão de chat.

Isolamento de repositório e controle de branch para alterações do agente

O estado do repositório é a espinha dorsal de um fluxo de trabalho de agente de codificação revisável. O agente não deve trabalhar em uma pasta ambígua com edições locais desconhecidas, a menos que o usuário tenha escolhido explicitamente esse modo.

Para fluxos de trabalho em equipe, comece cada tarefa a partir de uma URL de repositório, branch base e SHA de commit conhecidos. Crie um branch de tarefa ou espaço de trabalho destacado. Mantenha as alterações do usuário separadas das alterações do agente e capture o diff exato antes da revisão. Se o sandbox suportar sessões persistentes, persista o espaço de trabalho intencionalmente; não dependa do estado acidental do processo.

O padrão padrão é assim:

1. Crie um espaço de trabalho isolado para task-123.
2. Faça checkout do repositório em main@<base_sha>.
3. Crie o branch agent/task-123.
4. Execute a instalação de dependências de acordo com a política.
5. Deixe o agente inspecionar, editar, testar e iterar.
6. Capture o git diff, a saída dos testes, os artefatos gerados e a URL de pré-visualização.
7. Abra um pull request ou entregue o patch a um revisor humano.
8. Destrua ou arquive o espaço de trabalho de acordo com a política de retenção.

O detalhe chave é o passo 6. Um agente de codificação útil não diz apenas “arrumei”. Ele retorna os arquivos alterados, por que cada alteração existe, qual validação foi executada, o que falhou e o que permanece não verificado.

Políticas de comando, pacote e rede para agentes de codificação em sandbox

Instalações de pacotes são uma das partes mais difíceis do sandbox de agentes de codificação. Muitas tarefas reais precisam de dependências. Muitos incidentes na cadeia de suprimentos também começam com a busca de dependências, scripts pós-instalação ou binários opacos.

Uma política prática não é “nunca instalar pacotes”. É “instalar pacotes apenas por caminhos conhecidos, com registro e escopo”.

Controle	Implementação prática
Gerenciadores de pacotes	Decida quais gerenciadores de pacotes estão disponíveis por idioma e tipo de repositório.
Acesso a registros	Permita registros aprovados; bloqueie fontes de pacotes arbitrárias quando a tarefa não precisar delas.
Lockfiles	Prefira lockfiles existentes e comandos de instalação reproduzíveis.
Scripts pós-instalação	Decida se scripts de ciclo de vida podem ser executados automaticamente ou exigem aprovação.
Pacotes do sistema	Trate instalações de pacotes do sistema (apt, brew) como de risco mais alto do que instalações de dependências de projeto.
Caches	Use caches de pacotes controlados quando precisar de velocidade e reprodutibilidade.
Registro	Armazene nomes de pacotes, versões, URLs de registro, checksums quando disponíveis e saída da instalação.

A política de rede deve ser igualmente explícita. Um agente de codificação pode precisar ler documentação pública, chamar uma API de staging, baixar um pacote ou expor uma pré-visualização local. Essas são diferentes de acesso irrestrito à internet. Separe buscas de pacotes de saída, navegação na web, chamadas de API, entrega de webhooks e ingresso de pré-visualização. Se seu produto lida com código ou dados sensíveis, pergunte se DNS, logs de proxy e mirrors de registro são cobertos pela mesma política que o tráfego HTTP.

Segredos, logs e trilhas de auditoria para espaços de trabalho do agente

Segredos devem ter o menor escopo útil. Um agente de codificação normalmente não precisa de credenciais de produção. Ele pode precisar de um token Git somente leitura, um token de registro de pacotes, uma chave de API de staging ou um token de implantação de pré-visualização. Cada um deve ter escopo de tarefa, ser limitado no tempo quando possível e indisponível para comandos que não o exigem.

Evite colocar segredos em arquivos que o agente possa ler, a menos que a tarefa realmente exija isso. Prefira acesso intermediado: o sandbox pode realizar uma operação, mas o modelo não vê a credencial bruta. Quando variáveis de ambiente são necessárias, os logs devem ocultar padrões de segredos conhecidos, e os artefatos do revisor não devem incluir dumps completos de ambiente.

Para trilhas de auditoria, armazene mais do que o patch final:

• Solicitação do usuário e metadados da tarefa.
• URL do repositório, commit base, branch e commit ou diff final.
• Comandos solicitados, aprovados, bloqueados e executados.
• Saídas de comandos, códigos de saída e timeouts.
• Leituras e gravações de arquivos quando a plataforma puder capturá-las.
• Registros de rede e busca de pacotes no nível que sua política suporta.
• URLs de pré-visualização e caminhos de artefatos gerados.
• Aprovações humanas e decisões de mesclagem.

Isso não é burocracia. É como um revisor distingue uma correção real de uma história plausível.

Diffs, pré-visualizações e portões de revisão antes da mesclagem

A saída mais útil de um agente de codificação é um conjunto de alterações revisável. Isso significa que o sandbox deve produzir os mesmos artefatos que um engenheiro cuidadoso esperaria de um pull request:

• Um diff focado.
• Testes ou comandos de compilação que foram executados.
• Falhas que permanecem.
• Capturas de tela, URLs de pré-visualização ou arquivos para download quando a interface do usuário ou ativos gerados foram alterados.
• Uma breve explicação da mudança de comportamento pretendida.

Mantenha a mesclagem ou implantação final atrás de um portão controlado por humanos, a menos que sua organização tenha construído uma política de automação confiável separada para esse repositório e nível de risco exatos. A revisão humana é especialmente importante quando as alterações tocam em autenticação, faturamento, acesso a dados, chamadas de rede, infraestrutura, versões de dependências, migrações geradas ou conteúdo visível ao usuário.

O tratamento de pré-visualização merece sua própria regra: exponha apenas o serviço e a porta necessários para revisão. Um sandbox que inicia um aplicativo web deve dar aos revisores uma URL de pré-visualização com escopo, não acesso amplo de rede ao espaço de trabalho.

Estratégia de limpeza e redefinição para sessões de agente de longa duração

Todo sandbox precisa de um ciclo de vida. Sem um, a infraestrutura de agente de codificação de longa duração se torna uma pilha de espaços de trabalho obsoletos, logs vazados e processos ainda em execução.

Para tarefas curtas, um modelo efêmero funciona bem: crie um sandbox, execute o trabalho, extraia artefatos e destrua-o. Para tarefas maiores, a persistência pode ser valiosa: o agente pode precisar pausar, aguardar revisão, retomar do mesmo branch ou manter um servidor de desenvolvimento em execução durante uma sessão de revisão. A persistência deve ser um recurso explícito do produto com regras de expiração, proprietário e retenção.

Defina a limpeza para:

• Processos em segundo plano e portas abertas.
• Arquivos temporários e saídas de compilação.
• Caches de pacotes e arquivos baixados.
• Segredos com escopo de tarefa.
• Logs e artefatos.
• Branches ou worktrees que foram substituídos.

A redefinição é igualmente importante. Um revisor deve ser capaz de reexecutar a validação do agente a partir do commit base ou do branch final. Se o resultado funciona apenas por causa de estado invisível dentro de uma sessão de longa duração, o fluxo de trabalho é difícil de confiar.

Onde o Novita Agent Sandbox se encaixa neste fluxo de trabalho

O Novita Agent Sandbox é projetado para infraestrutura de agente onde execução de código, automação de navegador, fluxos de trabalho estilo computer-use, análise de dados, avaliações e fluxos de trabalho de agente de longa duração precisam de um ambiente de execução isolado. A documentação do Novita Agent Sandbox descreve o produto como um ambiente com estado para executar cargas de trabalho de agente, com caminhos SDK e CLI para trabalhar com ciclo de vida do sandbox, arquivos, comandos, sessões de navegador e primitivos de fluxo de trabalho relacionados. A Novita também documenta agora um template de primeira parte Codex Agent, o que importa porque transforma a ideia de “executar Codex em um sandbox” em um fluxo de trabalho lançado com detalhes de configuração concretos.

Para equipes que já usam as APIs de modelo da Novita AI, uma camada de sandbox pode reduzir a lacuna entre inferência de modelo e execução de ação. O modelo pode raciocinar, chamar ferramentas e planejar alterações de código; o sandbox pode fornecer o espaço de trabalho isolado onde essas ações são executadas, registradas, visualizadas e revisadas.

O que o template Codex de primeira parte muda na prática

O novo template Codex não remove a necessidade de política, mas esclarece como um fluxo de trabalho Codex orientado à produção se mapeia para os controles descritos anteriormente neste artigo.

• codex exec oferece um modo de execução não interativo que se encaixa melhor em trabalhos em fila, orquestradores de agente e execução de tarefas revisáveis do que uma sessão de terminal puramente interativa.
• --full-auto faz sentido apenas quando o próprio sandbox é o limite de aprovação confiável. Em outras palavras, a aprovação automática é mais fácil de justificar quando o acesso a arquivos, o egresso de rede, o escopo do repositório e a limpeza já são restringidos pelo ambiente de execução ao redor do Codex.
• --skip-git-repo-check é útil para tarefas de bootstrap, mas o padrão mais forte para trabalho de engenharia real ainda é clonar um repositório específico no sandbox e executar o Codex a partir desse checkout controlado.
• Escrever ~/.codex/auth.json e ~/.codex/config.toml dentro do sandbox torna a personalização do provedor e do modelo parte do ambiente isolado, em vez de algo emprestado de um laptop de desenvolvedor.
• sandbox.git.clone se encaixa naturalmente com isolamento de repositório e controle de branch: puxe apenas o repositório que a tarefa precisa, execute o agente nesse diretório com escopo e mantenha a máquina host fora do loop.
• A retomada de sessão via --json, thread_id capturado e codex exec resume <thread_id> é uma maneira prática de lidar com trabalhos de longa duração sem fingir que persistência e auditabilidade são a mesma coisa. Você ainda precisa de regras explícitas de retenção, captura de log e propriedade para sessões retomadas.

Essa é a divisão útil entre documentação e orientação de blog. A documentação mostra a sequência operacional. A decisão do fluxo de trabalho é tratar esses mecanismos como evidência para um padrão mais seguro: execute o Codex dentro de um espaço de trabalho limitado, mantenha a aprovação automática limitada a sandboxes confiáveis, preserve o estado do repositório intencionalmente e torne as sessões retomadas visíveis para os revisores, em vez de memória opaca do agente.

Use limites de produto conservadores ao projetar seu fluxo de trabalho:

• Trate o Novita Agent Sandbox como o ambiente de execução, não uma garantia de segurança abrangente.
• Mantenha segredos, instalações de pacotes, egresso e ações de publicação atrás de sua própria política.
• Valide os detalhes atuais do SDK, CLI, preços e limites de conta na documentação da Novita antes de codificá-los em automação de produção.
• Avalie os limites de isolamento, a compatibilidade com agentes de terceiros e os requisitos de conformidade em relação à sua própria política antes de confiar em qualquer sandbox em produção.

Essa separação mantém a orientação de implementação útil mesmo quando a camada do agente muda. Você pode usar agentes estilo Codex, agentes de codificação internos, agentes de navegador ou trabalhadores de avaliação, mantendo as mesmas perguntas de controle do sandbox.

Lista de verificação de implementação de sandbox para agente de codificação

Use esta lista de verificação antes de mover um sandbox de agente de codificação além de um protótipo.

Área	Pergunta mínima de produção
Espaço de trabalho	Cada tarefa recebe um sistema de arquivos com escopo e um commit base de repositório conhecido?
Branch	As alterações do agente são isoladas em um branch ou patch que os revisores podem inspecionar?
Terminal	Os comandos são registrados com diretório de trabalho, saída, código de saída e timeout?
Aprovação	Quais comandos são executados automaticamente, exigem aprovação ou são bloqueados?
Pacotes	As instalações de dependências são reproduzíveis e registradas?
Rede	O egresso é separado entre buscas de pacotes, navegação em documentação, chamadas de API e acesso de pré-visualização?
Segredos	As credenciais têm escopo de tarefa e são ocultadas dos logs?
Pré-visualizações	As portas de pré-visualização são explícitas e fáceis de desligar?
Artefatos	Os arquivos gerados, capturas de tela, relatórios e logs são anexados à revisão?
Persistência	A pausa/retomada da sessão é intencional, com proprietário e expiração?
Limpeza	Processos, portas, arquivos temporários, segredos e espaços de trabalho obsoletos são removidos?
Revisão	Um humano aprova mesclagem, publicação ou implantação para alterações arriscadas?

Se sua configuração atual não conseguir responder a várias dessas perguntas, mantenha o fluxo de trabalho em uma faixa de protótipo. O agente ainda pode ser útil, mas não deve receber acesso amplo a repositório, rede ou credenciais.

FAQ

Posso executar o próprio Codex dentro de um sandbox em nuvem?

Sim. A Novita agora documenta um template de primeira parte Codex Agent para o Novita Sandbox, com um fluxo lançado para executar codex exec em um ambiente isolado, clonar repositórios no sandbox, personalizar as configurações do provedor Codex dentro de ~/.codex/ e retomar sessões anteriores com um thread_id capturado. A ressalva ainda se aplica no nível da conta e configuração: valide o caminho de autenticação exato, credenciais do repositório, limites de tempo de execução e controles de política para seu próprio ambiente, em vez de assumir que todo fluxo de trabalho local do Codex é transferido inalterado.

O Docker é suficiente para um sandbox de agente de codificação?

O Docker pode ser útil para desenvolvimento local, trabalhos de CI e ambientes repetíveis, mas “suficiente” depende do seu modelo de ameaça. Pergunte o que compartilha um kernel, quais montagens de arquivo existem, como o egresso de rede é controlado, se os segredos são expostos ao contêiner e como escapes ou comprometimento de dependências seriam tratados. Para cargas de trabalho sensíveis, as equipes de segurança frequentemente avaliam limites de isolamento mais fortes e controles de egresso mais rigorosos.

Um agente de codificação deve ter acesso à internet?

Apenas quando a tarefa precisar, e apenas por meio de uma política que você possa explicar. Consulta de documentação, acesso a registros de pacotes, chamadas de API de staging e navegação arbitrária são permissões diferentes. Registre o que o agente buscou, mantenha as instalações de pacotes reproduzíveis e evite dar acesso à rede de produção a uma sessão de codificação de propósito geral.

O que um revisor deve examinar antes de mesclar código gerado por agente?

Revise o diff, os comandos que foram executados, a saída de teste/compilação, as alterações de dependências, os artefatos gerados, o comportamento da pré-visualização e qualquer validação ignorada. Preste atenção extra a autenticação, permissões, manipulação de dados, chamadas de rede, migrações, scripts de instalação e segredos.

Como a Novita ajuda com sandboxes para agentes de codificação?

O Novita Agent Sandbox fornece um ambiente de execução de agente isolado para cargas de trabalho como execução de código, automação de navegador, tarefas estilo computer-use, análise de dados, avaliações e fluxos de trabalho de longa duração. Com o template Codex de primeira parte, esse ambiente de execução também pode hospedar fluxos específicos do Codex, como execução não interativa, checkouts com escopo de repositório, configuração personalizada de provedor e retomada de sessão. Combine esses mecanismos com políticas explícitas de repositório, comando, pacote, rede, segredos e revisão para que o sandbox permaneça como o limite de execução, em vez de se tornar um atalho não supervisionado para seus controles normais de engenharia.

Artigos recomendados

• AI-Generated Code Sandbox Requirements for Production Apps
• Run Claude Code or Managed Agents in an Isolated Sandbox
• MCP Servers in Isolated Sandboxes: Filesystem, Secrets, and Network Tradeoffs