Sandboxes de Docker Desktop (obsoleto)

Warning

Los comandos docker sandbox integrados en Docker Desktop están obsoletos y han sido reemplazados por la CLI independiente sbx. Esta obsolescencia se aplica únicamente a la integración con Docker Desktop, no a Docker Sandboxes.

Esta página cubre el comando docker sandbox integrado en Docker Desktop para ejecutar agentes de codificación de IA en microVMs aisladas. Esta integración ha sido superada por la CLI independiente sbx, la cual proporciona el flujo de trabajo completo de Docker Sandboxes y no requiere Docker Desktop.

Note

Utiliza la CLI independiente sbx para los flujos de trabajo de agentes de IA en sandbox.

Requisitos previos

• Docker Desktop 4.58 o posterior
• macOS o Windows
• Claves de API para el agente elegido

Inicio rápido

1. Configura tu clave de API en tu archivo de configuración de shell:

   ~/.bashrc o ~/.zshrc

   export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx

   Carga la configuración de tu shell (source) y reinicia Docker Desktop para que el demonio detecte la variable.

2. Crea y ejecuta un sandbox:

   $ cd ~/mi-proyecto
   $ docker sandbox run claude
   

   La primera ejecución tarda más mientras Docker inicializa la microVM.

Reemplaza claude con un agente diferente si es necesario.

Agentes compatibles

El tipo de agente se especifica al crear un sandbox y no se puede cambiar más adelante.

Autenticación

Cada agente requiere su propia clave de API o credenciales. Docker Sandboxes utiliza un demonio que no hereda las variables de entorno de tu sesión de shell, por lo que debes configurar las claves en tu archivo de configuración de shell (no solo exportarlas en tu terminal).

Variables de entorno comunes por agente:

Después de configurar las variables, vuelve a cargar la configuración de tu shell y reinicia Docker Desktop. El proxy del sandbox inyecta las credenciales en las solicitudes de API, por lo que las claves permanecen en tu host y nunca se almacenan dentro del sandbox.

Comandos

$ docker sandbox run AGENTE [RUTA]                 # Crear y ejecutar
$ docker sandbox ls                                # Listar sandboxes
$ docker sandbox exec -it <nombre> bash             # Entrar al shell de un sandbox
$ docker sandbox rm <nombre>                        # Eliminar un sandbox
$ docker sandbox reset                             # Eliminar todos los sandboxes
$ docker sandbox network proxy <nombre> --policy … # Configurar política de red
$ docker sandbox network log                       # Ver el registro de red

Los sandboxes no aparecen en docker ps porque son microVMs, no contenedores. Para ver la referencia completa de comandos, consulta la referencia de CLI.

Pasa opciones de CLI específicas del agente después del nombre del sandbox con un separador --:

$ docker sandbox run <nombre> -- --continue

Arquitectura

Cada sandbox es una microVM ligera con su propio kernel, que utiliza la virtualización nativa de tu sistema (virtualization.framework en macOS, Hyper-V en Windows). Las plantillas de agente predeterminadas incluyen un demonio de Docker privado, por lo que docker build y docker compose up se ejecutan dentro del sandbox sin afectar a tu host.

Sistema host
  ├── Tus contenedores e imágenes
  ├── Sandbox VM 1
  │   ├── Demonio de Docker (aislado)
  │   ├── Contenedor del agente
  │   └── Contenedores creados por el agente
  └── Sandbox VM 2
      ├── Demonio de Docker (aislado)
      └── Contenedor del agente

Tu espacio de trabajo se sincroniza bidireccionalmente entre el host y el sandbox en la misma ruta absoluta. La conexión a Internet saliente pasa a través de un proxy de filtrado HTTP/HTTPS en el host. Consulta Políticas de red para su configuración.

Políticas de red

El proxy de filtrado controla a qué puede acceder un sandbox. De forma predeterminada, se permite todo el tráfico excepto a redes privadas y localhost.

Modo permitir (bloquear destinos específicos):

$ docker sandbox network proxy mi-sandbox \
  --policy allow \
  --block-cidr 10.0.0.0/8

Modo denegar (permitir destinos específicos):

$ docker sandbox network proxy mi-sandbox \
  --policy deny \
  --allow-host api.anthropic.com \
  --allow-host "*.npmjs.org"

Ver a qué está accediendo un agente:

$ docker sandbox network log

Plantillas personalizadas

Crea plantillas personalizadas para preinstalar herramientas:

FROM docker/sandbox-templates:claude-code

USER root
RUN apt-get update && apt-get install -y build-essential \
    && rm -rf /var/lib/apt/lists/*
USER agent

$ docker build -t mi-plantilla:v1 .
$ docker sandbox run -t mi-plantilla:v1 claude ~/proyecto

Entorno base

Todas las plantillas de agentes comparten un entorno común:

• Ubuntu 25.10
• CLI de Docker (con Buildx y Compose), Git, CLI de GitHub, Node.js, Go, Python 3, uv, make, jq, ripgrep
• Usuario agent sin privilegios de root pero con acceso a sudo
• Gestores de paquetes: apt, pip, npm

Resolución de problemas

'sandbox' no es un comando de docker

El complemento de la CLI no está instalado o no se encuentra en la ubicación correcta. Verifica que el complemento exista en ~/.docker/cli-plugins/docker-sandbox y reinicia Docker Desktop.

Las características beta deben estar habilitadas

Si tu Docker Desktop es administrado por un administrador con Gestión de configuración, pídeles que permitan las características beta.

Fallo de autenticación

Verifica que tu clave de API sea válida y esté configurada en tu archivo de configuración de shell (no solo exportada en la sesión actual). Carga el archivo de configuración y reinicia Docker Desktop.

Permiso denegado en los archivos del espacio de trabajo

Ve a Docker Desktop > Settings > Resources > File Sharing y asegúrate de que la ruta de tu espacio de trabajo esté en la lista. Verifica los permisos de los archivos con ls -la.

El sandbox se bloquea en Windows

Si el lanzamiento de múltiples sandboxes provoca bloqueos, finaliza todos los procesos docker.openvmm.exe en el Administrador de tareas y reinicia Docker Desktop. Lanza los sandboxes de uno en uno.

Problemas persistentes

Restablece todo el estado de los sandboxes:

$ docker sandbox reset

Esto detiene todas las VMs y elimina todos los datos de los sandboxes. Crea sandboxes nuevos después de esto.