Primeros pasos con Docker Sandboxes

Docker Sandboxes ejecuta agentes de codificación de IA en entornos de pruebas (sandboxes) aislados de microVM. Cada sandbox cuenta con su propio demonio de Docker, sistema de archivos y red: el agente puede compilar contenedores, instalar paquetes y modificar archivos sin tocar tu sistema host.

Esta página describe una sesión inicial típica: instalar la CLI, autenticar el agente, ejecutar un sandbox, trabajar con ramas y realizar la limpieza.

Requisitos previos

Una clave de API o método de autenticación para el agente que deseas utilizar. La mayoría de los agentes requieren una clave de API para su proveedor de modelos (Anthropic, OpenAI, Google y otros). Consulta las páginas de agentes para obtener instrucciones específicas del proveedor.

Docker Desktop no es necesario para usar sbx.

Instalación e inicio de sesión

$ brew install docker/tap/sbx
$ sbx login

> winget install -h Docker.sbx
> sbx login

$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
$ sudo apt-get install docker-sbx
$ sbx login

Si necesitas instalar sbx manualmente, descarga un binario directamente desde el repositorio sbx-releases.

sbx login abre un navegador para la autenticación OAuth de Docker. En el primer inicio de sesión (y después de sbx policy reset), la CLI te pedirá que elijas una política de red predeterminada para tus sandboxes:

Choose a default network policy:

     1. Open         — All network traffic allowed, no restrictions.
     2. Balanced     — Default deny, with common dev sites allowed.
     3. Locked Down  — All network traffic blocked unless you allow it.

Use ↑/↓ to navigate, Enter to select, or press 1–3.

Balanced es un buen punto de partida: permite el tráfico a los servicios de desarrollo habituales mientras bloquea todo lo demás. Puedes ajustar las reglas individuales más adelante. Consulta Políticas para obtener una descripción completa de cada opción.

Note

Consulta las Preguntas frecuentes para obtener detalles sobre por qué es necesario iniciar sesión y qué ocurre con tus datos.

Autenticación del agente

Los agentes necesitan credenciales para su proveedor de modelos. La forma de proporcionarlas depende del agente.

Para Claude Code con una suscripción de Claude (Max, Team o Enterprise), no es necesaria una configuración previa: utiliza el comando /login dentro del sandbox para iniciar sesión con OAuth. El token de sesión permanece en tu host y es inyectado por un proxy, no se almacena dentro del sandbox.

Para los agentes que utilizan claves de API (o si prefieres la autenticación por clave de API para Claude Code), almacena la clave antes de iniciar un sandbox:

$ sbx secret set -g anthropic

Esto solicitará el valor del secreto y lo almacenará en el llavero de tu sistema operativo. Un proxy en tu host inyecta la clave en las solicitudes de API salientes, por lo que nunca se expone dentro del sandbox. Consulta Credenciales para obtener detalles sobre el alcance, los servicios compatibles y los métodos alternativos.

Para dar acceso al agente a GitHub para crear pull requests o interactuar con repositorios:

$ sbx secret set -g github -t "$(gh auth token)"

Ejecución del primer sandbox

Elige un directorio de proyecto y lanza un agente con sbx run:

$ cd ~/mi-proyecto
$ sbx run claude

Reemplaza claude con el agente que deseas usar; consulta Agentes para ver la lista completa.

La primera ejecución tarda un poco más mientras se descarga la imagen del agente. Las ejecuciones posteriores reutilizan la imagen en caché y se inician en cuestión de segundos.

Puedes verificar qué se está ejecutando en cualquier momento:

$ sbx ls
SANDBOX              AGENT    STATUS    PORTS   WORKSPACE
claude-mi-proyecto   claude   running           ~/mi-proyecto

También puedes ejecutar sbx sin argumentos para abrir un panel de control interactivo. El panel muestra tus sandboxes con su estado en tiempo real, te permite acoplarte a los agentes, abrir shells y gestionar reglas de red desde un solo lugar. Consulta Modo interactivo para obtener más detalles.

Uso del modo de ramas (branch mode)

Por defecto, el agente edita tu árbol de trabajo directamente. Para darle su propia rama de Git, usa --branch:

$ sbx run claude --branch mi-caracteristica

Esto crea un Git worktree bajo .sbx/ en la raíz de tu repositorio. El agente trabaja en su propia rama y directorio sin tocar tu árbol de trabajo principal.

Cuando termine la sesión, revisa lo que hizo el agente desde el directorio de trabajo alternativo (worktree):

$ cd .sbx/<nombre-sandbox>-worktrees/mi-caracteristica
$ git log
$ git diff main

Si estás satisfecho, envía la rama y abre una solicitud de extracción (pull request):

$ git push -u origin mi-caracteristica
$ gh pr create

El modo de ramas es especialmente útil cuando se ejecutan múltiples agentes en el mismo repositorio: cada uno obtiene su propia rama y no pueden sobrescribir los cambios del otro. Consulta Modo de ramas para ver más opciones, incluyendo --branch auto y múltiples ramas por sandbox.

Gestión del acceso a la red

Tu política de red controla a qué puede acceder el sandbox. Si el agente no logra conectarse a una API o servicio, es muy probable que esté bloqueado por la política.

Verifica qué reglas están vigentes:

$ sbx policy ls

Para permitir un host específico:

$ sbx policy allow network -g registry.npmjs.org

Con Locked Down, incluso la API del proveedor de tu modelo está bloqueada a menos que la permitas explícitamente. Con Balanced, los servicios de desarrollo comunes están permitidos por defecto. Consulta Políticas para ver el conjunto de reglas completo y cómo personalizarlo.

Limpieza

Los sandboxes persisten después de que el agente finaliza. Para detener un sandbox sin eliminarlo:

$ sbx stop mi-sandbox

Los paquetes instalados, las imágenes de Docker y los cambios de configuración se conservan entre reinicios. Cuando hayas terminado con un sandbox, elimínalo para recuperar espacio en disco:

$ sbx rm mi-sandbox

Eliminar un sandbox borra todo lo que hay dentro: los paquetes instalados, las imágenes de Docker y cualquier directorio de trabajo (worktree) del modo de ramas bajo .sbx/. Los archivos en tu árbol de trabajo principal no se verán afectados.

Siguientes pasos

• Guía de uso — gestión de sandboxes, reconexión, múltiples espacios de trabajo, reenvío de puertos y más
• Agentes — agentes compatibles y configuración
• Personalización — compila plantillas reutilizables o declara capacidades con kits
• Credenciales — almacenamiento y gestión de credenciales
• Confianza en el espacio de trabajo — revisa los cambios del agente de forma segura
• Políticas — controla el acceso saliente