Compartir comentarios
Las respuestas se generan en base a la documentación.

Ejecutar Claude Code en un Docker Sandbox con Docker Model Runner

Tabla de contenidos

Esta guía muestra cómo ejecutar Claude Code dentro de un Docker Sandbox con Docker Model Runner como proveedor de modelos en el backend. Mantendrás al agente aislado de tu host en una microVM, lo apuntarás a un modelo local en tu máquina y mantendrás todo el tráfico del modelo de forma local en el dispositivo.

Agradecimiento

Docker desea agradecer a Pradumna Saraf por su contribución a esta guía.

En esta guía, aprenderás a:

  • Descargar un modelo de programación e iniciar Docker Model Runner con TCP habilitado
  • Permitir que el sandbox se conecte a Docker Model Runner en tu host
  • Crear un sandbox para Claude Code y configurar el endpoint local de forma persistente
  • Iniciar Claude Code con un modelo local y verificar la conexión
  • Empaquetar gpt-oss con una ventana de contexto más grande para prompts más largos

Cómo encajan las piezas

Tres componentes cooperan en tiempo de ejecución:

  • Docker Model Runner se ejecuta en tu host y sirve una API compatible con Anthropic en http://localhost:12434.
  • El Docker Sandbox ejecuta Claude Code dentro de una microVM aislada. La microVM tiene su propia red y no puede acceder al localhost de tu host directamente.
  • El proxy del sandbox se encuentra en tu host e intermedia cada solicitud saliente desde el sandbox. Aplica políticas de red y traduce el nombre de host especial host.docker.internal a localhost.

Claude Code dentro del sandbox envía solicitudes a http://host.docker.internal:12434. El proxy reescribe el destino a localhost:12434, el cual es respondido por Docker Model Runner. Ningún tráfico de modelos sale de tu máquina.

Prerrequisitos

Antes de comenzar, asegúrate de tener:

Si utilizas Docker Desktop, activa el acceso TCP en Settings > AI, o ejecuta:

$ docker desktop enable model-runner --tcp 12434

Paso 1: Descargar un modelo de programación

Descarga un modelo en tu host antes de crear el sandbox:

$ docker model pull ai/devstral-small-2

También puedes usar ai/qwen3-coder si quieres otro modelo enfocado en programación con una ventana de contexto grande.

Paso 2: Permitir que el sandbox se conecte a Docker Model Runner

Los sandboxes están aislados de la red por defecto, por lo que necesitas una regla de política antes de que el sandbox pueda conectarse a Docker Model Runner.

La regla se contrasta con el destino al que el proxy reenvía la solicitud, no con el nombre de host que utiliza el sandbox. Como el proxy reescribe host.docker.internal a localhost antes de reenviar, la regla permite localhost:12434 aunque Claude Code utilice host.docker.internal en sus solicitudes:

$ sbx policy allow network localhost:12434

Para más información sobre el acceso al host desde los sandboxes, consulta Acceder a servicios del host desde un sandbox.

Paso 3: Crear un sandbox para Claude Code

Desde el directorio de tu proyecto, crea un sandbox sin iniciar el agente:

$ cd ~/my-project
$ sbx create claude --name claude-dmr .

sbx run también funcionaría, pero inicia Claude Code inmediatamente. Sin configurar ANTHROPIC_BASE_URL, Claude Code apunta a api.anthropic.com y solicita OAuth o produce un error antes de que puedas corregir el endpoint. Crear primero el sandbox te permite escribir el endpoint local en él antes de que comience el agente.

No necesitas configurar una clave de API de Anthropic ni ejecutar sbx secret set anthropic. Docker Model Runner no autentica el endpoint local y el proxy del sandbox solo inyecta credenciales para las solicitudes destinadas a api.anthropic.com. Consulta Credenciales para ver la lista completa de servicios que el proxy autentica.

Paso 4: Configurar el endpoint local dentro del sandbox

Añade ANTHROPIC_BASE_URL al archivo de entorno persistente del sandbox para que Claude Code lo lea en cada inicio:

$ sbx exec -d claude-dmr bash -c "echo 'export ANTHROPIC_BASE_URL=http://host.docker.internal:12434' >> /etc/sandbox-persistent.sh"

El contenedor bash -c asegura que la redirección >> se ejecute dentro del sandbox, no en tu host. Para más detalles sobre este enfoque, consulta ¿Cómo configuro variables de entorno personalizadas dentro de un sandbox?.

To confirm the variable is set, open a shell in the sandbox:

$ sbx exec -it claude-dmr bash
$ echo $ANTHROPIC_BASE_URL
http://host.docker.internal:12434

Paso 5: Verificar la conectividad con Docker Model Runner

Estando aún dentro del shell del sandbox, envía una solicitud de prueba al endpoint del host:

$ curl http://host.docker.internal:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/devstral-small-2",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Say hello"}]
  }'

Una respuesta exitosa confirma que la regla de política y la URL base son correctas. Escribe exit para salir del shell. Para más detalles sobre el formato de la solicitud, consulta la Referencia de la API compatible con Anthropic.

Paso 6: Iniciar Claude Code con el modelo local

Ejecuta Claude Code en el sandbox y pasa la bandera del modelo al agente:

$ sbx run claude-dmr -- --model ai/devstral-small-2

Todo lo que va después de -- se reenvía a la CLI de Claude Code. Como ANTHROPIC_BASE_URL está configurada en el entorno persistente del sandbox, Claude Code enruta las solicitudes a Docker Model Runner en tu host en lugar de a api.anthropic.com.

Paso 7: Inspeccionar las solicitudes de Claude Code

Para inspeccionar las solicitudes que envía Claude Code, ejecuta en tu host:

$ docker model requests --model ai/devstral-small-2 | jq .

Esto te ayuda a depurar prompts, el uso del contexto y problemas de compatibilidad sin necesidad de conectarte al sandbox.

Paso 8: Empaquetar gpt-oss con una ventana de contexto más grande

ai/gpt-oss tiene por defecto una ventana de contexto más pequeña que los modelos enfocados en programación. Para usarlo en prompts a escala de repositorio, empaqueta una variante más grande en el host:

$ docker model pull ai/gpt-oss
$ docker model package --from ai/gpt-oss --context-size 32000 gpt-oss:32k

Luego apunta Claude Code al modelo empaquetado la próxima vez que ejecutes el sandbox:

$ sbx run claude-dmr -- --model gpt-oss:32k

Limpieza

Los sandboxes persisten después de que finaliza Claude Code. Para detener el sandbox sin eliminarlo:

$ sbx stop claude-dmr

Para eliminar el sandbox y todo lo que contiene, incluyendo el archivo de entorno persistente:

$ sbx rm claude-dmr

Los archivos en tu espacio de trabajo no se verán afectados.

Más información