Uso

Trabajar con sandboxes

El flujo de trabajo básico consiste en usar run para iniciar, ls para comprobar el estado, stop para pausar y rm para limpiar:

$ sbx run claude                    # iniciar un agente
$ sbx ls                            # ver qué se está ejecutando
$ sbx stop mi-sandbox               # pausarlo
$ sbx rm mi-sandbox                 # eliminarlo por completo

Para abrir una consola (shell) dentro de un sandbox en ejecución (útil para inspeccionar el entorno, verificar contenedores de Docker o instalar manualmente algún componente):

$ sbx exec -it <nombre-sandbox> bash

Si necesitas empezar de cero, elimina el sandbox y vuelve a ejecutar:

$ sbx rm mi-sandbox
$ sbx run claude

Inicio de sesión no interactivo

Para entornos de CI y scripts donde no hay un navegador disponible, utiliza un Token de Acceso Personal (PAT) de Docker con --username y --password-stdin:

$ echo "$DOCKER_PAT" | sbx login --username <tu-docker-id> --password-stdin

--password-stdin lee el token de la entrada estándar para evitar que se guarde en el historial de tu shell. Genera un PAT desde los ajustes de tu cuenta de Docker con al menos el alcance de Lectura (Read).

Modo interactivo

Ejecutar sbx sin subcomandos abre un panel de control interactivo en la terminal:

$ sbx

El panel de control muestra todos tus sandboxes como tarjetas con su estado en tiempo real, CPU y uso de memoria. Desde aquí puedes:

• Crear un sandbox (c).
• Iniciar o detener un sandbox (s).
• Acoplarte a la sesión de un agente (Enter), equivalente a sbx run.
• Abrir una consola (shell) dentro del sandbox (x), equivalente a sbx exec.
• Eliminar un sandbox (r).

El panel de control también incluye un panel de gobernanza de red donde puedes supervisar las conexiones salientes realizadas por tus sandboxes y gestionar las reglas de red. Usa tab para cambiar entre el panel de sandboxes y el panel de red.

Desde el panel de red puedes explorar los registros de conexión, permitir o bloquear hosts específicos y añadir reglas de red personalizadas. Presiona ? para ver todos los atajos de teclado.

Flujo de trabajo de Git

Cuando tu espacio de trabajo es un repositorio Git, el agente edita tu árbol de trabajo directamente de forma predeterminada. Los cambios aparecen en tu árbol de trabajo de inmediato, de la misma manera que si estuvieras trabajando en una terminal normal.

Si ejecutas múltiples agentes en el mismo repositorio a la vez, utiliza el modo de ramas para darle a cada agente su propia rama y directorio de trabajo.

Modo directo (predeterminado)

El agente edita tu árbol de trabajo directamente. Realiza git add, commit y push como lo harías normalmente. Si ejecutas múltiples agentes en el mismo repositorio al mismo tiempo, pueden interferir con los cambios del otro. Consulta el modo de ramas como alternativa.

Modo de ramas (branch mode)

Pasa --branch <nombre> para darle al agente su propio Git worktree y rama. Esto evita conflictos cuando varios agentes, o tú y un agente, escriben en los mismos archivos al mismo tiempo. Puedes configurar --branch en create, run o ambos.

La CLI crea los directorios de trabajo (worktrees) bajo .sbx/ en la raíz de tu repositorio. El worktree es un directorio de trabajo independiente, por lo que el agente no toca tu árbol de trabajo principal. Esto significa que:

• El worktree se desvía a partir de tu última confirmación en el momento de crearlo. Los cambios no confirmados en tu árbol de trabajo no se incluyen (sbx te advierte si detecta alguno).
• Los archivos que añadas o cambies en tu árbol de trabajo principal no serán visibles para el agente, y viceversa. Los dos directorios son independientes.

Iniciar una rama

$ sbx run claude --branch mi-caracteristica   # el agente trabaja en la rama mi-caracteristica

Utiliza --branch auto para que la CLI genere un nombre de rama automáticamente:

$ sbx run claude --branch auto

También puedes crear el sandbox primero y añadir una rama al ejecutarlo:

$ sbx create --name mi-sandbox claude .
$ sbx run --branch mi-caracteristica mi-sandbox

O configurar la rama al crear el sandbox y reutilizarla en las ejecuciones posteriores:

$ sbx create --name mi-sandbox --branch mi-caracteristica claude .
$ sbx run mi-sandbox                       # se reanuda en el worktree mi-caracteristica
$ sbx run --branch mi-caracteristica mi-sandbox   # equivalente: reutiliza el worktree existente

Múltiples ramas por sandbox

Puedes ejecutar múltiples directorios de trabajo (worktrees) en el mismo sandbox pasando diferentes nombres de rama:

$ sbx run --branch caracteristica-a mi-sandbox
$ sbx run --branch caracteristica-b mi-sandbox

Revisar y subir cambios

