devcontainer의 Claude Code

bypassPermissions를 안전하게 활성화한 상태에서 Claude Code를 실행하기 위한 샌드박스 개발 환경입니다. 보안 감사 워크플로를 위해 Trail of Bits에서 제작했습니다.

왜 사용해야 하나요?

호스트 머신에서 bypassPermissions로 Claude를 실행하는 것은 위험합니다. 확인 없이 어떤 명령이든 실행할 수 있기 때문입니다. 이 devcontainer는 파일시스템 격리를 제공하므로 호스트 시스템을 위험에 빠뜨리지 않으면서 제한 없는 Claude의 생산성 이점을 얻을 수 있습니다.

다음 용도로 설계되었습니다:

• 보안 감사: 호스트를 위험에 빠뜨리지 않고 클라이언트 코드 검토
• 신뢰할 수 없는 저장소: 알 수 없는 코드베이스를 안전하게 탐색
• 실험적 작업: 격리된 환경에서 Claude가 코드를 자유롭게 수정하도록 허용
• 다중 저장소 작업: 여러 관련 저장소에서 작업

사전 요구사항

• Docker 런타임 (다음 중 하나):

  • Docker Desktop - 실행 중인지 확인
  • OrbStack
  • Colima: brew install colima docker && colima start

• 터미널 워크플로용 (1회 설치):

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# Stop and delete current VM (removes containers/images)
colima stop && colima delete

# Start with optimized settings
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

빠른 시작

워크플로에 맞는 패턴을 선택하세요:

패턴 A: 프로젝트별 컨테이너 (격리)

각 프로젝트는 독립적인 볼륨을 가진 자체 컨테이너를 갖습니다. 일회성 검토, 신뢰할 수 없는 저장소, 또는 프로젝트 간 격리가 필요할 때 가장 적합합니다.

터미널:

git clone <untrusted-repo>
cd untrusted-repo
devc .          # Installs template + starts container
devc shell      # Opens shell in container

VS Code / Cursor:

1. Dev Containers 확장 프로그램을 설치하세요:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. devcontainer를 설정하세요 (다음 중 하나 선택):

   root@kitploit:~

   # Option A: Use devc (recommended)
   devc .
   
   # Option B: Clone manually
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. VS Code에서 프로젝트 폴더를 연 다음:

   • Cmd+Shift+P(Mac) 또는 Ctrl+Shift+P(Windows/Linux)를 누르세요
   • "Reopen in Container"를 입력하고 Dev Containers: Reopen in Container를 선택하세요

패턴 B: 공유 워크스페이스 컨테이너 (그룹)

상위 디렉터리에 devcontainer 구성이 포함되고, 내부에 여러 저장소를 클론합니다. 모든 저장소 간에 볼륨이 공유됩니다. 클라이언트 프로젝트, 관련 저장소 또는 지속적인 작업에 가장 적합합니다.

# Create workspace for a client engagement
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc .          # Install template + start container
devc shell      # Opens shell in container

# Inside container:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude          # Ready to work

토큰 기반 인증 (헤드리스)

헤드리스 서버용 또는 대화형 로그인 마법사를 건너뛰려면:

claude setup-token                          # run on host, one-time
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # rebuilds with token

토큰은 컨테이너로 전달됩니다. 컨테이너가 생성될 때마다 post_install.py가 일회성 인증 핸드셰이크를 실행하므로 claude가 로그인 마법사 없이 시작됩니다.

