Claude Code는 왜 Docker를 권장할까? 초보자 완전 가이드 (2026)

Claude Code를 막 설치하고 공식 문서를 열면 첫 화면부터 devcontainer, Docker, --dangerously-skip-permissions 같은 단어가 보입니다. 많은 사람의 첫 반응은 「AI에게 코드만 좀 써 달라고 했는데, 왜 컨테이너를 배워야 하지?」입니다.

이건 Anthropic이 초보자를 괴롭히려는 게 아닙니다. Claude Code가 일반 코드 자동완성과 근본적으로 다른 점은, 제안만 하는 게 아니라 실제로 머신에서 명령을 실행하고, 여러 파일을 수정하고, 의존성을 받고, 테스트를 돌린다는 것입니다. 능력이 강할수록 오동작과 권한 남용 위험도 커집니다. Docker의 역할은 그 능력에 복제 가능한 「울타리」를 두는 것——본机을 보호하고 팀 전원이 같은 환경에서 일하게 하는——입니다.

이 가이드는 초보자가 따라갈 수 있는 순서로 썼습니다. 먼저 「왜 권장하는지」→ 30초 Docker 이해 → 공식 devcontainer 연결 → 처음으로 돌려 보기 → 사실 Docker가 필요 없는 경우까지. 먼저 DevOps 전문가가 될 필요는 없습니다.

한 줄 요약: Claude Code가 Docker를 권하는 이유

핵심은 세 가지로 정리됩니다.

• 격리: 컨테이너에서 실행되는 명령은 기본적으로 호스트의 ~/.ssh, 클라우드 자격 증명, 개인 사진 폴더에 닿지 않습니다——직접 mount하지 않는 한.
• 재현성: .devcontainer/devcontainer.json에 Node 버전과 필요한 CLI를 적어 두면, 동료가 clone 후 컨테이너를 재구성할 때 환경이 같아져 「여기선 되는데」가 줄어듭니다.
• 보안 기준선: Anthropic은 claude-code 저장소에서 참고 devcontainer를 유지하며, 기본 거부 아웃바운드 방화벽(npm, GitHub, Anthropic API 등 화이트리스트만 허용)을 갖추고 있습니다. 이로써 「무인 Agent 실행」이 문서상 설명 가능한 전제를 갖게 됩니다.

공식 Development containers 문서도 분명합니다. dev container는 Docker 위에서 돌고, 에디터(Cursor, VS Code, JetBrains 등)가 컨테이너에 연결되며, 터미널과 빌드 도구는 컨테이너 안에서 실행되고 편집하는 파일은 로컬 저장소에 매핑됩니다. Claude Code CLI도 컨테이너 안에서 동작합니다——「Docker 권장」의 뜻은 모든 개발을 컨테이너로 옮기라는 게 아니라, AI 에이전트용 작업 구역을 나누는 것입니다.

완전 초보를 위한: Docker란?

먼저 Kubernetes, 마이크로서비스 같은 큰 말은 잊으세요. Claude Code 초보에게 필요한 비유는 하나뿐입니다.

Docker 컨테이너 = 가볍고 버릴 수 있는 「미니 PC」——OS 슬라이스, Node/Python, 필요한 도구가 들어 있는 상자. 진짜 PC와 CPU를 공유하지만 파일 시스템과 네트워크는 따로 설정할 수 있습니다.

가상 머신보다 기동이 빠르고 점유가 작습니다. 「본机에 직접 소프트웨어 설치」와 비교하면 컨테이너는 지워도 찌꺼기가 남지 않습니다——Claude가 하루에 열 가지 의존성 조합을 시도할 때 특히 중요합니다.

기억할 용어는 세 가지면 됩니다.

더 일반적인 Docker 개념은 Docker 공식 Get started를 참고하세요. 이 글은 Claude Code 최단 경로에 집중합니다.

Anthropic 공식 devcontainer 안에 뭐가 있나

저장소 anthropics/claude-code의 .devcontainer/는 장식이 아니라 복제 가능한 안전 개발 템플릿입니다. 주요 파일 역할은 다음과 같습니다.

• devcontainer.json: 볼륨 mount, 환경 변수, VS Code/Cursor 확장, Claude Code 설치 Feature;
• Dockerfile: 베이스 이미지(Debian/Ubuntu 등), 개발 도구, non-root 사용자;
• init-firewall.sh: 기본 거부 아웃바운드, 화이트리스트만 허용——직접 Dockerfile을 쓸 때 가장 자주 빠뜨리는 부분입니다.

문서는 Claude Code Dev Container Feature 설치를 권장합니다. devcontainer.json 예시:

{
                  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
                  "features": {
                    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
                  },
                  "remoteUser": "node",
                  "mounts": [
                    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
                  ],
                  "containerEnv": {
                    "DISABLE_AUTOUPDATER": "1"
                  }
                }

