# 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

**macOS**



- macOS Sonoma (versión 14) o posterior
- Apple silicon

**Windows**



- Procesador Intel o AMD de 64 bits (x86_64)
- Windows 11
- Windows Hypervisor Platform habilitado. Abre una consola de PowerShell con privilegios elevados (Ejecutar como administrador) y ejecuta:
  ```powershell
  Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All
  ```

**Linux (Ubuntu)**



- Ubuntu 24.04 o posterior
- Procesador Intel o AMD de 64 bits (x86_64)
- Virtualización de hardware KVM compatible y habilitada por la CPU. Si estás ejecutando dentro de una VM, la virtualización anidada debe estar activada. Verifica que KVM esté disponible:
  ```console
  $ lsmod | grep kvm
  ```
  Una configuración correcta muestra `kvm_intel` o `kvm_amd` en la salida. Si la salida está vacía, ejecuta `kvm-ok` para el diagnóstico. Si KVM no está disponible, `sbx` no se iniciará.
- Tu usuario debe pertenecer al grupo `kvm`:
  ```console
  $ sudo usermod -aG kvm $USER
  ```
  Cierra la sesión y vuelve a iniciarla (o ejecuta `newgrp kvm`) para que el cambio de grupo surta efecto.



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](/ai/sandboxes/get-started/agents) para obtener instrucciones específicas del proveedor.

Docker Desktop no es necesario para usar `sbx`.

## Instalación e inicio de sesión

**macOS**



```console
$ brew install docker/tap/sbx
$ sbx login
```

**Windows**



```powershell
> winget install -h Docker.sbx
> sbx login
```

**Linux (Ubuntu)**



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

El primer comando añade el repositorio `apt` de Docker a tu sistema.



Si necesitas instalar `sbx` manualmente, descarga un binario directamente desde el repositorio [sbx-releases](https://github.com/docker/sbx-releases/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:

```plaintext
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](/ai/sandboxes/get-started/security/policy/) para obtener una descripción completa de cada opción.

> [!NOTE]
> Consulta las [Preguntas frecuentes](/ai/sandboxes/get-started/faq/) 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:

```console
$ 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](/ai/sandboxes/get-started/security/credentials/) 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:

```console
$ 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`](/reference/cli/sbx/run/):

```console
$ cd ~/mi-proyecto
$ sbx run claude
```

Reemplaza `claude` con el agente que deseas usar; consulta [Agentes](/ai/sandboxes/get-started/agents) 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:

```console
$ 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](/ai/sandboxes/get-started/usage/#interactive-mode) para obtener más detalles.

![El panel de control interactivo que muestra el estado del sandbox, el uso de recursos y los controles de gobernanza de la red.](/ai/sandboxes/get-started/images/sbx-dashboard.png)

## 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`:

```console
$ sbx run claude --branch mi-caracteristica
```

Esto crea un [Git worktree](https://git-scm.com/docs/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):

```console
$ 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):

```console
$ 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](/ai/sandboxes/get-started/usage/#branch-mode) 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:

```console
$ sbx policy ls
```

Para permitir un host específico:

```console
$ 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](/ai/sandboxes/get-started/security/policy/) 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:

```console
$ 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:

```console
$ 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](/ai/sandboxes/get-started/usage/) — gestión de sandboxes, reconexión, múltiples espacios de trabajo, reenvío de puertos y más
- [Agentes](/ai/sandboxes/get-started/agents) — agentes compatibles y configuración
- [Personalización](/ai/sandboxes/get-started/customize) — compila plantillas reutilizables o declara capacidades con kits
- [Credenciales](/ai/sandboxes/get-started/security/credentials/) — almacenamiento y gestión de credenciales
- [Confianza en el espacio de trabajo](/ai/sandboxes/get-started/security/workspace/) — revisa los cambios del agente de forma segura
- [Políticas](/ai/sandboxes/get-started/security/policy/) — controla el acceso saliente