Docs/ Asistente de IA/ AI Sandbox

AI Sandbox

Un contenedor Alpine Linux completo que le da al asistente de IA acceso práctico al entorno de tu aplicación para depuración, pruebas y análisis.

Qué es el AI Sandbox

El AI Sandbox es un contenedor Alpine Linux dedicado que se ejecuta junto a tu aplicación. Comparte el namespace de red de la app, lo que significa que puede acceder a tu app vía localhost, y tiene acceso a los volúmenes montados de la app. Esto le da al asistente de IA un entorno real para trabajar -- no una simulación.

Dentro del sandbox, la IA puede instalar paquetes, clonar repositorios, construir y ejecutar aplicaciones, inspeccionar archivos, probar conectividad de red y ejecutar comandos arbitrarios. Es la diferencia entre una IA que lee logs y adivina, y una IA que puede realmente interactuar con tu servicio en ejecución.

Habilitar el sandbox

El sandbox está deshabilitado por defecto. Para habilitarlo, ve a la página de Settings de tu app en el panel de control y activa AI Sandbox. Alternativamente, usa la API:

Terminal

curl -X PATCH https://your-server:9000/api/v1/apps/:id \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sandbox_enabled": true}'

Tip

El sandbox se crea bajo demanda cuando se llama a la primera herramienta de sandbox. Si activas sandbox_enabled pero nunca usas una herramienta de sandbox, no se crea ningún contenedor.

Especificaciones del contenedor

Cada contenedor sandbox se provisiona con las siguientes especificaciones:

Propiedad	Valor
Image	Alpine 3.19
User	root
RAM	1 GB
CPU	2 núcleos
Network	Compartida con la app (modo de red de contenedor)
Volumes	Volúmenes de la app montados (escribibles)
Command timeout	5 minutos
Output limit	100 KB
Pre-installed tools	`curl`, `wget`, `dig`, `nc`, `jq`, `git`, `node`, `npm`, `python3`, `pip`, `bash`

Qué puede hacer la IA

Con acceso al sandbox, el asistente de IA puede realizar depuración y análisis prácticos:

Depurar endpoints de la aplicación

Como el sandbox comparte la red de la app, la IA puede llamar a tu aplicación directamente:

Sandbox

curl localhost:3000/health
curl -v localhost:8080/api/users | jq .

Analizar código fuente y dependencias

Clonar el repositorio, instalar dependencias e inspeccionar el proyecto:

Sandbox

git clone https://github.com/user/app.git /tmp/app
cd /tmp/app && npm install
npm audit

Probar conectividad

Verificar que los servicios pueden comunicarse entre sí:

Sandbox

nc -zv db 5432
dig redis.internal
curl -s http://api:8000/healthz

Inspeccionar archivos y logs

Leer archivos de configuración, archivos de entorno y salida de logs desde volúmenes montados:

Sandbox

cat /app/config/production.json
ls -la /app/logs/
tail -100 /app/logs/error.log

Ejecutar código y probar correcciones

Ejecutar scripts y validar correcciones antes de aplicarlas a la aplicación real:

Sandbox

python3 -c "import json; print(json.loads(open('/app/config.json').read()))"
node -e "const db = require('./db'); db.ping().then(console.log)"

Herramientas del sandbox

La IA interactúa con el sandbox a través de cinco herramientas MCP dedicadas:

Herramienta	Riesgo	Descripción	Ejemplo
`sandbox_exec`	Medium	Ejecutar un comando en el contenedor sandbox	`curl localhost:3000/health`
`sandbox_read_file`	Low	Leer un archivo del sistema de archivos del sandbox	`/app/config.json`
`sandbox_write_file`	High	Escribir un archivo en el sistema de archivos del sandbox	`/tmp/test-script.sh`
`sandbox_status`	Low	Verificar si el sandbox está en ejecución y saludable	--
`sandbox_reset`	Medium	Destruir y recrear el contenedor sandbox	--

Ciclo de vida

El contenedor sandbox sigue el ciclo de vida de su aplicación padre:

Creado: Bajo demanda cuando se invoca la primera herramienta de sandbox. La creación no es bloqueante y ocurre de forma asíncrona después del despliegue.
Iniciado: Automáticamente cuando la app padre se inicia. El sandbox permanece en ejecución mientras la app esté corriendo.
Detenido: Cuando la app padre se detiene. El contenedor sandbox se detiene junto con ella.
Destruido: Cuando la app padre se elimina. El contenedor sandbox y todos sus datos se eliminan permanentemente.

El sandbox no tiene política de reinicio. Si falla, permanece detenido hasta que la siguiente llamada a herramienta de sandbox active una recreación.

Validación de comandos

El sandbox aplica una lista mínima de bloqueo para prevenir operaciones catastróficas. Los siguientes comandos son rechazados:

rm -rf / -- destrucción del sistema de archivos
mkfs -- formateo de disco
shutdown / reboot -- operaciones a nivel del host
Fork bombs (ej., patrones :())

Todo lo demás está permitido. El sandbox es intencionalmente permisivo porque su propósito es darle a la IA las mismas capacidades que tendría un desarrollador humano al depurar. El contenedor en sí es la frontera de seguridad, no el filtro de comandos.

Modelo de seguridad

El modelo de seguridad del sandbox se basa en el aislamiento de contenedores en lugar del filtrado de comandos:

Sistema de archivos aislado: El sandbox tiene su propio sistema de archivos raíz. Solo los volúmenes explícitamente montados se comparten con la app.
Límites de recursos: Límites estrictos de RAM (1 GB) y CPU (2 núcleos) previenen el agotamiento de recursos en el host.
Desechable: El contenedor puede ser destruido y recreado en cualquier momento sin afectar la aplicación.
Sin política de reinicio: Un sandbox que falla no se reinicia automáticamente, previniendo bucles infinitos de fallos.
Timeout de comandos: Cada comando tiene un timeout de 5 minutos para prevenir procesos descontrolados.
Límite de salida: La salida de comandos se trunca a 100 KB para prevenir el agotamiento de memoria en el transporte MCP.

Warning

El sandbox tiene acceso de escritura a los volúmenes de tu app. Si bien esto es necesario para que la IA depure y pruebe correctamente, ten en cuenta que la IA puede modificar archivos en los volúmenes montados.

MCP Server

Tools Reference