Docker Sandbox에서 Docker Model Runner와 함께 Claude Code 실행하기

Docker Sandbox에서 Docker Model Runner와 함께 Claude Code 실행하기 (Run Claude Code in a Docker Sandbox with Docker Model Runner)

Docker Sandboxes와 Docker Model Runner를 결합해, Anthropic 호환 API를 통해 호스트의 로컬 모델과 소통하는 격리된 microVM에서 Claude Code를 실행하는 방법을 설명하는 가이드예요.

출처: 문서

본문

이 가이드는 Docker Sandbox 안에서 백엔드 모델 공급자로 Docker Model Runner와 함께 Claude Code를 실행하는 방법을 보여줘요. 에이전트를 microVM에서 호스트와 격리된 상태로 유지하고, 머신의 로컬 모델을 가리키며, 모든 모델 트래픽을 기기 내부에 유지하게 됩니다.

감사의 말 (Acknowledgment): Docker는 이 가이드에 기여해준 Pradumna Saraf에게 감사드려요.

이 가이드에서 다음을 배우게 됩니다:

  • 코딩 모델을 pull하고 TCP가 활성화된 상태로 Docker Model Runner 시작하기
  • 샌드박스가 호스트의 Docker Model Runner에 도달하도록 허용하기
  • Claude Code 샌드박스를 만들고 로컬 엔드포인트를 영구적으로 설정하기
  • 로컬 모델로 Claude Code를 시작하고 연결 검증하기
  • 더 긴 프롬프트를 위해 더 큰 컨텍스트 윈도우로 gpt-oss 패키징하기

조각들이 어떻게 맞물리는가 (How the pieces fit together)

런타임에 세 가지 구성 요소가 협력해요:

  • Docker Model Runner는 호스트에서 실행되며 http://localhost:12434에서 Anthropic 호환 API를 제공해요.
  • Docker Sandbox는 격리된 microVM 안에서 Claude Code를 실행해요. microVM은 자체 네트워크를 가지며 호스트의 localhost에 직접 도달할 수 없어요.
  • 샌드박스 프록시는 호스트에 있으며 샌드박스의 모든 아웃바운드 요청을 중개해요. 네트워크 정책을 강제하고 특별한 호스트 이름 host.docker.internal을 localhost로 변환해요.

샌드박스 안의 Claude Code는 http://host.docker.internal:12434로 요청을 보내요. 프록시는 대상을 localhost:12434로 다시 작성하면 Docker Model Runner가 응답해요. 어떤 모델 트래픽도 머신을 떠나지 않아요.

사전 요구사항 (Prerequisites)

시작하기 전에 다음이 있는지 확인하세요:

Docker Desktop을 사용한다면 Settings > AI에서 TCP 접근을 켜거나 다음을 실행하세요:

$ docker desktop enable model-runner --tcp 12434

1단계: 코딩 모델 pull하기 (Step 1: Pull a coding model)

샌드박스를 만들기 전에 호스트에서 모델을 pull하세요:

$ docker model pull ai/devstral-small-2

큰 컨텍스트 윈도우를 가진 다른 코딩 중심 모델을 원한다면 ai/qwen3-coder를 사용할 수도 있어요.

2단계: 샌드박스가 Docker Model Runner에 도달하도록 허용하기 (Step 2: Allow the sandbox to reach Docker Model Runner)

샌드박스는 기본적으로 네트워크가 격리되어 있으므로, 샌드박스가 Docker Model Runner에 도달하려면 먼저 정책 규칙이 필요해요.

규칙은 샌드박스가 사용하는 호스트 이름이 아니라 프록시가 전달하는 대상에 대항해 일치돼요. 프록시는 전달하기 전에 host.docker.internal을 localhost로 다시 작성하므로, Claude Code가 요청에서 host.docker.internal을 사용하더라도 규칙은 localhost:12434를 허용해요:

$ sbx policy allow network localhost:12434

샌드박스에서 호스트 접근에 대한 배경은 샌드박스에서 호스트 서비스 접근하기를 참조하세요.

3단계: Claude Code 샌드박스 만들기 (Step 3: Create a Claude Code sandbox)

프로젝트 디렉터리에서 에이전트를 실행하지 않고 샌드박스를 만드세요. 샌드박스가 시작될 때마다 Claude Code가 Docker Model Runner를 사용하도록 ANTHROPIC_BASE_URL을 설정하세요:

$ cd ~/my-project
$ sbx create --name claude-dmr \
  -e ANTHROPIC_BASE_URL=http://host.docker.internal:12434 \
  claude .

sbx run도 동작하지만 Claude Code를 즉시 시작해요. 먼저 샌드박스를 만들면 에이전트가 시작되기 전에 변수를 확인하고 연결을 테스트할 수 있어요.

Anthropic API 키를 설정하거나 sbx secret set anthropic을 실행할 필요는 없어요. Docker Model Runner는 로컬 엔드포인트를 인증하지 않으며, 샌드박스 프록시는 api.anthropic.com을 대상으로 하는 요청에만 자격 증명을 주입해요. 프록시가 인증하는 서비스의 전체 목록은 Credentials를 참조하세요. 변수 설정의 더 많은 방법은 환경 변수 설정을 참조하세요.

변수가 설정되었는지 확인하려면 샌드박스에서 셸을 열어보세요:

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

4단계: Docker Model Runner 연결 검증하기 (Step 4: Verify connectivity to Docker Model Runner)

여전히 샌드박스 셸 안에서 호스트 엔드포인트에 테스트 요청을 보내세요:

$ 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"}]
  }'

성공적인 응답은 정책 규칙과 기본 URL이 올바르다는 것을 확인시켜줘요. 셸을 떠나려면 exit를 입력하세요. 요청 형식에 대한 자세한 내용은 Anthropic-compatible API reference를 참조하세요.

5단계: 로컬 모델로 Claude Code 시작하기 (Step 5: Launch Claude Code with the local model)

샌드박스에서 Claude Code를 실행하고 모델 플래그를 에이전트에 전달하세요:

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

-- 다음의 모든 것은 Claude Code CLI로 전달돼요.

ANTHROPIC_BASE_URL은 샌드박스와 함께 저장되어 모든 세션에서 사용 가능하므로, Claude Code는 api.anthropic.com 대신 호스트의 Docker Model Runner로 요청을 보내요.

6단계: Claude Code 요청 검사하기 (Step 6: Inspect Claude Code requests)

Claude Code가 보내는 요청을 검사하려면 호스트에서 실행하세요:

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

이것은 샌드박스에 연결하지 않고 프롬프트, 컨텍스트 사용량, 호환성 문제를 디버그하는 데 도움이 돼요.

7단계: 더 큰 컨텍스트 윈도우로 gpt-oss 패키징하기 (Step 7: Package gpt-oss with a larger context window)

ai/gpt-oss는 기본적으로 코딩 중심 모델보다 작은 컨텍스트 윈도우를 사용해요. 저장소 규모의 프롬프트에 사용하려면 호스트에서 더 큰 변형을 패키징하세요:

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

그런 다음 샌드박스를 다음에 실행할 때 Claude Code가 패키징된 모델을 가리키게 하세요:

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

정리 (Clean up)

샌드박스는 Claude Code가 종료된 후에도 지속돼요. 삭제하지 않고 샌드박스를 중지하려면:

$ sbx stop claude-dmr

샌드박스와 그 안의 모든 것을 제거하려면:

$ sbx rm claude-dmr

작업 공간의 파일은 영향을 받지 않아요.

더 알아보기 (Learn more)

더 알아보기 (Learn more)