Para revisar el trabajo del agente, busca la ruta del worktree con git worktree list, y luego realiza push o abre una PR desde allí:

$ git worktree list                          # encontrar la ruta del worktree
$ cd .sbx/<nombre-sandbox>-worktrees/mi-caracteristica
$ git log                                    # ver qué hizo el agente
$ git push -u origin mi-caracteristica
$ gh pr create

Algunos agentes no confirman los cambios automáticamente y los dejan sin confirmar en el worktree. Si esto ocurre, realiza el commit desde el directorio del worktree antes de hacer push.

Consulta Confianza en el espacio de trabajo para conocer las consideraciones de seguridad al revisar los cambios del agente.

Limpieza

sbx rm elimina el sandbox y todos sus directorios de trabajo (worktrees) y ramas.

Ignorar el directorio .sbx/

El modo de ramas almacena los worktrees bajo .sbx/ en la raíz de tu repositorio. Para mantener este directorio fuera de git status, añádelo al archivo .gitignore de tu proyecto:

$ echo '.sbx/' >> .gitignore

O bien, para ignorarlo en todos los repositorios, añade .sbx/ a tu archivo global de gitignore:

$ echo '.sbx/' >> "$(git config --global core.excludesFile)"

Tip

Si git config --global core.excludesFile está vacío, configura uno primero: git config --global core.excludesFile ~/.gitignore.

También puedes crear los directorios de trabajo de Git tú mismo y ejecutar un agente directamente en uno de ellos, pero el sandbox no tendrá acceso al directorio .git del repositorio principal. Esto significa que el agente no podrá realizar commits, push ni usar Git. --branch soluciona esto configurando el worktree de modo que Git funcione dentro del sandbox.

Confirmaciones firmadas (signed commits)

Los sandboxes pueden firmar confirmaciones (commits) de Git con claves SSH del agente de tu host. La clave privada permanece en tu host.

En el host, carga la clave en tu agente SSH:

$ ssh-add ~/.ssh/id_ed25519

Dentro del sandbox, verifica que el agente reenviado exponga la clave:

$ ssh-add -L

Configura Git globalmente dentro del sandbox para usar la firma de confirmaciones SSH. Esto escribe en la configuración de Git del usuario del sandbox, no en el .git/config de tu repositorio. Utiliza una clave pública en línea en lugar de una ruta de archivo de clave, porque las rutas del host como ~/.ssh/id_ed25519.pub podrían no existir en el sandbox:

$ git config --global gpg.format ssh
$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"

Luego realiza el commit como de costumbre:

$ git commit -S

Para fallos de firma comunes, consulta Las confirmaciones del sandbox no están firmadas.

Reconexión y asignación de nombres

Los sandboxes persisten después de que el agente finaliza. Ejecutar de nuevo la misma ruta de espacio de trabajo se reconecta al sandbox existente en lugar de crear uno nuevo:

$ sbx run claude ~/mi-proyecto  # crea el sandbox
$ sbx run claude ~/mi-proyecto  # se reconecta al mismo sandbox

Utiliza --name para hacer esto explícito y evitar ambigüedades:

$ sbx run claude --name mi-proyecto

Creación sin acoplarse

sbx run crea el sandbox y te conecta al agente. Para crear un sandbox en segundo plano sin acoplarte:

$ sbx create claude .

A diferencia de run, create requiere una ruta de espacio de trabajo explícita. Utiliza el modo directo de forma predeterminada, o pasa --branch para el modo de ramas. Conéctate más tarde usando sbx run:

$ sbx run claude-mi-proyecto

Múltiples espacios de trabajo

Puedes montar directorios adicionales en un sandbox junto con el espacio de trabajo principal. La primera ruta es el espacio de trabajo primario; el agente se inicia aquí y el worktree de Git del sandbox se crea a partir de este directorio si utilizas --branch. Los espacios de trabajo adicionales siempre se montan directamente.

Todos los espacios de trabajo aparecen dentro del sandbox en sus rutas absolutas del host. Asegúrate de añadir :ro para montar un espacio de trabajo adicional en modo de solo lectura (útil para material de referencia o bibliotecas compartidas que el agente no debe modificar):

$ sbx run claude ~/proyecto-a ~/shared-libs:ro ~/docs:ro

Cada sandbox está completamente aislado, por lo que también puedes ejecutar proyectos independientes en paralelo. Elimina los sandboxes que no uses cuando hayas terminado para recuperar espacio en disco:

$ sbx run claude ~/proyecto-a
$ sbx run claude ~/proyecto-b
$ sbx rm <nombre-sandbox>       # al finalizar

Copiar archivos entre el host y el sandbox

Usa sbx cp para copiar archivos o directorios entre tu host y un sandbox. Esto es útil para archivos puntuales que no forman parte de un espacio de trabajo montado, como resultados generados, registros (logs) o archivos de configuración.

$ sbx cp ./config.json mi-sandbox:/home/user/
$ sbx cp mi-sandbox:/home/user/output.log ./
$ sbx cp ./src/ mi-sandbox:/home/user/src

