# Uso ## Trabajar con sandboxes El flujo de trabajo básico consiste en usar [`run`](/reference/cli/sbx/run/) para iniciar, [`ls`](/reference/cli/sbx/ls/) para comprobar el estado, [`stop`](/reference/cli/sbx/stop/) para pausar y [`rm`](/reference/cli/sbx/rm/) para limpiar: ```console $ 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): ```console $ sbx exec -it bash ``` Si necesitas empezar de cero, elimina el sandbox y vuelve a ejecutar: ```console $ 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`: ```console $ echo "$DOCKER_PAT" | sbx login --username --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](https://app.docker.com/settings/personal-access-tokens) con al menos el alcance de **Lectura** (Read). ## Modo interactivo Ejecutar `sbx` sin subcomandos abre un panel de control interactivo en la terminal: ```console $ 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](#modo-de-ramas-branch-mode) 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](#modo-de-ramas-branch-mode) como alternativa. ### Modo de ramas (branch mode) Pasa `--branch ` para darle al agente su propio [Git worktree](https://git-scm.com/docs/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 ```console $ 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: ```console $ sbx run claude --branch auto ``` También puedes crear el sandbox primero y añadir una rama al ejecutarlo: ```console $ 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: ```console $ 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: ```console $ 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í: ```console $ git worktree list # encontrar la ruta del worktree $ cd .sbx/-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](/ai/sandboxes/usage/security/workspace/) 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: ```console $ echo '.sbx/' >> .gitignore ``` O bien, para ignorarlo en todos los repositorios, añade `.sbx/` a tu archivo global de gitignore: ```console $ 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: ```console $ ssh-add ~/.ssh/id_ed25519 ``` Dentro del sandbox, verifica que el agente reenviado exponga la clave: ```console $ 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: ```console $ 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: ```console $ git commit -S ``` Para fallos de firma comunes, consulta [Las confirmaciones del sandbox no están firmadas](/ai/sandboxes/usage/troubleshooting/#las-confirmaciones-commits-del-sandbox-no-estan-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: ```console $ 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: ```console $ sbx run claude --name mi-proyecto ``` ## Creación sin acoplarse [`sbx run`](/reference/cli/sbx/run/) crea el sandbox y te conecta al agente. Para crear un sandbox en segundo plano sin acoplarte: ```console $ 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](#modo-de-ramas-branch-mode). Conéctate más tarde usando `sbx run`: ```console $ 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): ```console $ 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: ```console $ sbx run claude ~/proyecto-a $ sbx run claude ~/proyecto-b $ sbx rm # al finalizar ``` ## Copiar archivos entre el host y el sandbox Usa [`sbx cp`](/reference/cli/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. ```console $ 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](/ai/sandboxes/usage/customize) para plantillas reutilizables y kits declarativos. Los agentes también pueden compilar imágenes de Docker, ejecutar contenedores y usar [Compose](https://docs-docker.esdocu.com/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](/ai/sandboxes/usage/security/isolation/); tu navegador o las herramientas locales no pueden acceder por defecto a un servidor que se ejecute en su interior. Usa [`sbx ports`](/reference/cli/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. ```console $ 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: ```console $ 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: ```console $ 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: ```console $ 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: ```console $ 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: ```console $ 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](/ai/sandboxes/usage/customize) 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](/ai/sandboxes/usage/security/governance/) 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](/ai/sandboxes/usage/customize/templates/).