mounts에서 ~/.claude에 이름 있는 볼륨을 붙인 점에 주목하세요. 컨테이너 재구성 후에도 로그인 상태와 세션 기록을 유지할 수 있어 매번 다시 인증할 필요가 없습니다. 공식이 별도 절로 설명하는 이유입니다.

이미 ECC(Everything Claude Code) 같은 설정 모음을 쓰고 있다면, devcontainer는 「하드웨어 계층」으로 보면 됩니다. ECC가 skills와 hooks를, Docker가 Claude 명령의 실제 실행 파일 시스템을 담당합니다.

보안 서사: 왜 컨테이너 안에서만 「권한 확인 건너뛰기」를 말할 수 있나

Claude Code는 기본적으로 bash 실행이나 파일 쓰기마다 확인을 요구합니다. CI나 장시간 무인 작업에서는 --dangerously-skip-permissions를 붙이는 경우도 있습니다.

공식 입장은 분명합니다. 이 플래그는 hardened devcontainer용이지, 데스크톱 본机용이 아닙니다. 본机에서 확인을 건너뛰면 AI가 사용자 디렉터리를 무제한으로 다룰 수 있습니다——파일 삭제, 키체인 우회 읽기, 임의 URL로 요청 전송이 가능합니다. 컨테이너 방안은 최소한 다음을 합니다.

• 파일 시스템 경계: 프로젝트 디렉터리 + 필요한 설정 볼륨만 mount;
• 네트워크 경계: 아웃바운드 방화벽으로 외부 목적지 제한;
• 사용자 경계: non-root 실행, sudo 제한.

다만 컨테이너가 만능은 아닙니다. ~/.aws나 프로덕션 DB URL을 .env에 넣고 mount하면 AI도 읽을 수 있습니다. 안전은 mount 내용과 저장소 신뢰성에 달려 있습니다. 공식 원문에도 「Only use dev containers when developing with trusted repositories.」라고 적혀 있습니다.

실습: Docker로 Claude Code를 처음 돌려 보기

아래는 macOS / Windows(WSL2)에서 검증된 경로입니다. Docker 전권을 먼저 읽을 필요는 없습니다.

1단계: Docker 엔진 설치

하나만 골라도 됩니다. 팀 내 통일이 더 중요합니다.

• macOS: Docker Desktop(가장 편함); Apple Silicon에서는 Colima, OrbStack도 흔하며 CLI는 docker 호환;
• Windows: Docker Desktop + WSL2 백엔드;
• Linux: Docker Engine 또는 rootless Podman(devcontainer CLI 지원 확인).

설치 후 터미널에서 docker --version과 docker run hello-world를 실행해 Hello from Docker가 나오면 통과입니다.

2단계: 프로젝트와 devcontainer 설정 준비

저장소 루트에 .devcontainer/를 만듭니다. 방법은 두 가지.

1. anthropics/claude-code에서 참고 설정을 복사한 뒤 프로젝트에 맞게 Dockerfile 수정; 또는
2. Cursor / VS Code에서 Dev Containers: Add Dev Container Configuration Files 실행 후 공식 문서대로 Claude Code Feature 추가.

손으로 쓰기 싫다면 본机에 CLI를 한 번 설치한 뒤 Claude Code에 자연어로 요청해도 됩니다. 「Node 20 프로젝트용 .devcontainer 생성. Claude Code Feature와 pnpm 포함」——생성 후에도 mount 범위와 방화벽 구간은 반드시 사람이 검토하세요.

3단계: 컨테이너 안에서 프로젝트 열기

Cursor / VS Code: 명령 팔레트에서 Dev Containers: Reopen in Container. 첫 빌드는 몇 분 걸릴 수 있지만 이후 증분 기동은 훨씬 빠릅니다. 프롬프트가 바뀌고 which node가 컨테이너 내부 경로를 가리키면 「상자 안」에 들어온 것입니다.

GUI 에디터 없이 터미널만 써도 됩니다.

# 프로젝트 루트, docker-compose.yml이 있을 때
                docker compose up -d
                docker compose exec dev bash
                claude

서비스 이름은 compose 파일을 따릅니다. devcontainer는 이 흐름을 표준화한 것입니다.

4단계: 컨테이너 안에서 Claude Code 동작 확인

컨테이너 터미널에서 claude를 실행하고 작은 일을 시켜 봅니다. 예: 「package.json의 scripts를 나열하고 설명해 줘」. 확인할 것:

• 파일 변경이 호스트 Git 상태에 나타나는지(bind mount 정상);
• cat /etc/os-release가 컨테이너 OS를 보여 주는지(본机 버전 아님);
• mount하지 않은 경로 접근을 Claude에게 시도해 보고 거부되는지.

세 가지 모두 기대대로면 격리층이 작동 중입니다. 이후 팀 문서에 「Claude Code 쓰기 전 Reopen in Container」라고 적으면 신입이 Node 버전을 따로 맞출 필요가 없습니다.

사실 Docker가 필요 없는 경우

