Sandbox de Codex: perfiles de permisos para npm sin acceso total
Conserva las protecciones del espacio de trabajo de Codex y permite el acceso al registro de paquetes. Configura un perfil de permisos y el proxy de red, comprueba operaciones permitidas y bloqueadas, y entiende el alcance de la lectura, el aislamiento nativo y las restricciones de perfiles de tu empresa.
Índice

Si Codex edita tu repositorio pero no puede descargar paquetes npm, revisa su perfil de permisos del sandbox antes de cambiar la configuración de la API. El perfil integrado :workspace desactiva el acceso a la red de los comandos, lo que afecta a quienes instalan dependencias en sesiones locales de Codex. Extiende :workspace, activa el proxy de red y permite el nombre de host del registro en lugar de conceder acceso total.
A fecha de 2026-11-19, OpenAI documenta los perfiles de permisos como una función beta. Esta guía configura la ejecución local de comandos y utiliza ejemplos de Bash para macOS, Linux o WSL2.
¿Qué permite el perfil predeterminado del espacio de trabajo?
Cuando un repositorio Git es la raíz del espacio de trabajo, :workspace permite que los comandos del sandbox editen archivos de código fuente, pero protege ciertos directorios. Bajo cada raíz del espacio de trabajo, .git, .codex, .agents y .aws permanecen en modo de solo lectura. Esto impide escribir directamente en archivos de configuración como .codex/config.toml o en los hooks de .git/hooks. Estas protecciones afectan a las rutas bajo las raíces del espacio de trabajo, no a todos los directorios del equipo con esos nombres.
Los permisos de lectura son más amplios. Los comandos pueden leer fuera del repositorio cuando tus permisos del sistema operativo lo permiten. La explicación de OpenAI sobre los límites predeterminados del sandbox describe por qué esto permite usar compiladores, SDK, bibliotecas y configuraciones almacenadas en otras ubicaciones. No significa que esos archivos estén ocultos para los comandos de Codex.
La red está desactivada porque un comando capaz de leer datos no debería poder enviarlos al exterior automáticamente. Por la misma razón, descargar dependencias requiere acceso adicional. OpenAI también documenta que los procesos hijos heredan las restricciones del sandbox de su proceso padre, incluso cuando siguen activos después de que termine el comando original.
Para una descarga ocasional, revisa la solicitud de acceso a la red en lugar de cambiar tu perfil predeterminado. Codex puede enviarte esa solicitud o someterla a revisión automática, como explica su descripción del proxy de red. Para descargas frecuentes de dependencias, usa un perfil limitado al registro. Mantén la red desactivada en los flujos de trabajo que no la necesitan.
Configura un perfil dev para el registro de npm
Necesitas una instalación de Codex CLI que admita la interfaz documentada codex sandbox --permission-profile. Las comprobaciones también requieren npm, curl y Bash. Valida la política desde la raíz de una copia de trabajo temporal de un repositorio Git.
Edita tu archivo personal ~/.codex/config.toml. Integra estos ajustes en las tablas existentes en lugar de definir las mismas tablas varias veces. Esta configuración selecciona dev como perfil de permisos predeterminado.
No combines esta configuración con los ajustes antiguos sandbox_mode o [sandbox_workspace_write]. La documentación de perfiles de permisos exige elegir uno de los dos sistemas de configuración, no mezclarlos.
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" conserva las protecciones integradas, incluido el acceso de solo lectura a .git y .codex. Las entradas adicionales impiden modificar la configuración del editor y del contenedor de desarrollo. También bloquean el acceso a los archivos de variables de entorno indicados y al directorio secrets con todo su contenido bajo cada raíz. OpenAI define los valores de permisos del sistema de archivos así: read permite solo lectura, write permite lectura y escritura, y deny bloquea el acceso.
La configuración de red tiene dos controles independientes. permissions.dev.network.enabled = true permite usar la red; network_proxy = true activa la aplicación de las reglas de dominio. Como explica la documentación de permisos de red, activar la red sin un proxy activo concede acceso directo a la red. En ese caso, las reglas de dominio no se aplican. No omitas la configuración del proxy.
La guía de seguridad empresarial de OpenAI incluye registry.npmjs.org en su ejemplo de acceso a dependencias. Aquí, example.com es un destino bloqueado explícitamente para comprobar la restricción. Según el comportamiento documentado de las reglas de dominio, las denegaciones explícitas tienen prioridad sobre las reglas de permiso coincidentes. Los demás destinos requieren aprobación o se bloquean.
Esta configuración no concede acceso ilimitado a todos los hosts con los que podría contactar una instalación de paquetes. Añade otro nombre de host solo después de identificar por qué lo necesita tu proyecto.
Comprueba tanto los permisos como las restricciones
Usa codex sandbox para probar comandos directamente con el perfil. Incluye --include-managed-config para que la resolución del perfil también tenga en cuenta los requisitos administrados. Esto importa cuando una política de la empresa restringe tus opciones.
Primero, comprueba el registro desde Bash:
codex sandbox --permission-profile dev --include-managed-config -- \
npm ping --registry=https://registry.npmjs.org \
--cache="$PWD/.npm-cache"
Un npm ping correcto muestra PONG. La opción cache sitúa aquí la caché de npm dentro del espacio de trabajo. Así evitas conceder un permiso de escritura adicional para una caché en otra ubicación. Esto confirma la conectividad con el registro, no que todas las dependencias o los scripts de instalación puedan completarse.
Después, comprueba la escritura en el espacio de trabajo, la protección de los metadatos de Git y el dominio bloqueado. Ejecuta estas pruebas por separado. La prueba de Git presupone que .git es un directorio existente, no un archivo que apunta al directorio real del repositorio.
# 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
El resultado esperado es que la escritura en el espacio de trabajo funcione, la escritura en .git se deniegue y la solicitud de red se rechace. Un error de configuración, un directorio inexistente o un fallo de conexión ajeno a la política no demuestran que la restricción funcione. Si alguna operación restringida tiene éxito, detente y revisa la configuración efectiva antes de usar el perfil para trabajar. Estas son comprobaciones que debes ejecutar, no resultados de pruebas ya realizadas.
Cuando obtengas los resultados esperados, inicia una nueva sesión de Codex desde la raíz del repositorio. Ejecuta /permissions y comprueba la entrada dev y su descripción, como documenta OpenAI en su ejemplo de configuración de perfiles. Con ese perfil activo, vuelve a intentar la instalación de dependencias original. Mantén su caché dentro del espacio de trabajo o concede acceso write solo al directorio externo de caché que necesite.
¿Qué revisar si las descargas siguen fallando?
Si el perfil no se aplica, busca primero ajustes antiguos del sandbox en la configuración cargada. Después, revisa la prioridad de la configuración: las opciones de la línea de comandos o la configuración de un proyecto de confianza pueden sustituir tus valores predeterminados. No sigas añadiendo permisos a un perfil que la sesión no utiliza.
Si npm ping funciona pero la instalación falla, revisa por separado el destino de la solicitud fallida y la ruta del sistema de archivos. Otro nombre de host necesita su propia decisión de acceso a la red. Escribir la caché fuera del espacio de trabajo requiere una regla adecuada del sistema de archivos. Los permisos del sistema de archivos y de red son independientes: abrir la red no concede permisos para escribir archivos.
Si un destino permitido sigue fallando, comprueba si el cliente respeta la configuración del proxy. Las notas de implementación del proxy de red de OpenAI explican que algunos programas ignoran las variables de entorno del proxy. Diagnostica el cliente o su configuración en lugar de retirar las restricciones del sandbox.
Un fallo al conectar Codex con su proveedor de modelos es distinto de un bloqueo del gestor de paquetes dentro del sandbox. Para configurar la autenticación del proveedor, la Base URL o el protocolo, consulta la guía de conexión de API a Codex.
¿El acceso amplio de lectura puede exponer claves de API?
Sí. La protección de solo lectura impide modificar archivos, no leerlos. OpenAI explica directamente este compromiso en su artículo sobre el sandbox de Codex. En traducción:
La contrapartida es que los archivos confidenciales de otras ubicaciones del equipo también pueden seguir siendo legibles, como los archivos de configuración que contienen claves de API.
Por tanto, el perfil predeterminado no garantiza que los secretos situados fuera del repositorio estén ocultos.
El ejemplo solo bloquea las rutas concretas .env y .env.local, relativas a la raíz, y el directorio secrets con su contenido. No cubre todos los posibles nombres o ubicaciones de archivos con credenciales. Añade las reglas deny adecuadas para rutas sensibles de tu entorno, también fuera del espacio de trabajo cuando sea necesario. Compruébalas con archivos de prueba inofensivos, sin mostrar credenciales reales.
Los archivos que se pueden modificar también suponen un riesgo. OpenAI describe cómo modificar un paquete instalado, como node_modules/prettier, podría afectar a un formateador que el editor ejecute después fuera del sandbox. Como Git suele ignorar node_modules, ese cambio podría no aparecer en git status. Revisa las herramientas y las dependencias generadas que se puedan modificar, además de los cambios en el código versionado.
Los equipos que utilizan varios agentes de programación también deberían revisar sus permisos de Claude Code para secretos y Git. Usa la configuración propia de cada herramienta en lugar de copiar las claves de permisos de Codex en otro cliente.
¿Por qué usar aislamiento nativo en lugar de Docker?
El aislamiento nativo permite que Codex utilice tus herramientas de desarrollo existentes mientras aplica restricciones del sistema operativo a los comandos que ejecuta. OpenAI presenta su diseño de sandbox nativo como una alternativa a reproducir todo el entorno de desarrollo dentro de un contenedor.
El ejemplo práctico es el desarrollo de iOS en un Mac. En el flujo que describe OpenAI, un contenedor Docker no puede ejecutar las herramientas nativas de compilación del Mac ni iniciar el simulador de iPhone. Delegar esas operaciones al Mac anfitrión las sitúa fuera del sandbox del contenedor. Por tanto, esas operaciones en el equipo anfitrión necesitan sus propias restricciones.
En macOS, Codex utiliza Seatbelt. Para Linux y WSL2, las instrucciones de configuración del sandbox de OpenAI recomiendan instalar bubblewrap mediante el gestor de paquetes de la distribución. Trata un fallo de inicio del sandbox por separado de una solicitud denegada al registro.
La ejecución nativa en Windows requiere su propia validación. La documentación del sandbox de Windows recomienda MXC en dispositivos compatibles. También advierte de que la implementación antigua unelevated no admite restricciones que bloqueen la lectura de rutas. Superar las comprobaciones de Bash en WSL2 no sustituye las pruebas de aplicación de restricciones en Windows nativo.
Un contenedor sigue siendo una opción cuando todo el flujo de trabajo se ejecuta dentro de él. Si necesitas herramientas del equipo anfitrión, identifica y restringe las operaciones que se ejecutan allí. No des por hecho que el contenedor también protege el trabajo delegado al anfitrión.
¿Puede una empresa impedir que selecciones dev?
Sí. Los administradores pueden usar un archivo requirements.toml administrado para limitar los perfiles que se pueden seleccionar. Definir un perfil local no anula esa restricción. El ejemplo de requisitos administrados de OpenAI muestra esta política:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
Cuando existe allowed_permission_profiles, la tabla final combinada constituye la lista completa de perfiles permitidos. Los perfiles omitidos están bloqueados, al igual que los definidos explícitamente como false. Si el ejemplo representa la lista final tras combinar los requisitos, tu perfil personalizado dev no está disponible porque no está permitido. Pide al administrador que apruebe un perfil adecuado para compilar, en lugar de intentar eludir la política.
La documentación de configuración administrada establece un límite importante entre versiones: las listas de perfiles permitidos requieren Codex 0.138.0 o posterior. Codex 0.137.0 y las versiones anteriores ignoran allowed_permission_profiles y el ajuste administrado default_permissions. Comprueba cada cliente administrado antes de confiar en este control.
Antes del despliegue, prueba una compilación permitida y una acción bloqueada deliberadamente en cada sistema operativo compatible. Limita los permisos a los registros necesarios, confirma que se ha seleccionado el perfil previsto y conserva las pruebas de bloqueo al actualizar los clientes.