Uno de los lados de la copia debe usar el formato SANDBOX:RUTA. No se admite la copia directa entre dos sandboxes.

Instalar dependencias y usar Docker

Pídele al agente que instale lo que necesite: tiene acceso a sudo y los paquetes instalados persisten durante la vida útil del sandbox. Para equipos o entornos repetibles, consulta Personalización para plantillas reutilizables y kits declarativos.

Los agentes también pueden compilar imágenes de Docker, ejecutar contenedores y usar Compose. Todo se ejecuta dentro del demonio de Docker privado del sandbox, por lo que los contenedores iniciados por el agente nunca aparecerán en el docker ps de tu host. Cuando eliminas el sandbox, todas las imágenes, contenedores y volúmenes de su interior se eliminan con él.

Acceder a servicios dentro del sandbox

Los sandboxes están aislados de la red; tu navegador o las herramientas locales no pueden acceder por defecto a un servidor que se ejecute en su interior. Usa sbx ports para reenviar tráfico desde tu host hacia un sandbox en ejecución.

El caso común: un agente ha iniciado un servidor de desarrollo o una API, y deseas abrirlo en tu navegador o ejecutar pruebas contra él.

$ sbx ports mi-sandbox --publish 8080:3000   # host 8080 → puerto del sandbox 3000
$ open http://localhost:8080

Para permitir que el sistema operativo elija un puerto de host libre en lugar de elegir uno tú mismo:

$ sbx ports my-sandbox --publish 3000        # puerto de host efímero
$ sbx ports my-sandbox                       # comprobar qué puerto fue asignado

sbx ls muestra las asociaciones de puertos activas junto a cada sandbox, y sbx ports las detalla:

$ sbx ls
SANDBOX         AGENT   STATUS   PORTS                    WORKSPACE
my-sandbox      claude  running  127.0.0.1:8080->3000/tcp /home/user/proj

Para dejar de reenviar un puerto:

$ sbx ports my-sandbox --unpublish 8080:3000

Algunas cosas a tener en cuenta:

• Los servicios deben enlazarse a 0.0.0.0 — un servicio que escuche en 127.0.0.1 dentro del sandbox no será accesible a través de un puerto publicado. La mayoría de los servidores de desarrollo escuchan en 127.0.0.1 por defecto, por lo que generalmente necesitarás pasar una bandera como --host 0.0.0.0 al iniciarlos.
• No es persistente — los puertos publicados se pierden cuando el sandbox se detiene o el demonio se reinicia. Vuelve a publicarlos después de reiniciar.
• Sin bandera en la creación — a diferencia de docker run -p, no hay una opción --publish en sbx run o sbx create. Los puertos solo se pueden publicar después de que el sandbox se esté ejecutando.
• La eliminación requiere el puerto de host — --unpublish 3000 es rechazado; debes usar --unpublish 8080:3000. Ejecuta primero sbx ports mi-sandbox si utilizaste un puerto efímero y necesitas encontrar el puerto de host asignado.

Acceder a servicios del host desde un sandbox

Los servicios que se ejecutan en tu host son accesibles desde el interior de un sandbox utilizando el nombre de host host.docker.internal. Usa esto en lugar de 127.0.0.1 o de la dirección IP de la red local de tu máquina, las cuales no son accesibles desde el interior del sandbox.

El proxy del sandbox traduce host.docker.internal a localhost antes de reenviar la solicitud, por lo que debes añadir la dirección localhost con el puerto específico a la lista de permitidos de tu política de red:

$ sbx policy allow network -g localhost:11434

Luego, utiliza host.docker.internal en cualquier configuración o solicitud que apunte al servicio del host. Por ejemplo, para verificar la conectividad desde una consola de sandbox:

$ curl http://host.docker.com:11434

Implementación para un equipo

Al implementar los sandboxes en un equipo, dos características cubren diferentes necesidades:

• Las plantillas y kits personalizados te permiten empaquetar configuraciones de agentes reutilizables, servidores MCP, imágenes base y políticas por proyecto. Cada desarrollador los descarga junto con su espacio de trabajo.
• La gobernanza de la organización permite a los administradores definir reglas de red y del sistema de archivos en la Consola de Administración de Docker. Las reglas se aplican en los sandboxes de todos los desarrolladores y tienen prioridad sobre la política local. Disponible mediante una suscripción de pago independiente.

La personalización proporciona puntos de partida compartidos a los desarrolladores. La gobernanza proporciona una aplicación centralizada a los administradores.

Qué persiste

Mientras exista un sandbox, los paquetes instalados, las imágenes de Docker, los cambios de configuración y el historial de comandos persisten tras las detenciones y reinicios. Cuando eliminas un sandbox, todo lo que contiene se borra; solo tus archivos del espacio de trabajo permanecen en tu host. Para conservar un entorno configurado, crea una plantilla personalizada.