Dev Container 설정

일관되고 보안이 강화된 개발 환경이 필요한 팀을 위한 Claude Code 개발 컨테이너(devcontainer) 설정 방법을 안내합니다.

참조 devcontainer 설정과 관련 Dockerfile은 그대로 사용하거나 필요에 따라 커스터마이즈할 수 있는 사전 구성된 개발 컨테이너를 제공합니다. 이 devcontainer는 Visual Studio Code Dev Containers 확장 및 유사한 도구와 함께 작동합니다.

컨테이너의 강화된 보안 조치(격리 및 방화벽 규칙)를 통해 무인 작업을 위한 권한 프롬프트를 우회하는 claude --dangerously-skip-permissions를 안전하게 실행할 수 있습니다.

주의: devcontainer가 상당한 보호를 제공하지만, 어떤 시스템도 모든 공격에 완전히 면역되지는 않습니다. --dangerously-skip-permissions로 실행할 때, devcontainer는 악성 프로젝트가 Claude Code 자격 증명을 포함한 devcontainer 내의 모든 접근 가능한 항목을 유출하는 것을 막지 못합니다. 신뢰할 수 있는 저장소에서 개발할 때만 devcontainer를 사용하고, 항상 양호한 보안 관행을 유지하며 Claude의 활동을 모니터링하십시오.

주요 기능

기능	설명
프로덕션 수준 Node.js	필수 개발 의존성이 포함된 Node.js 20 기반
보안 설계	필요한 서비스에만 네트워크 접근을 제한하는 커스텀 방화벽
개발자 친화적 도구	git, ZSH 생산성 향상, fzf 등 포함
VS Code 통합	사전 구성된 확장 및 최적화된 설정
세션 유지	컨테이너 재시작 간 명령어 히스토리 및 설정 보존
크로스 플랫폼	macOS, Windows, Linux 개발 환경 호환

4단계로 시작하기

1단계: VS Code와 Remote - Containers 확장 설치

2단계: Claude Code 참조 구현 저장소 복제

git clone https://github.com/anthropics/claude-code.git
cd claude-code

3단계: VS Code에서 저장소 열기

code .

4단계: 프롬프트가 표시되면 "Reopen in Container" 클릭 (또는 명령 팔레트 사용: Cmd+Shift+P → "Remote-Containers: Reopen in Container")

설정 구성 요소

devcontainer 설정은 세 가지 주요 구성 요소로 이루어져 있습니다.

devcontainer.json

컨테이너 설정, 확장, 볼륨 마운트를 제어합니다.

{
  "name": "Claude Code Dev",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "settings": {
    "terminal.integrated.shell.linux": "/bin/zsh"
  },
  "extensions": [
    "ms-vscode.vscode-node-debug2",
    "dbaeumer.vscode-eslint"
  ],
  "mounts": [
    "source=${localEnv:HOME}/.anthropic,target=/root/.anthropic,type=bind,consistency=cached"
  ],
  "postStartCommand": "bash .devcontainer/init-firewall.sh",
  "remoteUser": "node"
}

Dockerfile

컨테이너 이미지와 설치된 도구를 정의합니다.

FROM node:20-bullseye-slim

# 필수 도구 설치
RUN apt-get update && apt-get install -y \
    git \
    zsh \
    fzf \
    iptables \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Claude Code 설치
RUN npm install -g @anthropic-ai/claude-code

# ZSH 설정
RUN sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended

# 작업 디렉토리 설정
WORKDIR /workspace

init-firewall.sh

네트워크 보안 규칙을 설정합니다. 이 스크립트는 컨테이너 시작 시 실행되어 방화벽을 초기화합니다.

#!/bin/bash
# init-firewall.sh

# 허용할 도메인 목록
ALLOWED_DOMAINS=(
  "api.anthropic.com"
  "registry.npmjs.org"
  "github.com"
  "claude.ai"
)

# 기본 정책: 모든 아웃바운드 차단
iptables -P OUTPUT DROP

# DNS 허용
iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT

