Objetivo del tema
Comprender cómo funciona el sandboxing en Qwen Code, por qué constituye una capa adicional de seguridad, qué proveedores se pueden usar, cómo se activa y cómo personalizar el entorno aislado cuando el proyecto lo necesita.
Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en la sección Sandbox de Qwen Code Docs y en la documentación de configuración y personalización del sandbox.
La documentación oficial define el sandboxing como la ejecución de operaciones potencialmente riesgosas dentro de un entorno aislado. Esto incluye, por ejemplo, comandos de shell o modificaciones de archivos realizadas por herramientas del agente.
La idea central es simple: aunque Qwen Code tenga permiso para actuar, no siempre conviene que lo haga directamente sobre el sistema anfitrión. El sandbox crea una capa de contención para reducir impacto, limitar superficie de riesgo y volver más seguro el trabajo automatizado.
Approval mode define cuánto poder le das al agente. El sandbox define dónde y bajo qué aislamiento puede ejercer ese poder.
Conviene no confundir sandboxing con approval modes. Son mecanismos distintos:
Por eso pueden combinarse de muchas maneras:
En términos de seguridad real, usar aprobación prudente y sandbox suele ser bastante más sólido que confiar solo en uno de los dos mecanismos.
La documentación oficial explica tres mecanismos principales de activación, con un orden de precedencia específico.
GEMINI_SANDBOX-s o --sandboxtools.sandbox en settings.jsonEjemplos:
qwen --sandbox
qwen --sandbox=docker
qwen -s
export GEMINI_SANDBOX=true
qwen -p "ejecuta la suite de pruebas"
{
"tools": {
"sandbox": true
}
}La documentación remarca un punto importante: si GEMINI_SANDBOX está definido, sobrescribe al flag del CLI y al valor del archivo de configuración.
La referencia oficial admite varios valores para esta variable, no solo true o false.
| Valor | Significado | Comentario |
|---|---|---|
true |
Activa sandbox y deja que el sistema elija provider automáticamente. | Conveniente para empezar. |
false |
Desactiva sandbox. | Menor aislamiento. |
docker |
Fuerza el uso de Docker. | Requiere Docker instalado. |
podman |
Fuerza el uso de Podman. | Requiere Podman instalado. |
sandbox-exec |
Fuerza el provider de macOS Seatbelt. | Aplica en entornos compatibles. |
| cadena personalizada | Define un comando provider específico. | Uso más avanzado. |
La documentación oficial describe un comportamiento diferente según el sistema operativo cuando se usa GEMINI_SANDBOX=true.
sandbox-exec si está disponible.Esto significa que “activar sandbox” no garantiza por sí solo que el aislamiento vaya a funcionar. También hace falta que el provider correspondiente exista y esté operativo en la máquina.
La documentación indica que el sandbox está desactivado por defecto, pero también aclara otro detalle importante: cuando se usa --yolo o --approval-mode=yolo, el sandbox se habilita por defecto.
La lógica es coherente: si vas a darle al agente el máximo nivel de autonomía, conviene agregar automáticamente una capa de aislamiento.
YOLO sin sandbox sería una combinación demasiado agresiva para muchos entornos. Por eso la documentación asocia ambos mecanismos de forma predeterminada.
Cuando se usa un provider basado en contenedores, la documentación oficial explica que Qwen Code utiliza una imagen por defecto incluida o referenciada por el paquete CLI. En la documentación reciente se mencionan imágenes como ghcr.io/qwenlm/qwen-code:<version> o equivalentes preconstruidos.
En términos prácticos, esto significa que no hace falta construir un contenedor propio para empezar. El usuario puede activar el sandbox y dejar que Qwen Code arranque con la imagen base prevista por el proyecto.
La documentación no presenta Docker y Podman como herramientas conceptualmente distintas para el usuario final de Qwen Code. Ambos cumplen el rol de provider de sandbox basado en contenedores.
Desde una perspectiva práctica:
Qwen Code puede trabajar con cualquiera de los dos si están correctamente instalados y disponibles en el sistema.
La documentación de sandbox menciona la variable de entorno SANDBOX_FLAGS para inyectar flags personalizados al comando docker o podman.
Esto es útil cuando necesitás adaptar el entorno de ejecución sin reescribir toda la lógica del provider. Por ejemplo, para montar volúmenes adicionales o pasar ciertos parámetros del runtime del contenedor.
export GEMINI_SANDBOX=docker
export SANDBOX_FLAGS="--cpus=2 --memory=4g"
qwen
Es una herramienta potente, pero conviene usarla con criterio, porque cuanto más se personaliza el runtime, más complejo puede volverse el diagnóstico de problemas.
La documentación oficial de configuración explica que, para necesidades específicas del proyecto, se puede crear un Dockerfile personalizado en:
.qwen/sandbox.Dockerfile
Ejemplo documentado:
FROM qwen-code-sandbox
# Agrega dependencias o herramientas extra
# RUN apt-get update && apt-get install -y some-package
En documentación más reciente del área de sandbox también se muestra el uso de la imagen publicada en GitHub Container Registry, por ejemplo:
FROM ghcr.io/qwenlm/qwen-code:sha-570ec43
RUN apt-get update && apt-get install -y \
git \
python3 \
ripgrep
La idea es muy útil: si tu proyecto necesita herramientas concretas dentro del entorno aislado, podés prepararlas de antemano y no depender del contenedor base “genérico”.
La documentación oficial describe el uso de BUILD_SANDBOX para construir automáticamente la imagen del sandbox cuando existe un Dockerfile personalizado. Ejemplo:
GEMINI_SANDBOX=docker BUILD_SANDBOX=1 qwen -s
Sin embargo, la documentación para desarrolladores también aclara una limitación importante al 12 de marzo de 2026: el proyecto no soporta cómodamente el uso de esta función después de la instalación por npm sin apoyarse en scripts del código fuente o en un entorno de desarrollo específico.
En otras palabras, personalizar el sandbox es posible, pero entrar en ese terreno ya es bastante más avanzado que simplemente activar Docker o Podman.
Más allá de la teoría, el sandbox aporta ventajas muy concretas:
Esto es especialmente valioso en tareas como:
También conviene dejar claros sus límites. El sandbox no reemplaza:
Es decir, el sandbox reduce riesgos, pero no convierte en inocua cualquier automatización. La seguridad operativa sigue dependiendo del conjunto completo de decisiones que rodean el uso del agente.
Cuando el sandbox no funciona, los problemas suelen concentrarse en unos pocos puntos repetidos.
| Problema | Causa probable | Primer paso razonable |
|---|---|---|
| El sandbox no arranca | Docker o Podman no están instalados o no están operativos. | Verificar el provider local antes de lanzar Qwen Code. |
GEMINI_SANDBOX=true no produce aislamiento |
El sistema no encuentra un provider compatible. | Forzar docker, podman o sandbox-exec según el sistema. |
| El entorno aislado no tiene una herramienta necesaria | La imagen base no incluye esa dependencia. | Crear o ajustar .qwen/sandbox.Dockerfile. |
| El comportamiento cambia respecto del sistema anfitrión | El contenedor tiene un entorno distinto, como era esperable. | Revisar imagen, flags y dependencias disponibles dentro del sandbox. |
Estas reglas suelen funcionar bien en casi cualquier contexto real:
El sandboxing agrega una capa de aislamiento muy importante al uso de Qwen Code. No reemplaza approvals, trusted folders ni criterio humano, pero reduce considerablemente el riesgo operativo cuando el agente ejecuta comandos o aplica cambios sobre el proyecto.
En este tema vimos las ideas centrales:
GEMINI_SANDBOX admite selección automática o providers específicos.SANDBOX_FLAGS y .qwen/sandbox.Dockerfile permiten personalización avanzada.Con esta base, el siguiente paso natural es pasar al modo no interactivo y a la automatización, donde muchas de estas decisiones de seguridad vuelven a ser especialmente importantes.