Sandboxing en Codex — Permisos, Approvals y Entornos Cloud

Referencias Oficiales: Sandboxing · Config Basics · Cloud Environments · Review

Ruta del currículo

1. Primeros Pasos con Codex — Instalación, Primera Tarea y Checkpoints — primeros loops seguros
2. Instrucciones de Codex — Cómo Hacer que AGENTS.md Sirva de Verdad — reglas del repo y defaults
3. Sandboxing en Codex — Permisos, Approvals y Entornos Cloud — permisos y límites ← Estás aquí
4. Diseño de Tareas en Codex — Escribe Prompts Como Issues, No Como Deseos — dar buena forma al trabajo
5. Skills de Codex — Convierte Prompts Repetidos en Workflows Reutilizables — convertir trabajo repetido en activos reutilizables
6. Subagentes de Codex — Ejecución Paralela y Patrones de Delegación — ejecución paralela y delegación
7. MCP en Codex — Conecta Contexto Externo en Vez de Copiarlo y Pegar — conectar sistemas externos
8. Reviews y Automatizaciones con Codex — /review, Worktrees e Ingeniería Repetible — ejecutar workflows estables una y otra vez
9. Codex Worktrees — Ejecución Paralela Aislada Sin Caos de Branches
10. Handoffs en Codex — Convertir Lanes Paralelos en Resultados Listos para Merge
11. Loops de Verificación en Codex — Demostrar que Funciona Antes del Merge
12. Release Readiness en Codex — Gates Finales Antes de Producción
13. Codex Loop Seguro del Primer Día — Flujo Inicial para Evitar Errores Tempranos
14. Playbook de Entrega de Equipo en Codex — Operación Intermedia por Lanes
15. Gobernanza de Cambios de Alto Riesgo en Codex — Controles Avanzados para Releases Críticas
16. Manual Operativo de Codex — Ritmo Diario, Semanal y de Release para Equipos
17. Playbook de Recuperación de Incidentes en Codex — Respuesta Determinista Bajo Presión
18. Bucle de Hardening Post-Incidente en Codex — De la Recuperación a Controles Duraderos
19. Simulacros de Resiliencia Caótica en Codex — Ensayar Fallos Antes de Recibirlos
20. Métricas de Resiliencia y SLO en Codex — Medir Confiabilidad Antes del Fallo
21. Loops de Persistencia Ralph en Codex — Llevar Tareas Largas a Cierre Verificado

Documentación oficial usada en esta guía

• Diferencia entre read-only, workspace-write y danger-full-access — Sandboxing
• Combinaciones base de config — Config basics
• Ciclo de vida cloud, setup e internet — Cloud environments

El sandbox no es solo seguridad: también es ergonomía

La conversación equivocada es “¿cómo hago para que Codex tenga más poder?”. La conversación correcta es “¿cómo dejo que haga trabajo normal sin volver la revisión inmanejable?”.

Sandboxing en Codex define qué puede tocar, cuándo debe pedir permiso y qué tan caro sería un error. Si aprietas demasiado, te ahogas en approvals. Si aflojas demasiado, la revisión deja de ser cómoda y el blast radius crece.

La meta operativa es esta:

• Codex no debería pedir permiso para trabajo rutinario y local.
• Sí debería frenar antes de cruzar límites de riesgo.
• El diff resultante debe seguir siendo fácil de revisar y revertir.

Piensa en tres palancas, no en una sola

Mucha gente habla de “el sandbox” como si fuera un único switch. En la práctica, el comportamiento real sale de tres palancas combinadas:

1. sandbox_mode — qué puede hacer por defecto.
2. approval_policy — en qué momento se detiene para pedir permiso.
3. writable_roots — exactamente dónde puede escribir.

Si configuras solo una de las tres, el modelo mental queda incompleto.

Los modos locales más comunes

La documentación oficial resume así los modos más usados:

OpenAI describe workspace-write como el modo local de baja fricción por defecto. Eso importa porque te da una pista de diseño: si no tienes una razón fuerte para salirte de ahí, probablemente todavía no la necesitas.

Approval policy: dónde nace la fatiga

El sandbox no suele doler por el nombre del modo. Duele por la frecuencia con la que interrumpe el flujo.

La combinación que aparece una y otra vez en la documentación es:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

Ese combo funciona bien como baseline porque deja pasar trabajo típico dentro del repo, pero sigue poniendo una puerta antes de acciones que cruzan el borde.

Cómo leer el tradeoff real

La clave es distinguir approval fatigue de riesgo legítimo. No toda interrupción es mala. Pero si las pausas aparecen en acciones rutinarias y previsibles, el problema suele ser la configuración, no el usuario.

writable_roots decide el blast radius real

Los docs de Sandboxing señalan que, si necesitas trabajar sobre más de un directorio, puedes extender la escritura con writable roots en vez de desactivar el sandbox entero. Ese detalle cambia muchísimo la práctica diaria.

Buenos defaults

• el root del repo actual
• quizá un directorio temporal controlado
• como mucho, una segunda carpeta hermana si la tarea realmente la necesita

Defaults peligrosos

• todo tu home
• varios proyectos no relacionados
• carpetas con secretos, notas personales o repos fuera del flujo actual

Una regla útil: si no te sentirías cómodo viendo ese directorio en un diff inesperado, no debería ser writable root por defecto.

Local y cloud: modelos mentales distintos

Muchos tropiezos vienen de mezclar cómo se comporta Codex local con cómo funciona Codex cloud. No son lo mismo.