# SSH 허용
iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT

# localhost 허용
iptables -A OUTPUT -d 127.0.0.0/8 -j ACCEPT

# 허용된 도메인에 대한 규칙 적용
for domain in "${ALLOWED_DOMAINS[@]}"; do
  # DNS 조회로 IP 주소 확인 후 허용
  for ip in $(dig +short "$domain"); do
    iptables -A OUTPUT -d "$ip" -j ACCEPT
  done
done

echo "방화벽 규칙 초기화 완료"

보안 기능

컨테이너는 다층 보안 접근 방식을 구현합니다.

네트워크 격리

정밀한 접근 제어: npm 레지스트리, GitHub, Claude API 등 허용 목록에 있는 도메인으로만 아웃바운드 연결 제한
허용된 아웃바운드 연결: 방화벽은 아웃바운드 DNS 및 SSH 연결 허용
기본 차단 정책: 다른 모든 외부 네트워크 접근 차단
시작 검증: 컨테이너 초기화 시 방화벽 규칙 유효성 검사

시스템 격리

독립된 환경: 메인 시스템과 분리된 안전한 개발 환경 생성
파일 시스템 범위 제한: Claude Code의 쓰기 접근을 프로젝트 범위로 제한
자격 증명 보호: API 키와 토큰이 컨테이너 내에 안전하게 저장

커스터마이즈 옵션

devcontainer 설정은 다양한 요구에 맞게 조정할 수 있습니다.

VS Code 확장 추가

{
  "extensions": [
    "ms-vscode.vscode-node-debug2",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-python.python",
    "golang.go"
  ]
}

네트워크 접근 권한 조정

# init-firewall.sh에서 추가 도메인 허용
ALLOWED_DOMAINS=(
  "api.anthropic.com"
  "registry.npmjs.org"
  "github.com"
  "pypi.org"          # Python 패키지
  "rubygems.org"      # Ruby 패키지
  "your-internal-registry.company.com"  # 내부 레지스트리
)

리소스 할당 조정

.devcontainer/devcontainer.json에서 리소스를 설정합니다.

{
  "runArgs": [
    "--memory=4g",
    "--cpus=2"
  ]
}

셸 설정 커스터마이즈

# Dockerfile에서 ZSH 플러그인 추가
RUN git clone https://github.com/zsh-users/zsh-autosuggestions \
    ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# .zshrc 설정
RUN echo 'plugins=(git zsh-autosuggestions)' >> ~/.zshrc

사용 사례

보안 클라이언트 작업

devcontainer를 사용하여 다른 클라이언트 프로젝트를 격리하면 환경 간에 코드와 자격 증명이 혼용되지 않습니다.

프로젝트 A devcontainer
└── 클라이언트 A API 키
└── 클라이언트 A 코드베이스

프로젝트 B devcontainer
└── 클라이언트 B API 키
└── 클라이언트 B 코드베이스

팀 온보딩

새 팀원은 모든 필요한 도구와 설정이 사전 설치된 완전히 구성된 개발 환경을 몇 분 안에 사용할 수 있습니다.

# 신규 팀원 온보딩 과정
git clone https://github.com/your-org/your-project.git
cd your-project
code .
# "Reopen in Container" 클릭 -> 완료!

일관된 CI/CD 환경

CI/CD 파이프라인에서 devcontainer 설정을 미러링하여 개발과 프로덕션 환경이 일치하도록 합니다.

# .github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: your-registry/claude-code-dev:latest
    steps:
      - uses: actions/checkout@v3
      - run: npm test

다음 단계

보안 가이드 - Claude Code 보안 모범 사례
네트워크 설정 - 엔터프라이즈 네트워크 설정
VS Code 통합 - VS Code에서 Claude Code 사용
VS Code devcontainers 공식 문서 - 상세 devcontainer 가이드

일관되고 보안이 강화된 개발 환경이 필요한 팀을 위한 Claude Code 개발 컨테이너(devcontainer) 설정 방법을 안내합니다.

