Ejemplos de kits

Note

Los kits son experimentales. El formato de archivo de los kits, los comandos de la CLI y la experiencia para crear, cargar y gestionar kits están sujetos a cambios a medida que la característica evoluciona. Comparte comentarios y reportes de errores en el repositorio docker/sbx-releases.

Cada sección a continuación muestra un fragmento de spec.yaml que demuestra un único patrón de kit. Estos no son kits completos y distribuibles; son ejemplos pequeños y enfocados que puedes incorporar a tu propio kit. Para ver la referencia completa de la especificación, consulta Kits.

Colocar un archivo de configuración compartido

Utiliza archivos estáticos bajo files/workspace/ cuando el contenido sea el mismo en cada sandbox y no requiera la sustitución de valores en tiempo de ejecución. Casos de uso típicos: reglas de linter, ajustes del editor, un archivo .editorconfig compartido o dotfiles del equipo.

ruff-lint/
├── spec.yaml
└── files/
    └── workspace/
        └── ruff.toml

schemaVersion: "1"
kind: mixin
name: ruff-lint
displayName: Ruff
description: Python linting with shared team config

commands:
  install:
    - command: "uv tool install ruff@latest"
      user: "1000"

line-length = 80

[lint]
select = ["E", "F", "I"]

Instalar una herramienta al crear el sandbox

commands.install se ejecuta una vez por sandbox, en el momento de su creación. Aquí va cualquier elemento que deba incorporarse a la imagen: gestores de paquetes (apt-get, pip, npm), descargas de binarios o scripts de instalación de proveedores.

commands:
  install:
    - command: "apt-get update && apt-get install -y jq"
    - command: "curl -fsSL https://example.com/install.sh | sh"

Los comandos de instalación se ejecutan como root de forma predeterminada. Configura user: "1000" cuando el paso deba ejecutarse como el usuario del agente; por ejemplo, npm install -g en un prefijo con alcance de usuario o cualquier comando que escriba en /home/agent/.

Ejecutar un servicio en segundo plano

commands.startup se ejecuta en cada inicio del sandbox. Para servicios de larga duración, ejecútalos en segundo plano dentro de un comando de shell y redirige la salida a un archivo de registro (log). Confiar únicamente en el campo background: true puede dejar el servicio asociado a un shell que finaliza, lo que lo cerrará de forma silenciosa.

commands:
  startup:
    - command:
        - sh
        - -c
        - nohup my-service --port 8080 > /tmp/my-service.log 2>&1 &
      user: "1000"

El archivo de registro merece la pena: si el servicio finaliza antes de tiempo, su salida de error (stderr) se envía a un shell primario que no está conectado a nada que puedas leer. Un archivo de registro vacío te indica que el contenedor se ejecutó; uno con contenido te indica por qué falló.

Integrar valores en tiempo de ejecución en un archivo con initFiles

Cuando un archivo de configuración necesita un valor que no se conoce hasta el inicio del sandbox —la mayoría de las veces la ruta absoluta del espacio de trabajo— utiliza commands.initFiles. El marcador de posición ${WORKDIR} se expande a la ruta del espacio de trabajo primario cuando se escribe el archivo.

commands:
  initFiles:
    - path: /home/agent/.local/bin/start-code-server.sh
      content: |
        exec code-server --bind-addr 0.0.0.0:8080 --auth none "${WORKDIR}"
      mode: "0755"
  startup:
    - command:
        - sh
        - -c
        - nohup /home/agent/.local/bin/start-code-server.sh > /tmp/code-server.log 2>&1 &
      user: "1000"

mode: "0755" hace que el archivo generado sea ejecutable para que el comando de inicio pueda invocarlo directamente.

Utiliza initFiles en lugar de un archivo estático siempre que el contenido dependa de un valor en tiempo de ejecución. En caso contrario, usa un archivo estático.

Tip

Este fragmento se extrajo del kit de code-server en el repositorio contrib, el cual es también un ejemplo ejecutable que demuestra el patrón completo.

Incluir una habilidad (skill) de Claude Code

Claude Code lee habilidades con alcance de proyecto de .claude/skills/<nombre>/SKILL.md en el espacio de trabajo. Coloca una en files/workspace/ para que esté disponible en el sandbox.

docker-review/
├── spec.yaml
└── files/
    └── workspace/
        └── .claude/
            └── skills/
                └── docker-review/
                    └── SKILL.md

schemaVersion: "1"
kind: mixin
name: docker-review
displayName: Dockerfile review skill
description: Ships a Claude Code skill that reviews Dockerfiles

---
name: docker-review
description: Review a Dockerfile for best practices. Use when the user asks to review, audit, or improve a Dockerfile.
---

When reviewing a Dockerfile, check:

1. Base image — pinned tag or digest, appropriate for the workload
2. Layer order — dependencies copied before application source
3. Image size — multi-stage builds, `.dockerignore`, package-manager cache flags
4. Security — non-root `USER`, no secrets in `ARG`/`ENV`
5. Reproducibility — pinned package versions, frontend directive where relevant

Los kits deben tener como objetivo el espacio de trabajo en lugar de ~/.claude/ porque los sandboxes no heredan la configuración del agente a nivel de usuario del host. Consulta las Preguntas frecuentes para obtener más detalles.

Bifurcar un agente existente

Los kits de agentes (kind: agent) definen un agente completo desde cero. La variante más común es una bifurcación de un agente integrado: misma imagen y credenciales, pero con un punto de entrada (entrypoint) diferente. Este ejemplo reproduce el agente claude integrado pero elimina --dangerously-skip-permissions para que cada llamada a herramienta solicite aprobación:

schemaVersion: "1"
kind: agent
name: claude-safe
displayName: Claude Code (with approval prompts)
description: Claude Code without --dangerously-skip-permissions

agent:
  image: "docker/sandbox-templates:claude-code-docker"
  aiFilename: CLAUDE.md
  persistence: persistent
  entrypoint:
    run: [claude]

network:
  serviceDomains:
    api.anthropic.com: anthropic
    console.anthropic.com: anthropic
  serviceAuth:
    anthropic:
      headerName: x-api-key
      valueFormat: "%s"
  allowedDomains:
    - "claude.com:443"

credentials:
  sources:
    anthropic:
      env:
        - ANTHROPIC_API_KEY

Lanza el sandbox con el name: del kit como argumento del agente en sbx run:

$ sbx run claude-safe --kit ./claude-safe

Para obtener un tutorial paso a paso sobre cómo construir un nuevo kit de agente desde cero, consulta Construir un agente.

Más ejemplos

Todos estos patrones proceden de kits funcionales en el repositorio sbx-kits-contrib, el cual contiene cada ejemplo como un kit completo y cargable. Utilízalo para estudiar la estructura completa de un kit o cárgalo directamente:

$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=<kit>"