La pregunta correcta no es “¿por qué cloud no hace lo mismo que local?” Sino: “qué parte de mi éxito local dependía de estado que nunca formalicé?”

En cloud, setup es el contrato operativo

Los docs de Cloud Environments describen un ciclo claro:

1. Codex crea un contenedor y hace checkout del repo.
2. Ejecuta tu setup script.
3. Aplica la política de internet.
4. Entra la fase del agente para editar y verificar.

Dos hechos oficiales importan muchísimo:

• los setup scripts corren con acceso a internet
• el acceso a internet en la fase del agente está apagado por defecto

Eso te da una guía directa: si algo necesita descargar dependencias, hacer bootstrap, preparar toolchains o generar artefactos base, normalmente pertenece a setup y no al loop de edición.

El borde de setup: qué sí y qué no meter ahí

Setup debe dejar el entorno listo para que el agente trabaje. No debe “resolver la tarea por adelantado”.

Sí conviene poner en setup

• instalación de dependencias
• pinning de runtimes o toolchains
• codegen repetible
• preparación de datos de test
• bootstrap de compilaciones nativas
• pasos de warming o caché que no requieran juicio humano

No conviene poner en setup

• implementar la feature
• mutar archivos de producto como parte silenciosa del arranque
• decisiones que dependan de leer el diff o del contexto del turno
• hacks temporales que solo existen para “hacer pasar” una tarea concreta

Un setup bueno es reproducible, declarativo y aburrido. Si cada tarea necesita explicar de nuevo cómo levantar el entorno, tu problema no es el prompt: es setup.

Variables de entorno, secretos y límites de exposición

Cloud Environments distingue entre variables de entorno y secretos:

• las environment variables están disponibles durante toda la tarea, incluyendo setup y agent phase
• los secrets solo están disponibles para los setup scripts y se eliminan antes de la fase del agente

Eso tiene implicaciones prácticas:

• si el agente necesita leer algo durante la edición, no asumas que puede ver un secret de setup
• si un dato solo se necesita para instalar o autenticar bootstrap, mejor dejarlo como secret de setup que exponerlo toda la sesión
• si dependes de credenciales en tiempo de ejecución, diseña explícitamente ese límite en vez de descubrirlo a mitad de una tarea

Review y permisos siempre van juntos

La documentación de Review dice que el panel se centra por defecto en uncommitted changes, y puede cambiar a:

• cambios contra la base branch
• cambios del último turno
• staged vs unstaged cuando trabajas localmente

Esto conecta directo con sandboxing. Cuanto más ancho sea el permiso, más necesaria es una disciplina de revisión explícita.

Traducción práctica

• sandbox más estricto → más pausas, pero el espacio de daño es menor
• sandbox más amplio → menos pausas, pero tu rutina de review tiene que ser mejor

Si amplías permisos y no mejoras /review, /diff, checkpoints o hábitos de verificación, solo cambiaste fricción por riesgo oculto.

Configuraciones sensatas para empezar

Baseline local de baja fricción

approval_policy = "on-request"
sandbox_mode = "workspace-write"

A eso súmale writable roots estrechos. Ese detalle importa más que añadir una configuración “inteligente” extra.

Cuándo ampliar writable roots

Amplía raíces escribibles cuando:

• la tarea necesita tocar dos carpetas hermanas del mismo proyecto
• el repo genera artefactos en un directorio controlado fuera del root
• tienes un workspace multi-paquete donde la frontera real no coincide con un solo folder

No las amplíes solo para “que deje de molestar”. Primero confirma que la molestia viene de una frontera mal diseñada.

Cuándo evitar danger-full-access

Evítalo si:

• todavía estás afinando instrucciones del repo
• el diff de salida aún te sorprende con frecuencia
• estás onboarding a alguien nuevo
• no tienes una rutina clara de review y rollback

En otras palabras: más poder no arregla un flujo inmaduro.

Fallos típicos y cómo diagnosticarlos rápido

Un playbook simple para no pasarte ni quedarte corto

Si estás empezando

• local primero
• workspace-write + on-request
• writable roots estrechos
• tareas pequeñas y reversibles
• review siempre al final

Si ya sientes approval fatigue real

• identifica qué acción te interrumpe demasiado
• revisa si el problema es el modo o el límite de escritura
• amplía solo la parte necesaria
• vuelve a medir si mejoró la fricción sin disparar el riesgo

Si migras un flujo a cloud

• documenta los comandos reales de verificación
• mueve bootstrap reproducible a setup
• no asumas internet en agent phase
• valida explícitamente qué necesita secrets y qué no

Checklist rápido antes de abrir más permisos

• ¿El cuello de botella es de verdad approval fatigue y no prompt vago?
• ¿La tarea cabe dentro de workspace-write si ajusto mejor los writable roots?
• ¿Tengo checkpoints o rollback claros si algo sale mal?
• ¿La revisión final sigue siendo manejable en tamaño y alcance?
• ¿En cloud, el setup deja el entorno listo sin resolver la tarea por mí?
• ¿Estoy separando bien environment variables de secrets de setup?

Regla de cierre

Empieza con límites más estrechos. Ábrelos solo cuando la fricción ya sea un problema demostrado. Y cada vez que amplíes autonomía, sube también la calidad del review, los checkpoints y la claridad del entorno.

El mejor sandbox de Codex no es el más poderoso. Es el que tu equipo puede confiar una y otra vez.