주의: devcontainer가 상당한 보호를 제공하지만, 어떤 시스템도 모든 공격에 완전히 면역되지는 않습니다. --dangerously-skip-permissions로 실행할 때, devcontainer는 악성 프로젝트가 Claude Code 자격 증명을 포함한 devcontainer 내의 모든 접근 가능한 항목을 유출하는 것을 막지 못합니다. 신뢰할 수 있는 저장소에서 개발할 때만 devcontainer를 사용하고, 항상 양호한 보안 관행을 유지하며 Claude의 활동을 모니터링하십시오.

주요 기능

기능	설명
프로덕션 수준 Node.js	필수 개발 의존성이 포함된 Node.js 20 기반
보안 설계	필요한 서비스에만 네트워크 접근을 제한하는 커스텀 방화벽
개발자 친화적 도구	git, ZSH 생산성 향상, fzf 등 포함
VS Code 통합	사전 구성된 확장 및 최적화된 설정
세션 유지	컨테이너 재시작 간 명령어 히스토리 및 설정 보존
크로스 플랫폼	macOS, Windows, Linux 개발 환경 호환

4단계로 시작하기

1단계: VS Code와 Remote - Containers 확장 설치

2단계: Claude Code 참조 구현 저장소 복제

git clone https://github.com/anthropics/claude-code.git
cd claude-code

3단계: VS Code에서 저장소 열기

code .

4단계: 프롬프트가 표시되면 "Reopen in Container" 클릭 (또는 명령 팔레트 사용: Cmd+Shift+P → "Remote-Containers: Reopen in Container")

설정 구성 요소

devcontainer 설정은 세 가지 주요 구성 요소로 이루어져 있습니다.

devcontainer.json

컨테이너 설정, 확장, 볼륨 마운트를 제어합니다.

{
  "name": "Claude Code Dev",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "settings": {
    "terminal.integrated.shell.linux": "/bin/zsh"
  },
  "extensions": [
    "ms-vscode.vscode-node-debug2",
    "dbaeumer.vscode-eslint"
  ],
  "mounts": [
    "source=${localEnv:HOME}/.anthropic,target=/root/.anthropic,type=bind,consistency=cached"
  ],
  "postStartCommand": "bash .devcontainer/init-firewall.sh",
  "remoteUser": "node"
}

Dockerfile

컨테이너 이미지와 설치된 도구를 정의합니다.

FROM node:20-bullseye-slim

# 필수 도구 설치
RUN apt-get update && apt-get install -y \
    git \
    zsh \
    fzf \
    iptables \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Claude Code 설치
RUN npm install -g @anthropic-ai/claude-code

# ZSH 설정
RUN sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended

# 작업 디렉토리 설정
WORKDIR /workspace

init-firewall.sh

네트워크 보안 규칙을 설정합니다. 이 스크립트는 컨테이너 시작 시 실행되어 방화벽을 초기화합니다.

#!/bin/bash
# init-firewall.sh

# 허용할 도메인 목록
ALLOWED_DOMAINS=(
  "api.anthropic.com"
  "registry.npmjs.org"
  "github.com"
  "claude.ai"
)

# 기본 정책: 모든 아웃바운드 차단
iptables -P OUTPUT DROP

# DNS 허용
iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT

# SSH 허용
iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT

# localhost 허용
iptables -A OUTPUT -d 127.0.0.0/8 -j ACCEPT

# 허용된 도메인에 대한 규칙 적용
for domain in "${ALLOWED_DOMAINS[@]}"; do
  # DNS 조회로 IP 주소 확인 후 허용
  for ip in $(dig +short "$domain"); do
    iptables -A OUTPUT -d "$ip" -j ACCEPT
  done
done

echo "방화벽 규칙 초기화 완료"

보안 기능

컨테이너는 다층 보안 접근 방식을 구현합니다.

네트워크 격리