공식 권장은 강제가 아닙니다. 다음 상황에서는 본机 직접 실행이 더 편합니다.

판단 구호: 「내가 자리를 비울 때 AI가 명령을 자동 실행해도 괜찮은가?」 괜찮고 저장소를 신뢰한다 → 컨테이너 + mount 축소; 아니다 → 본机 대화형으로 충분.

Mac 사용자 보충: Docker와 Apple 개발 공존

Mac에서 Xcode와 AI 보조 풀스택을 병행하는 독자가 많습니다. 실무에서 흔한 분담은 다음과 같습니다.

• Xcode, 시뮬레이터, 서명은 macOS 본机;
• Node/Python 서비스, Claude Code 장세션, 실험 스크립트는 devcontainer;
• 팀 백엔드 환경을 맞출 때 docker-compose.yml을 저장소에 넣고 API를 컨테이너에서 연동 테스트.

Apple Silicon에서 x86 이미지를 돌리면 느리므로 arm64 베이스를 우선하세요. Docker Desktop에 메모리 4~8GB 이상을 할당하면 dev server와 Claude를 병행할 때 swap이 덜 납니다.

문제 해결 빠른 참조

• Rebuild 후 Claude가 다시 로그인 요구: ~/.claude가 이름 있는 볼륨에 mount됐는지 확인. 컨테이너 쓰기 레이어만 쓰면 사라집니다.
• 컨테이너에서 npm / GitHub 접근 불가: init-firewall.sh 화이트리스트 확인. 회사 프록시는 HTTP_PROXY 추가 설정.
• 포트 3000이 안 열림: devcontainer forwardPorts 또는 compose에서 포트 매핑 선언.
• Permission denied: remoteUser가 프로젝트 디렉터리에 쓸 수 있는지. Linux bind mount는 UID 맞춤이 자주 필요.
• Docker Desktop 기동 실패: Windows는 WSL2, Mac은 가상화가 보안 소프트에 막히지 않았는지 확인.

자주 묻는 질문 FAQ

Claude Code와 Cursor 내장 Agent 둘 다 Docker가 필요한가?

아닙니다. Cursor Agent는 기본적으로 본机 워크스페이스에서 돕니다. Claude Code는 독립 CLI이며 공식 devcontainer를 일급 시민으로 지원합니다. Cursor로 편집 + 컨테이너 터미널에서 claude 병행도 가능합니다.

devcontainer는 VS Code 필수?

필수는 아닙니다. 규격은 VS Code에서 시작했지만 Cursor, JetBrains, GitHub Codespaces가 지원합니다. 순수 docker compose + shell도 되지만 Reopen in Container 편의는 없습니다.

이미 OpenClaw docker compose 배포를 할 줄 아는데, 이건 중복인가?

중복이 아닙니다. 배포용 compose는 「서비스 공개」, devcontainer는 「개발 시 Claude가 어디서 실행되는지」가 목적입니다. 사고방식은 비슷하지만 설정 의도가 다릅니다. OpenClaw 배포 경험은 mount와 네트워크 이해에 도움이 됩니다.

컨테이너 안 Claude Code는 어떻게 업데이트하나?

공식 Feature는 최신 CLI를 설치하고 컨테이너 안 자동 업데이트가 켜진 경우가 많습니다. 버전 고정은 Dockerfile에서 pin하거나 containerEnv에 DISABLE_AUTOUPDATER 설정.

회사에서 Docker Desktop 설치가 금지된 경우

IT에 원격 devcontainer 호스트, GitHub Codespaces, 사내 K8s 개발 공간이 있는지 문의하세요. Claude Code에 필요한 것은 「격리된 Linux 환경」이지, 반드시 노트북上的 Docker는 아닙니다.

정리: Docker는 숙제가 아니라 Claude Code의 「안전벨트」

제목으로 돌아가면: Claude Code가 Docker를 권하는 이유는?

• AI 프로그래밍 어시스턴트가 제안을 넘어 실행할 수 있기 때문;
• 팀이 스크린샷으로 Node 설치를 가르치는 대신 같이 재구성 가능한 환경이 필요하기 때문;
• Anthropic이 무인 모드를 방화벽 뒤 컨테이너에 가두고 ~/ 전체에 풀어 두고 싶지 않기 때문.

초보자를 겁먹일 필요는 없습니다. 오늘 할 일은 하나뿐입니다. 작은 프로젝트에서 Reopen in Container하고, 컨테이너 터미널에서 한 번 claude를 실행해, 명령은 컨테이너 안에서, 파일 변경은 호스트에 나타나는 걸 직접 확인하는 것. 여기까지 되면 문서만 본 사람보다 한 발 앞섭니다.

이후 ECC, MCP를 붙이거나 Agent를 VPS에 올릴 때도 Docker는 AI 시대의 「공통 설치 프로그램」이 됩니다——Claude Code 공식은 그 사실을 누구보다 일찍, 분명히 보안 가이드에 적어 둔 쪽입니다.