Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Modo sandbox

Estado: Activo Alcance: estado actual Última revisión: 2026-08-23 Responsable: runtime de ax-code

AX Code incluye un sandbox de ejecución integrado que puede restringir lo que el agente de IA hace en tu sistema. De forma predeterminada, AX Code arranca en acceso completo con el sandbox desactivado, así que las escrituras en el sistema de archivos y el acceso a la red no tienen restricciones. Activa workspace-write o read-only antes de trabajar con repositorios no confiables o de ejecutar tareas sin supervisión.

Aviso de seguridad: full-access no es un límite de seguridad. El agente puede modificar archivos fuera del espacio de trabajo, escribir .git/ y .ax-code/, ejecutar comandos de shell sin restricciones y acceder a la red.

Inicio rápido

Alterna el sandbox desde la TUI:

• Escribe /sandbox en el prompt, o
• Pulsa Ctrl+P y busca «sandbox»

La barra de estado muestra el estado actual:

• sandbox activado (verde): el agente queda confinado al espacio de trabajo
• sandbox desactivado (rojo): sin restricciones

El ajuste persiste entre sesiones en ax-code.json.

Qué cambia

Configuración

Fuente de verdad

Esta página resume el comportamiento visible para el usuario. Cuando el comportamiento cambie, verifica la documentación frente a:

• packages/ax-code/src/isolation/index.ts para la resolución del modo, las rutas protegidas, las comprobaciones de red, de escritura y de bash, y IsolationDeniedError.
• packages/ax-code/src/config/schema.ts para la forma de la configuración, los valores predeterminados y las descripciones.
• packages/ax-code/src/server/routes/isolation.ts para el comportamiento del alternado en el entorno de ejecución y la persistencia.
• packages/ax-code/test/isolation/isolation.test.ts y packages/ax-code/test/tool/bash.test.ts para el comportamiento de aplicación esperado.

Mantén breves las afirmaciones duplicadas en el README raíz y enlaza aquí para los detalles.

Alternar desde la TUI

Usa /sandbox o la paleta de comandos (Ctrl+P → «Activar o desactivar el sandbox»). El cambio surte efecto de inmediato y se guarda en el ax-code.json de tu proyecto.

Indicador de la CLI

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

Variable de entorno

AX_CODE_ISOLATION_MODE=workspace-write ax-code

Archivo de configuración

En ax-code.json:

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

Precedencia

Indicador de CLI > variable de entorno > archivo de configuración > valor predeterminado (full-access)

Cuando hay activa una anulación de la CLI o del entorno, la TUI informa de ese modo efectivo. Un alternado /sandbox puede guardar la preferencia del proyecto, pero la anulación de mayor precedencia sigue activa hasta que se retira (normalmente al reiniciar).

Modos de aislamiento

Rutas protegidas

En el modo workspace-write, estas rutas están siempre protegidas contra escritura:

• .git/: evita corromper por accidente el estado de Git
• .ax-code/: evita la manipulación de la configuración o de los plugins

Añade rutas protegidas personalizadas en la configuración:

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

Acceso a la red

La red está desactivada de forma predeterminada en los modos workspace-write y read-only. Herramientas afectadas:

• webfetch: bloqueado
• websearch: bloqueado
• codesearch: bloqueado
• bash: los clientes solo de red (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) están bloqueados

Limitación: el bloqueo de red en bash es de capa de aplicación y cubre los clientes de red dedicados de arriba. No intercepta herramientas de doble uso que también funcionan sin conexión (git, npm/pnpm/yarn, pip, go, intérpretes de lenguajes como python/node), porque sus invocaciones sin conexión no se pueden distinguir de forma estática y bloquearlas rompería flujos habituales. Un aislamiento de red verdadero y exhaustivo exige controles del sistema operativo, que este sandbox no proporciona. Cuando se alcanza un cliente denegado, el agente pide una elevación de una sola vez.

Para permitir la red y conservar las restricciones de escritura:

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

Backend de aislamiento (aplicación frente al sistema)

macOS: perfiles Seatbelt mediante sandbox-exec (escritura limitada al espacio de trabajo o worktree, red denegada cuando network: false).
Linux: bubblewrap (bwrap) cuando está instalado (--unshare-net cuando la red está desactivada, espacio de trabajo montado con enlace en lectura y escritura).
Windows: solo capa de aplicación por ahora.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

Consulta SECURITY.md para el modelo de amenazas.

Permisos y hooks controlados por el repositorio

Los archivos del proyecto no son confiables de forma predeterminada. Las reglas de permisos en ax-code.json, .ax-code/policy.json y las definiciones de agente o modo del proyecto pueden endurecer el acceso con deny, pero las concesiones allow/ask controladas por el repositorio se ignoran. Los comandos del proyecto no pueden activar la expansión de shell. .ax-code/hooks.json, .ax-code/plugin/ y los plugins configurados por el proyecto no se ejecutan.

La configuración no confiable del proyecto tampoco puede elegir un shell personalizado, un LSP o formateador ejecutable, un paquete de proveedor o un endpoint de API, variables de entorno de credenciales del proveedor, una fuente externa de skills ni una ruta de instrucciones fuera del worktree. Siguen disponibles las rutas de instrucciones relativas seguras y las anulaciones integradas no ejecutables. Los servidores MCP usan un flujo de aprobación aparte con huella, descrito en Integraciones MCP.

Después de revisar la configuración controlada por el repositorio, los usuarios pueden optar por aceptarla fuera del repositorio para el proceso actual:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

El interruptor solo de entorno impide que una copia de trabajo se declare confiable a sí misma.

Cómo funciona la aplicación

La aplicación del sandbox es siempre de capa de aplicación y se comprueba en cada invocación de herramienta. Cuando backend es os o auto y la plataforma lo admite, bash se envuelve además en un sandbox del núcleo.

Cuando una herramienta incumple el aislamiento, lanza un IsolationDeniedError con un mensaje claro que explica qué se bloqueó y por qué.