정밀한 접근 제어: npm 레지스트리, GitHub, Claude API 등 허용 목록에 있는 도메인으로만 아웃바운드 연결 제한
허용된 아웃바운드 연결: 방화벽은 아웃바운드 DNS 및 SSH 연결 허용
기본 차단 정책: 다른 모든 외부 네트워크 접근 차단
시작 검증: 컨테이너 초기화 시 방화벽 규칙 유효성 검사

시스템 격리

독립된 환경: 메인 시스템과 분리된 안전한 개발 환경 생성
파일 시스템 범위 제한: Claude Code의 쓰기 접근을 프로젝트 범위로 제한
자격 증명 보호: API 키와 토큰이 컨테이너 내에 안전하게 저장

커스터마이즈 옵션

devcontainer 설정은 다양한 요구에 맞게 조정할 수 있습니다.

VS Code 확장 추가

{
  "extensions": [
    "ms-vscode.vscode-node-debug2",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-python.python",
    "golang.go"
  ]
}

네트워크 접근 권한 조정

# init-firewall.sh에서 추가 도메인 허용
ALLOWED_DOMAINS=(
  "api.anthropic.com"
  "registry.npmjs.org"
  "github.com"
  "pypi.org"          # Python 패키지
  "rubygems.org"      # Ruby 패키지
  "your-internal-registry.company.com"  # 내부 레지스트리
)

리소스 할당 조정

.devcontainer/devcontainer.json에서 리소스를 설정합니다.

{
  "runArgs": [
    "--memory=4g",
    "--cpus=2"
  ]
}

셸 설정 커스터마이즈

# Dockerfile에서 ZSH 플러그인 추가
RUN git clone https://github.com/zsh-users/zsh-autosuggestions \
    ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# .zshrc 설정
RUN echo 'plugins=(git zsh-autosuggestions)' >> ~/.zshrc

사용 사례

보안 클라이언트 작업

devcontainer를 사용하여 다른 클라이언트 프로젝트를 격리하면 환경 간에 코드와 자격 증명이 혼용되지 않습니다.

프로젝트 A devcontainer
└── 클라이언트 A API 키
└── 클라이언트 A 코드베이스

프로젝트 B devcontainer
└── 클라이언트 B API 키
└── 클라이언트 B 코드베이스

팀 온보딩

새 팀원은 모든 필요한 도구와 설정이 사전 설치된 완전히 구성된 개발 환경을 몇 분 안에 사용할 수 있습니다.

# 신규 팀원 온보딩 과정
git clone https://github.com/your-org/your-project.git
cd your-project
code .
# "Reopen in Container" 클릭 -> 완료!

일관된 CI/CD 환경

CI/CD 파이프라인에서 devcontainer 설정을 미러링하여 개발과 프로덕션 환경이 일치하도록 합니다.

# .github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: your-registry/claude-code-dev:latest
    steps:
      - uses: actions/checkout@v3
      - run: npm test

다음 단계

보안 가이드 - Claude Code 보안 모범 사례
네트워크 설정 - 엔터프라이즈 네트워크 설정
VS Code 통합 - VS Code에서 Claude Code 사용
VS Code devcontainers 공식 문서 - 상세 devcontainer 가이드

주요 기능

4단계로 시작하기

설정 구성 요소

devcontainer.json

Dockerfile

init-firewall.sh

보안 기능

네트워크 격리

시스템 격리

커스터마이즈 옵션

VS Code 확장 추가

네트워크 접근 권한 조정

리소스 할당 조정

셸 설정 커스터마이즈

사용 사례

보안 클라이언트 작업

팀 온보딩

일관된 CI/CD 환경

다음 단계

관련 가이드

주요 기능

4단계로 시작하기

설정 구성 요소

devcontainer.json

Dockerfile

init-firewall.sh

보안 기능

네트워크 격리

시스템 격리

커스터마이즈 옵션

VS Code 확장 추가

네트워크 접근 권한 조정

리소스 할당 조정

셸 설정 커스터마이즈

사용 사례

보안 클라이언트 작업

팀 온보딩

일관된 CI/CD 환경

다음 단계

관련 가이드