# Ejecutar Claude Code en un Docker Sandbox con Docker Model Runner


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](https://twitter.com/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:

- [Docker Desktop](/get-started/get-docker/) o Docker Engine instalado
- [Docker Model Runner habilitado](/ai/model-runner/get-started/#enable-docker-model-runner)
- [Docker Sandboxes (`sbx`) instalado e inicio de sesión completado](/ai/sandboxes/get-started/#install-and-sign-in)

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

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

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

```console
$ 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](/ai/sandboxes/usage/#accessing-host-services-from-a-sandbox).

## Paso 3: Crear un sandbox para Claude Code

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

```console
$ 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](/ai/sandboxes/security/credentials/) 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:

```console
$ 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?](/ai/sandboxes/faq/#how-do-i-set-custom-environment-variables-inside-a-sandbox).

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

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

```console
$ 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](/ai/model-runner/api-reference/#anthropic-compatible-api).

## Paso 6: Iniciar Claude Code con el modelo local

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

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

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

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

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

```console
$ sbx stop claude-dmr
```

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

```console
$ sbx rm claude-dmr
```

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

## Más información

- [Usar Claude Code con Docker Model Runner](/guides/claude-code-sandbox-model-runner/claude-code-model-runner/)
- [Primeros pasos con Docker Sandboxes](/ai/sandboxes/get-started/)
- [Claude Code en Docker Sandboxes](/ai/sandboxes/agents/claude-code/)
- [Descripción general de Docker Model Runner](/ai/model-runner/)
- [Referencia de la API de Docker Model Runner](/ai/model-runner/api-reference/)