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.

Imágenes base

Todas las plantillas de sandbox se publican como docker/sandbox-templates:<variante>. 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.

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:

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

$ sbx run claude --template docker.io/docker/sandbox-templates:claude-code

Compilar una plantilla personalizada

Compilar una plantilla personalizada requiere Docker 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:

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:

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

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

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

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

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

$ sbx run -t mi-plantilla:v1 claude

Listar y eliminar plantillas

Lista todas las plantillas guardadas:

$ sbx template ls

Elimina una plantilla que ya no necesites:

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

$ sbx template save mi-sandbox mi-plantilla:v1 --output mi-plantilla.tar

En la otra máquina, carga el archivo tar y úsalo:

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

⚠ 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