이는 유효한 자격 증명이 있어도 컨테이너에서 항상 표시되는 Claude Code의 대화형 온보딩 마법사를 우회합니다 (#8938).

토큰을 설정하지 않으면 대화형 로그인 흐름이 이전과 같이 작동합니다.

CLI 도우미 명령

devc .              Install template + start container in current directory
devc up             Start the devcontainer
devc rebuild        Rebuild container (preserves persistent volumes)
devc destroy [-f]   Remove container, volumes, and image for current project
devc down           Stop the container
devc shell          Open zsh shell in container
devc exec CMD       Execute command inside the container
devc upgrade        Upgrade Claude Code in the container
devc mount SRC DST  Add a bind mount (host → container)
devc sync [NAME]    Sync Claude Code sessions from devcontainers to host
devc template DIR   Copy devcontainer files to directory
devc self-install   Install devc to ~/.local/bin

참고: 프로젝트의 Docker 리소스를 정리하려면 devc destroy를 사용하세요. 수동으로 컨테이너를 제거하면(예: docker rm) 고아 볼륨과 이미지가 남게 되어 devc destroy가 이를 찾을 수 없습니다.

/insights용 세션 동기화

Claude Code의 /insights 명령은 세션 기록을 분석하지만 호스트의 ~/.claude/projects/에서만 읽습니다. devcontainer 볼륨 내부의 세션은 이 명령에 보이지 않습니다.

devc sync는 모든 devcontainer(실행 중 및 중지된)의 세션 로그를 호스트로 복사하여 /insights가 이를 포함할 수 있게 합니다:

devc sync              # Sync all devcontainers
devc sync crypto       # Filter by project name (substring match)

Devcontainer는 Docker 라벨을 통해 자동으로 검색됩니다. 컨테이너 이름이나 ID를 알 필요가 없습니다. 동기화는 증분 방식이므로 반복 실행해도 안전합니다.

파일 공유

VS Code / Cursor

호스트의 파일을 VS Code 탐색기 패널로 끌어다 놓으면 /workspace/에 자동으로 복사됩니다. 구성이 필요 없습니다.

터미널: devc mount

호스트 디렉터리를 컨테이너 내부에서 사용할 수 있게 하려면:

devc mount ~/drop /drop           # Read-write
devc mount ~/secrets /secrets --readonly

이는 devcontainer.json에 바인드 마운트를 추가하고 컨테이너를 다시 생성합니다. 기존 마운트는 devc template 업데이트에도 유지됩니다.

팁: 공유 "드롭 폴더"는 전체 홈 디렉터리를 마운트하지 않고 파일을 전달하는 데 유용합니다.

보안 참고: 큰 호스트 디렉터리(예: $HOME)를 마운트하지 마세요. --readonly를 지정하지 않는 한 마운트된 모든 경로는 컨테이너 내부에서 쓰기 가능하며, 이는 이 프로젝트가 제공하는 파일시스템 격리를 약화시킵니다.

네트워크 격리

기본적으로 컨테이너는 완전한 아웃바운드 네트워크 액세스 권한을 갖습니다. 더 엄격한 보안을 위해 iptables를 사용하여 네트워크 액세스를 제한하세요.

네트워크 격리를 활성화해야 하는 경우

• 악성 의존성을 포함할 수 있는 코드 검토
• 원격 측정(telemetry) 또는 phone-home 동작이 있는 소프트웨어 감사
• 매우 민감한 검토를 위한 최대 격리

예시: Claude + GitHub + 패키지 레지스트리

sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP

장단점

• 레지스트리를 허용 목록에 추가하지 않으면 패키지 관리자가 차단됨
• 네트워크 액세스가 필요한 도구가 작동하지 않을 수 있음
• DNS 확인은 여전히 작동함(민감한 경우 차단 고려)

위협 모델

이 프로젝트가 해결하는 주요 위협은 호스트 머신에서 임의의 명령을 실행하는 Claude Code입니다. bypassPermissions가 활성화되면 Claude는 확인 없이 셸 명령을 실행하고, 패키지를 설치하고, 파일을 수정합니다. 호스트 머신에서는 셸 구성을 수정하거나, 프로젝트 디렉터리 밖에서 rm -rf를 실행하거나, 로컬에 저장된 자격 증명을 남용할 수 있음을 의미합니다. devcontainer는 이 모든 것을 피해 범위가 /workspace로 제한된 일회용 컨테이너 안에 가둡니다.

컨테이너에는 일반적인 개발 도구가 포함되어 있어 Claude를 실행하는 것뿐만 아니라 모든 개발 작업을 내부에서 수행할 수 있습니다. 의도된 워크플로는 다음과 같습니다: 저장소를 클론하고, devcontainer를 시작하고, 완전히 그 안에서 작업합니다. 프로젝트에 포함된 것 이상의 추가 런타임이나 도구가 필요한 경우, 반복 사용을 위해 Dockerfile에 추가하거나 devc exec로 임시 설치하세요.

격리되는 것과 격리되지 않는 것의 구체적인 경계는 아래 보안 모델을 참조하세요. 짚고 넘어갈 한 가지 미묘한 점: devcontainer 런타임은 호스트의 SSH 에이전트 소켓(SSH_AUTH_SOCK)을 자동으로 컨테이너로 전달합니다. 이를 통해 컨테이너 내부의 코드가 SSH를 통해 사용자로 인증할 수 있지만(예: git push), 실제 개인 키 자료는 호스트에 남아 있으며 컨테이너에 노출되지 않습니다.

보안 모델

이 devcontainer는 파일시스템 격리를 제공하지만 완전한 샌드박싱은 아닙니다.

샌드박스됨: 파일시스템(호스트 파일 접근 불가), 프로세스(호스트에서 격리), 패키지 설치(컨테이너에 유지)

샌드박스되지 않음: 네트워크(기본적으로 전체 아웃바운드—네트워크 격리 참조), git 신원(~/.gitconfig 읽기 전용으로 마운트), SSH 에이전트(소켓 전달, 키는 호스트에 유지), Docker 소켓(기본적으로 마운트되지 않음)

컨테이너는 bypassPermissions 모드를 자동으로 구성합니다. Claude는 확인 없이 명령을 실행합니다. 호스트 머신에서는 위험할 수 있지만, 컨테이너 자체가 샌드박스입니다.

컨테이너 세부 사항

볼륨은 컨테이너 외부에 저장되므로 셸 기록, Claude 설정 및 gh 로그인은 devc rebuild 후에도 유지됩니다. 호스트 ~/.gitconfig는 git 신원용으로 읽기 전용 마운트됩니다.

문제 해결

"devcontainer CLI를 찾을 수 없음"

npm install -g @devcontainers/cli

컨테이너가 시작되지 않음

1. Docker가 실행 중인지 확인
2. 재빌드 시도: devc rebuild
3. 로그 확인: docker logs $(docker ps -lq)

GitHub CLI 인증이 유지되지 않음

gh 볼륨의 소유권 수정이 필요할 수 있습니다:

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv가 작동하지 않음

Python은 uv를 통해 관리됩니다:

uv run script.py              # Run a script
uv add package                # Add project dependency
uv run --with requests py.py  # Ad-hoc dependency

개발

이미지를 수동으로 빌드:

devcontainer build --workspace-folder .

컨테이너 테스트:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh