# Plantillas Cada sandbox es personalizable: los agentes instalan paquetes, descargan imágenes y configuran herramientas mientras trabajan, y esos cambios persisten durante la vida útil del sandbox. Las plantillas capturan un entorno configurado en una imagen reutilizable para que no tengas que configurarlo de nuevo cada vez. ## Plantillas personalizadas Las plantillas personalizadas son imágenes de sandbox reutilizables que extienden uno de los entornos de agentes integrados con herramientas y configuraciones adicionales incorporadas. En lugar de pedirle al agente que instale paquetes cada vez, compila una plantilla una vez y reutilízala en diferentes sandboxes y miembros del equipo. Las plantillas tienen sentido cuando varias personas necesitan el mismo entorno, cuando la configuración implica pasos tediosos de repetir, o cuando necesitas versiones fijas de herramientas específicas. Para trabajos puntuales, la imagen predeterminada es adecuada; pídele al agente que instale lo que necesite. > [!NOTE] > Las plantillas privadas solo se aplican al entorno de un agente existente, no crean nuevos entornos de ejecución de agentes. El agente que se inicia dentro del sandbox se determina por la variante de la imagen base que amplías y el agente que especificas en el comando `sbx run`, no por los binarios instalados en la plantilla. Para definir un nuevo agente desde cero, consulta [Kits](/ai/sandboxes/customize/templates/kits/#definir-un-agente). ### Imágenes base Todas las plantillas de sandbox se publican como `docker/sandbox-templates:`. Están basadas en Ubuntu y se ejecutan como un usuario `agent` sin privilegios de root con acceso a sudo. La mayoría de las variantes incluyen Git, la CLI de Docker y herramientas de desarrollo comunes como Node.js, Python, Go y Java. | Variante | Agente | | :-------------------- | :---------------------------------------------------------------------------------- | | `claude-code` | [Claude Code](https://claude.ai/download) | | `claude-code-minimal` | Claude Code con un conjunto mínimo de herramientas (sin Node.js, Python, Go o Java) | | `codex` | [OpenAI Codex](https://github.com/openai/codex) | | `copilot` | [GitHub Copilot](https://github.com/github/copilot-cli) | | `cursor-agent` | [Cursor](https://cursor.com/cli) | | `docker-agent` | [Docker Agent](https://github.com/docker/docker-agent) | | `droid` | [Droid](https://www.factory.ai) | | `gemini` | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | | `kiro` | [Kiro](https://kiro.dev) | | `opencode` | [OpenCode](https://opencode.ai) | | `shell` | Sin agente preinstalado. Úsala para la configuración manual del agente. | Cada variante también tiene una versión `-docker` (por ejemplo, `claude-code-docker`) que incluye un motor Docker Engine completo ejecutándose dentro del sandbox, sin necesidad de un demonio Docker local. Cuando eliges un agente integrado sin especificar una plantilla personalizada, `sbx run` y `sbx create` utilizan las variantes de plantilla `-docker` de forma predeterminada. Los contenedores de agentes creados a partir de las plantillas `-docker` se ejecutan en modo privilegiado dentro de la microVM (not en tu host), con un volumen de bloque dedicado en `/var/lib/docker`, y `dockerd` se inicia automáticamente dentro del sandbox. El volumen de bloque tiene un tamaño predeterminado de 50 GB y utiliza un archivo disperso (sparse file), por lo que solo consume espacio en disco a medida que Docker escribe en él. Para anular el tamaño del volumen, configura la variable de entorno `DOCKER_SANDBOXES_DOCKER_SIZE` con una cadena de tamaño antes de iniciar el sandbox: ```console $ DOCKER_SANDBOXES_DOCKER_SIZE=10g sbx run claude ``` Usa la variante sin Docker si no necesitas compilar o ejecutar contenedores dentro del sandbox y prefieres un entorno más ligero y sin privilegios. Especifícala explícitamente con `--template`: ```console $ sbx run claude --template docker.io/docker/sandbox-templates:claude-code ``` ### Compilar una plantilla personalizada Compilar una plantilla personalizada requiere [Docker Desktop](https://docs-docker.esdocu.com/desktop/). Escribe un Dockerfile que amplíe una de las imágenes base. Elige la variante que coincida con el agente que planeas ejecutar. Por ejemplo, amplía `claude-code` para personalizar un entorno de Claude Code, o `codex` para personalizar un entorno de OpenAI Codex. El siguiente ejemplo crea una plantilla de Claude Code con Rust y herramientas de búfer de protocolo (protocol buffers) preinstaladas: ```dockerfile FROM docker/sandbox-templates:claude-code USER root RUN apt-get update && apt-get install -y protobuf-compiler USER agent RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y ``` Usa `root` para las instalaciones de paquetes a nivel de sistema (`apt-get`), y vuelve a cambiar a `agent` antes de instalar herramientas a nivel de usuario. Las herramientas que se instalan en el directorio de inicio, como `rustup`, `nvm` o `pyenv`, deben ejecutarse como `agent`; de lo contrario, se instalarán bajo `/root/` y no estarán disponibles en el sandbox. Compila la imagen y súbela a un registro OCI, como Docker Hub: ```console $ docker build -t mi-org/mi-plantilla:v1 --push . ``` > [!NOTE] > El demonio de Docker utilizado por Docker Sandboxes descarga las plantillas directamente desde un registro; no comparte el almacén de imágenes de tu demonio de Docker local en el host. > [!IMPORTANT] > Las plantillas privadas solo son compatibles con Docker Hub. `sbx` reutiliza tu sesión de `sbx login` para descargar imágenes privadas de Docker Hub. Otros registros (como GitHub Container Registry, ECR o un registro autohospedado como Nexus) se descargan de forma anónima, por lo que las descargas de imágenes privadas en esos registros fallarán. Para imágenes compiladas localmente o imágenes privadas en registros con los que `sbx` no pueda autenticarse, guarda la imagen en un archivo tar y cárgala directamente en el entorno de ejecución del sandbox en lugar de descargarla desde un registro: ```console $ docker image save mi-org/mi-plantilla:v1 -o mi-plantilla.tar $ sbx template load mi-plantilla.tar $ sbx run --template mi-org/mi-plantilla:v1 claude ``` `sbx template load` importa el archivo tar en el almacén de imágenes del entorno de ejecución del sandbox, por lo que la imagen no necesita ser accesible desde un registro en el momento de crear el sandbox. A menos que utilices la política de red permisiva `allow-all`, es posible que también debas añadir a la lista de permitidos los dominios de los que dependan tus herramientas personalizadas: ```console $ sbx policy allow network -g "*.example.com:443,example.com:443" ``` Luego, ejecuta un sandbox con tu plantilla. El agente que especifiques debe coincidir con la variante de la imagen base que amplía tu plantilla: ```console $ sbx run --template docker.io/mi-org/mi-plantilla:v1 claude ``` Debido a que esta plantilla amplía la imagen base `claude-code`, la ejecutas con `claude`. Si amplías `codex`, usa `codex`; si amplías `shell`, usa `shell` (que te introduce en una consola Bash sin agente). > [!NOTE] > A diferencia de los comandos de Docker, `sbx` no resuelve automáticamente el dominio de Docker Hub (`docker.io`) en las referencias de imágenes. ### Caché de plantillas Las imágenes de plantilla se almacenan en caché localmente. El primer uso las descarga desde el registro; los sandboxes posteriores reutilizan la caché. Las imágenes almacenadas en caché persisten a lo largo de la creación y eliminación de sandboxes, y se borran al ejecutar `sbx reset`. ## Guardar un sandbox como plantilla En el caso de no querer escribir un Dockerfile, puedes guardar el estado de un sandbox en ejecución como plantilla. Esto captura los paquetes instalados, los cambios de configuración y los archivos en una imagen reutilizable, lo cual es útil cuando has configurado un entorno de forma interactiva y deseas conservarlo. ### Guardar y reutilizar Detén el sandbox (o deja que la CLI te lo pida) y luego guárdalo con un nombre y una etiqueta: ```console $ sbx template save mi-sandbox mi-plantilla:v1 ``` La imagen se guarda en el almacén de imágenes local del entorno de ejecución del sandbox. Crea un nuevo sandbox a partir de ella con la bandera `-t`: ```console $ sbx run -t mi-plantilla:v1 claude ``` ### Listar y eliminar plantillas Lista todas las plantillas guardadas: ```console $ sbx template ls ``` Elimina una plantilla que ya no necesites: ```console $ sbx template rm mi-plantilla:v1 ``` ### Exportar e importar Para compartir una plantilla guardada o moverla a otra máquina, expórtala como un archivo tar: ```console $ sbx template save mi-sandbox mi-plantilla:v1 --output mi-plantilla.tar ``` En la otra máquina, carga el archivo tar y úsalo: ```console $ sbx template load mi-plantilla.tar $ sbx run -t mi-plantilla:v1 claude ``` ### Limitaciones Los archivos de configuración del agente siempre se vuelven a crear cuando se crea un sandbox. Los cambios en los archivos de configuración del agente a nivel de usuario, como `/home/agent/.claude/settings.json` y `/home/agent/.claude.json`, no persisten en las plantillas guardadas. Si la plantilla guardada se compiló para un agente diferente al que especificas en `sbx run`, recibirás una advertencia. Por ejemplo, guardar un sandbox de Claude y ejecutarlo con `codex` produce: ```text ⚠ WARNING: template "mi-plantilla:v1" was built for the "claude" agent but you are using "codex". The sandbox may not work correctly. Consider using: sbx run -t mi-plantilla:v1 claude ```