Sandbox do Codex: perfis de permissão para npm sem acesso total
Mantenha as proteções do espaço de trabalho do Codex e permita acesso ao registro de pacotes. Configure um perfil de permissão e o proxy de rede, teste operações permitidas e bloqueadas e entenda o alcance da leitura, o isolamento nativo e as restrições de perfis da empresa.
Conteúdo

Se o Codex edita seu repositório, mas não consegue baixar pacotes npm, confira o perfil de permissão do sandbox antes de alterar as configurações da API. O perfil integrado :workspace desativa o acesso à rede dos comandos, o que afeta quem instala dependências em sessões locais do Codex. Crie um perfil que estenda :workspace, ative o proxy de rede e permita o nome de host do registro em vez de conceder acesso total.
Em 2026-11-19, a OpenAI documenta os perfis de permissão como um recurso beta. Este guia configura a execução local de comandos e usa exemplos de Bash para macOS, Linux ou WSL2.
O que o perfil padrão do espaço de trabalho permite?
Quando um repositório Git é a raiz do espaço de trabalho, :workspace permite que os comandos do sandbox editem arquivos de código-fonte, mas protege alguns diretórios. Em cada raiz do espaço de trabalho, .git, .codex, .agents e .aws continuam disponíveis apenas para leitura. Isso impede gravações diretas em configurações como .codex/config.toml e nos hooks de .git/hooks. Essas proteções valem para os caminhos dentro das raízes do espaço de trabalho, não para todos os diretórios com esses nomes no computador.
As permissões de leitura são mais amplas. Os comandos podem ler arquivos fora do repositório quando suas permissões no sistema operacional permitem. A explicação da OpenAI sobre os limites padrão do sandbox descreve por que isso permite usar compiladores, SDKs, bibliotecas e configurações armazenadas em outros locais. Isso não significa que esses arquivos fiquem ocultos dos comandos do Codex.
A rede fica desativada porque um comando capaz de ler dados não deve receber automaticamente permissão para enviá-los a serviços externos. Pelo mesmo motivo, baixar dependências exige acesso adicional. A OpenAI também documenta que processos filhos herdam as restrições de sandbox do processo pai, inclusive descendentes que continuam ativos depois que o comando original termina.
Para um download ocasional, analise a solicitação de acesso à rede em vez de alterar seu perfil padrão. O Codex pode enviar a solicitação a você ou à revisão automática, conforme a explicação sobre o proxy de rede. Para downloads frequentes de dependências, use um perfil limitado ao registro. Mantenha a rede desativada nos fluxos de trabalho que não precisam dela.
Configure um perfil dev para o registro do npm
Use uma instalação do Codex CLI que ofereça a interface documentada codex sandbox --permission-profile. As verificações também exigem npm, curl e Bash. Valide a política a partir da raiz de uma cópia de trabalho temporária de um repositório Git.
Edite seu arquivo pessoal ~/.codex/config.toml. Incorpore os ajustes abaixo às tabelas existentes, em vez de definir a mesma tabela mais de uma vez. Essa configuração define dev como seu perfil de permissão padrão.
Não combine essa configuração com os ajustes antigos sandbox_mode ou [sandbox_workspace_write]. A documentação de perfis de permissão exige escolher um dos dois sistemas de configuração, sem misturá-los.
default_permissions = "dev"
[features]
network_proxy = true
[permissions.dev]
description = "Workspace editing with npm registry access."
extends = ":workspace"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
".env" = "deny"
".env.local" = "deny"
"secrets" = "deny"
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"registry.npmjs.org" = "allow"
"example.com" = "deny"
extends = ":workspace" preserva as proteções integradas, incluindo o acesso somente para leitura a .git e .codex. As entradas adicionais impedem alterações nas configurações do editor e do contêiner de desenvolvimento. Elas também bloqueiam o acesso aos arquivos de variáveis de ambiente indicados e ao diretório secrets, com todo o seu conteúdo, em cada raiz. A OpenAI define os valores de permissão do sistema de arquivos assim: read permite apenas leitura, write permite leitura e gravação, e deny bloqueia o acesso.
A configuração de rede tem dois controles separados. permissions.dev.network.enabled = true permite acesso à rede; network_proxy = true ativa a aplicação das regras de domínio. Como explica a documentação de permissões de rede, ativar a rede sem um proxy ativo concede acesso direto à rede. Nesse caso, as regras de domínio não são aplicadas. Não omita a configuração do proxy.
O guia de segurança empresarial da OpenAI inclui registry.npmjs.org no exemplo de acesso a dependências. Aqui, example.com é um destino bloqueado explicitamente para verificar a restrição. Segundo o comportamento documentado das regras de domínio, bloqueios explícitos prevalecem sobre regras de permissão correspondentes. Outros destinos exigem aprovação ou são bloqueados.
Essa configuração não concede acesso irrestrito a todos os hosts que uma instalação de pacotes pode contatar. Adicione outro nome de host somente depois de identificar por que o projeto precisa dele.
Verifique tanto as permissões quanto as restrições
Use codex sandbox para testar comandos diretamente com o perfil. Inclua --include-managed-config para que a resolução do perfil também considere os requisitos gerenciados. Isso importa quando uma política da empresa restringe suas opções.
Primeiro, verifique o registro no Bash:
codex sandbox --permission-profile dev --include-managed-config -- \
npm ping --registry=https://registry.npmjs.org \
--cache="$PWD/.npm-cache"
Um npm ping bem-sucedido mostra PONG. Neste exemplo, a opção cache coloca o cache do npm dentro do espaço de trabalho. Isso evita conceder uma permissão de gravação separada para um cache em outro local. O resultado confirma a conexão com o registro, não que todas as dependências ou os scripts de instalação possam ser concluídos.
Em seguida, verifique a gravação no espaço de trabalho, a proteção dos metadados do Git e o domínio bloqueado. Execute essas verificações separadamente. O teste do Git pressupõe que .git seja um diretório existente, não um arquivo que aponta para o diretório real do repositório.
# Expect success: create and remove a temporary workspace file.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp ./codex-write-check.XXXXXX) && rm "$p"'
# Expect a filesystem permission denial.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp .git/codex-write-check.XXXXXX) && rm "$p"'
# Expect a proxy policy rejection.
codex sandbox --permission-profile dev --include-managed-config -- \
curl --fail --head --max-time 15 https://example.com
O resultado esperado é que a gravação no espaço de trabalho funcione, a gravação em .git seja negada e a solicitação de rede seja rejeitada. Um erro de configuração, um diretório inexistente ou uma falha de conexão sem relação com a política não comprovam que a restrição funcionou. Se alguma operação restrita for concluída, pare e examine a configuração efetiva antes de usar o perfil no trabalho normal. Essas são verificações para você executar, não resultados de testes já realizados.
Depois de obter os resultados esperados, inicie uma nova sessão do Codex na raiz do repositório. Execute /permissions e confira a entrada dev e sua descrição, como documentado no exemplo de configuração de perfis da OpenAI. Com esse perfil ativo, tente novamente a instalação de dependências original. Mantenha o cache dentro do espaço de trabalho ou conceda acesso write apenas ao diretório externo de cache necessário.
O que verificar se os downloads ainda falharem?
Se o perfil não estiver sendo aplicado, primeiro procure ajustes antigos do sandbox na configuração carregada. Depois, confira a ordem de prioridade das configurações: opções da linha de comando ou configurações de um projeto confiável podem substituir seus valores padrão. Não continue adicionando permissões a um perfil que a sessão não está usando.
Se npm ping funcionar, mas a instalação falhar, examine separadamente o destino da solicitação com erro e o caminho do sistema de arquivos. Outro nome de host precisa de uma decisão própria de acesso à rede. Gravar o cache fora do espaço de trabalho exige uma regra adequada do sistema de arquivos. As permissões do sistema de arquivos e da rede são independentes: liberar a rede não concede permissão para gravar arquivos.
Se um destino permitido ainda falhar, confira se o cliente respeita as configurações do proxy. As notas de implementação do proxy de rede da OpenAI explicam que alguns programas ignoram as variáveis de ambiente do proxy. Investigue o cliente ou sua configuração em vez de remover as restrições do sandbox.
Uma falha na conexão do próprio Codex com o provedor de modelos é diferente de um comando do gerenciador de pacotes bloqueado no sandbox. Para configurar a autenticação do provedor, a Base URL ou o protocolo, consulte o guia de conexão de API ao Codex.
O acesso amplo de leitura pode expor chaves de API?
Sim. A proteção somente para leitura impede alterações, não a leitura. A OpenAI explica diretamente essa consequência no artigo sobre o sandbox do Codex. Em tradução:
A contrapartida é que arquivos sensíveis em outros locais do computador também podem continuar acessíveis para leitura, como arquivos de configuração que contêm chaves de API.
Portanto, o perfil padrão não garante que os segredos fora do repositório fiquem ocultos.
O exemplo bloqueia apenas os caminhos específicos .env e .env.local, relativos à raiz, e o diretório secrets com todo o seu conteúdo. Ele não cobre todos os possíveis nomes ou locais de arquivos com credenciais. Adicione regras deny apropriadas para caminhos sensíveis do seu ambiente, inclusive fora do espaço de trabalho quando necessário. Teste com arquivos inofensivos, sem exibir credenciais reais.
Arquivos que podem ser modificados também representam um risco. A OpenAI descreve como alterar um pacote instalado, como node_modules/prettier, pode afetar um formatador que o editor execute depois fora do sandbox. Como o Git costuma ignorar node_modules, essa alteração pode não aparecer em git status. Revise as ferramentas e dependências geradas que permitem gravação, além das mudanças no código versionado.
Equipes que usam vários agentes de programação também devem revisar as permissões do Claude Code para segredos e Git. Use a configuração própria de cada ferramenta, em vez de copiar as chaves de permissão do Codex para outro cliente.
Por que usar isolamento nativo em vez de Docker?
O isolamento nativo permite que o Codex use suas ferramentas de desenvolvimento existentes enquanto aplica restrições do sistema operacional aos comandos que executa. A OpenAI apresenta seu projeto de sandbox nativo como alternativa a exigir que os usuários reproduzam o ambiente de desenvolvimento dentro de um contêiner.
O exemplo prático é o desenvolvimento de iOS em um Mac. No fluxo descrito pela OpenAI, um contêiner Docker não consegue executar as ferramentas nativas de compilação do Mac nem iniciar o simulador de iPhone. Delegar essas operações ao Mac hospedeiro as coloca fora do sandbox do contêiner. Por isso, as operações no hospedeiro ainda precisam de suas próprias restrições.
No macOS, o Codex usa Seatbelt. Para Linux e WSL2, as instruções de configuração do sandbox da OpenAI recomendam instalar bubblewrap pelo gerenciador de pacotes da distribuição. Trate uma falha na inicialização do sandbox separadamente de uma solicitação negada ao registro.
A execução nativa no Windows precisa de validação própria. A documentação do sandbox do Windows recomenda MXC em dispositivos compatíveis. Ela também alerta que a implementação antiga unelevated não permite bloquear a leitura de caminhos específicos. Obter os resultados esperados nas verificações de Bash no WSL2 não substitui testar a aplicação das restrições no Windows nativo.
Um contêiner continua sendo uma opção quando todo o fluxo de trabalho acontece dentro dele. Se o trabalho depende de ferramentas do hospedeiro, identifique e restrinja as operações executadas nele. Não presuma que o contêiner também cobre o trabalho delegado ao hospedeiro.
Uma empresa pode impedir que você selecione dev?
Sim. Administradores podem usar um arquivo requirements.toml gerenciado para limitar quais perfis os usuários podem selecionar. Definir um perfil local não substitui essa restrição. O exemplo de requisitos gerenciados da OpenAI mostra esta política:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
Quando allowed_permission_profiles está presente, a tabela final combinada forma a lista completa de perfis permitidos. Perfis ausentes dessa tabela são bloqueados, assim como aqueles definidos explicitamente como false. Se o exemplo representar a lista final após a combinação dos requisitos, seu perfil personalizado dev ficará indisponível porque não foi permitido. Peça ao administrador que aprove um perfil adequado para compilação, em vez de tentar contornar a política.
A documentação de configuração gerenciada estabelece um limite importante entre versões: listas de perfis permitidos exigem Codex 0.138.0 ou posterior. Codex 0.137.0 e versões anteriores ignoram allowed_permission_profiles e o ajuste gerenciado default_permissions. Confira todos os clientes gerenciados antes de depender desse controle.
Antes de ampliar a implantação, teste uma compilação permitida e uma ação bloqueada de propósito em cada sistema operacional compatível. Limite as permissões aos registros necessários, confirme que o perfil esperado está selecionado e mantenha os testes de bloqueio ao atualizar os clientes.