핵심 요약
- Dev Containers 확장을 설치하고 Docker를 돌린 채로, .devcontainer/가 있는 리포지토리에서 Reopen in Container — Claude Code와 그것이 실행하는 모든 명령이 컨테이너 안에서 돌고, 여러분 머신에서는 돌지 않습니다.
- 공식 feature — features 블록의 "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" — 은 어느 devcontainer에나 CLI를 설치합니다; VS Code에는 확장도 들어오고, 양쪽이 하나의 ~/.claude를 공유합니다.
- 로그인은 컨테이너 터미널에서. 브라우저 콜백이 닿지 않으면 프롬프트에 코드를 붙여넣으세요. ~/.claude 볼륨과 containerEnv.CLAUDE_CONFIG_DIR로 인증은 재빌드를 살아남습니다.
- dev container는 환경 자체를 갈아끼웁니다(/sandbox는 대신 여러분 호스트에서 개별 명령을 가둡니다). 둘은 조합됩니다 — 환경은 컨테이너, 행동은 sandbox와 권한 프롬프트.
Run Your AI Coding Agent in Dev Containers - Complete Beginner's Guide
채널: Visual Studio Code15:39
Step-by-Step: Run Claude Code SAFELY in a Dev Container
채널: Fuzz Puppy6:56
Development containers — official documentation
공식 문서: code.claude.com/docs
이 페이지의 모든 셋업 단계, feature 이름, 자격 증명 경로는 공식 development containers 문서와 대조해 검증했습니다. 위 영상들이 시각·사실 자료입니다.
스크린샷의 권리는 각 제작자에게 있으며, 해당 타임스탬프로 바로 연결됩니다. 얼굴이 나온 장면은 사용하지 않았습니다.
dev container에서 Claude Code 돌리기, 단계별로
파트 1 — 전제 조건: VS Code가 Docker를 만나다
- 1
Dev Containers 확장 설치
VS Code의 확장 뷰를 열어 Microsoft의 Dev Containers를 설치하세요. 이 확장이 상태 표시줄의 원격 표시기, Reopen in Container 명령, Remote Explorer를 추가합니다 — 아래의 전체 워크플로가 이걸 통과합니다. Docker는 아직 필요 없습니다.
VS Code에 Reopen in Container를 달아 주는 게 Dev Containers 확장입니다 — 먼저 확장 뷰에서 설치하세요.2:00부터 시청 - 2
Docker Desktop 설치하고 띄우기
dev container는 진짜 컨테이너이므로 무엇이든 열리기 전에 컨테이너 엔진이 돌아가야 합니다. macOS와 Windows에서는 Docker Desktop이, Linux에서는 Docker Engine이 일반적입니다. 띄우고 계속 돌려 두세요 — 첫 시도에서 "Opening Remote"이 멈추는 1등 원인이 바로 꺼져 있는 엔진입니다.
Docker Desktop은 돌아가기만 하면 됩니다; 빈 Containers 목록이야말로 건강한 사전 컨테이너 셋업의 모습입니다.2:12부터 시청 - 3
Claude Code에게 무엇이 바뀌는지 이해
Reopen in Container 이후 VS Code는 서버를 컨테이너 안에서 돌립니다 — Claude Code가 실행하는 모든 명령도 마찬가지. 설치, 테스트 실행, 파일 편집은 컨테이너 안에 머물고, 워크스페이스 폴더는 리포지토리로 다시 마운트됩니다. 여러분 머신에 필요한 건 VS Code와 Docker뿐이고, 툴체인과 의존성은 이미지 속에 살며 에이전트의 삐끗한 실험이 밖의 무엇도 건드리지 못합니다.
파트 2 — 끝까지 돌아가는 컨테이너 하나
- 4
준비된 dev container 열기
장치가 도는 걸 보는 가장 빠른 길: Remote Explorer에서 Go dev container 같은 샘플을 고르세요. VS Code가 github.com/microsoft/vscode-remote-try-go를 클론해 컨테이너 볼륨 안에서 엽니다 — 아직 여러분이 쓴 설정은 한 줄도 없습니다.
Remote Explorer에는 준비된 샘플이 실려 옵니다 — 하나를 고르면 VS Code가 리포지토리를 컨테이너 볼륨으로 곧장 클론합니다.2:30부터 시청 - 5
VS Code의 빌드와 연결을 기다리기
첫 연결은 리포지토리를 클론하고, 컨테이너 이미지를 레이어별로 받아 오고, 컨테이너를 시작합니다 — 상태 표시줄이 "Connecting to Dev Container"라고 알립니다. 느린 회선에서는 셋업 최대의 대기 시간입니다; 그다음 열기부터는 이미지를 재활용해 몇 초면 끝납니다.
첫 빌드는 컨테이너 이미지를 레이어별로 내려받습니다; 상태 표시줄이 dev container로의 연결을 추적합니다.2:52부터 시청 - 6
터미널이 컨테이너 안에 있는지 확인
새 터미널을 열어 툴체인 버전을 출력해 보세요(여기서는 go version). 출력은 노트북이 아니라 컨테이너의 OS와 아키텍처를 자칭합니다. 바로 이 터미널이 claude를 띄울 자리 — 그리고 그것이 실행하는 것은 모두 컨테이너 안에 머뭅니다.
go version이 출력하는 건 컨테이너의 툴체인이지 노트북의 것이 아닙니다 — 이 터미널에서 claude를 돌리면 그것도 안에 머뭅니다.3:50부터 시청 - 7
devcontainer.json 읽기
.devcontainer/devcontainer.json 파일이 환경 전체를 정의합니다: 베이스 이미지(또는 Dockerfile), 컨테이너에 설치할 VS Code 확장, 포워딩할 포트, postCreateCommand 셋업 단계, remoteUser. Claude Code에게 이 파일은 공식 feature와 자격 증명 볼륨이 들어갈 자리이기도 합니다 — 9단계와 13단계에서 다룹니다.
컨테이너를 이루는 모든 것은 .devcontainer/devcontainer.json에 있습니다: 이미지, 확장, 포워딩 포트, post-create 명령.4:40부터 시청 - 8
에이전트를 워크스페이스로 향하게
에이전트 패널에서 @workspace를 붙이고 프로젝트 설명을 부탁하세요. 설명과 그 뒤의 모든 명령이 컨테이너 안에서 실행됩니다. CLI가 이미지에 설치되고 나면 Claude Code도 똑같습니다: @workspace식 컨텍스트에, 컨테이너를 떠나지 않는 명령.
@workspace로 프로젝트 설명을 부탁하는 장면 — 실행되는 모든 명령은 컨테이너 안에서 돕니다.5:20부터 시청 - 9
공식 Claude Code feature로 갈아끼우기
수동 설치는 없습니다: devcontainer.json의 features 블록에 "ghcr.io/anthropics/devcontainer-features/claude-code:1.0"을 더하고 재빌드하세요. feature가 CLI를 설치하고, 컨테이너가 VS Code로 열리면 Claude Code 확장도 들어와 터미널과 같은 ~/.claude를 공유합니다. 베이스 이미지에 Node.js가 없으면 "Failed to install Node.js and npm"이 뜹니다: 위에 Node feature를 더하세요. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC이나 DISABLE_AUTOUPDATER 같은 환경 설정은 containerEnv 아래로, mounts로 여러분의 다른 로컬 리포지토리를 컨테이너로 끌어들일 수도 있습니다.
- 10
앱을 돌리고 포워딩된 포트 사용
컨테이너 안에서 앱을 시작하면(디버그 패널, npm run dev, go run — 스택이 시키는 대로) VS Code가 듣는 중인 포트를 감지합니다: 로컬 브라우저로 열어 보겠다는 알림이 떠요. 서버는 컨테이너를 떠나지 않고, 포워딩이 localhost를 평소처럼 굴러가게 할 뿐입니다.
앱은 컨테이너 안의 9000 포트에서 돕니다; VS Code가 포워딩해 localhost는 정확히 평소처럼 작동합니다.6:08부터 시청
파트 3 — 여러분의 리포지토리와 로그인
- 11
여러분 프로젝트에 dev container 추가
어떤 리포지토리에서든 명령 팔레트나 원격 표시기로 Dev Containers: Add Dev Container Configuration Files를 실행하고 "Add configuration to workspace folder"를 고르세요. 코드와 함께 커밋된 설정은 팀원에게 — 그리고 Codespaces에 — 동일한 환경을 공짜로 줍니다.
devcontainer.json이 아직 없나요? VS Code가 템플릿에서 만들어 줍니다 — git이 공유할 수 있게 워크스페이스에 두세요.9:00부터 시청 - 12
템플릿과 features 고르기
VS Code는 스택에 맞는 템플릿(Node.js, Python, Go…)을 제안한 뒤 features 목록 — Git LFS나 GitHub CLI 같은 재사용 가능한 설치기 — 을 보여 줍니다. 9단계의 claude-code feature가 끼어들 자리도 이 목록입니다. 기본값을 받아들이고(또는 생성된 파일의 다듬기를 에이전트에게 맡기고) 컨테이너에서 다시 여세요.
features 목록은 템플릿의 제안 옆에 Claude Code feature 줄이 끼어드는 자리입니다.9:48부터 시청 - 13
컨테이너 안에서 로그인
통합 터미널에서 claude를 실행하고 로그인 방식(Claude 구독 또는 Anthropic Console)을 고르세요. 브라우저는 호스트에서 열립니다; 콜백이 컨테이너에 닿지 않으면 브라우저의 코드를 복사해 "Paste code here if prompted" 프롬프트에 붙여넣으세요. 재빌드를 살아남게 하려면 ~/.claude에 볼륨을 마운트하고 containerEnv.CLAUDE_CONFIG_DIR을 같은 경로로 — 계정 파일 ~/.claude.json은 그 폴더 밖에 살아서 양쪽 절반이 모두 필요합니다. 헤드리스 실행이나 Codespaces용으로는 claude setup-token으로 토큰을 만들어 ANTHROPIC_API_KEY나 CLAUDE_CODE_OAUTH_TOKEN으로 넘기세요.
dev container vs /sandbox: 어느 격리가 필요한가?
Claude Code는 두 가지 격리 답을 실어 왔고, 둘은 다른 문제를 풉니다. dev container는 에이전트가 일하는 환경을 갈아끼우고, 내장 sandboxing은 여러분 현재 머신에서 도는 명령을 가둡니다. 공식 문서는 둘을 상호 보완으로 놓습니다 — 참조용 devcontainer는 egress 제한 스크립트까지 싣고 있죠.
- 1범위. dev container는 환경 전체 — OS, 툴체인, 의존성 — 를 devcontainer.json에 정의된 것으로 통째로 바꿉니다. sandboxing은 여러분 머신을 지키면서 각 bash 명령이 읽고, 쓰고, 네트워크로 닿을 수 있는 범위를 제한합니다.
- 2요건. dev container에는 Docker(Desktop 또는 Engine)에 Dev Containers 확장이 더 필요합니다; sandboxing은 Claude Code에 내장되어 어느 쪽도 필요 없습니다.
- 3팀의 역학. devcontainer.json은 커밋되므로 모든 팀원과 모든 Codespace가 동일한 환경을 빌드합니다; sandbox 정책은 Claude Code 설정에 살며 리포지토리가 아닌 사용자를 따라다닙니다.
- 4피해 반경. 컨테이너 안에서 건성 rm -rf나 폭주 설치는 버릴 수 있는 파일시스템에 부딪히고 호스트는 멀쩡합니다. sandbox는 컨테이너 경계 없이 같은 결과를 명령 단위로 노립니다.
- 5프로젝트 자체가 환경을 필요로 하면 dev container: 여러 런타임, 깔끔한 온보딩, 클라우드 개발. 호스트 위 세션의 일상 가드레일은 sandbox. 둘은 조합됩니다 — dev container 안에서 Claude Code를 돌리면서 sandboxing과 권한 프롬프트는 켜 두세요.
한 줄 더 차이를 낳습니다: /sandbox는 대화 도중 조정할 수 있는 세션별 정책이고, dev container는 세션이 시작되기 전에 정해집니다 — 바꾸는 것은 재빌드를 뜻합니다. 무인 배치 실행은 둘을 동시에 의지합니다: non-root 컨테이너 사용자, 제한된 egress, 그리고 --dangerously-skip-permissions은 컨테이너 안에서만.
말을 안 듣나요? 여기서 시작
Claude Code 주변의 dev container 마찰은 알려진 패턴 몇 개로 떨어집니다. 아래의 모든 해결책은 공식 development containers 문서에서 왔습니다.
- 1feature 설치 중 "Failed to install Node.js and npm": 베이스 이미지에 Node.js가 없습니다. features 블록에서 claude-code feature 위에 Node feature(ghcr.io/devcontainers/features/node:1)를 더하고 재빌드하세요.
- 2브라우저에서는 로그인이 끝나는데 컨테이너는 로그아웃 상태: OAuth 콜백이 컨테이너에 닿지 않습니다. 브라우저에 표시된 코드를 복사해 터미널의 "Paste code here if prompted" 프롬프트에 붙여넣으세요.
- 3재빌드마다 로그인과 설정이 사라진다: ~/.claude를 영속화하는 게 없습니다. 그 경로에 이름 있는 볼륨을 마운트하고 containerEnv.CLAUDE_CONFIG_DIR을 거기로 — 프로젝트가 격리되도록 볼륨 이름에 devcontainerId 변수를 넣으세요. Codespaces에서는 폴더가 stop/start는 견디지만 전체 재빌드에서 지워지므로, 대신 ANTHROPIC_API_KEY나 claude setup-token의 CLAUDE_CODE_OAUTH_TOKEN을 secret으로 넘기세요.
- 4Claude Code 버전의 깜짝 변수: claude-code:1.0 feature 태그가 고정하는 건 설치 스크립트지 CLI가 아닙니다 — 최신 릴리스가 설치되고 컨테이너 안에서 자동 업데이트됩니다. 버전을 얼리려면 Dockerfile에서 npm install -g @anthropic-ai/claude-code@X.Y.Z.
- 5"Is Docker running?"이거나 멈춘 "Opening remote": 엔진에 닿지 않습니다 — Docker Desktop(또는 데몬)을 시작하고 재시도하세요. --dangerously-skip-permissions이 시작을 거부한다면 컨테이너가 root로 돌고 있는 겁니다; remoteUser를 "vscode" 같은 non-root 사용자로. 조직은 /etc/claude-code의 managed-settings.json으로 bypass 모드 자체를 끌 수 있습니다.
재빌드는 만능 재시도입니다: 명령 팔레트 → "Dev Containers: Rebuild Container"가 devcontainer.json을 다시 읽고 편집 후의 features를 다시 실행합니다. 재빌드가 새 클론과 다르게 굴러간다면 컨테이너를 지우고 다시 여세요 — 이미지와 이름 있는 볼륨은 삭제를 살아남습니다.