Claude Code 데브컨테이너 — 정책을 넣어도 저장소 권한자면 지울 수 있고, 볼륨을 걸어도 로그인은 안 남습니다

팀 전원이 똑같은 개발 환경을 쓰게 만드는 방법으로 데브컨테이너가 자주 거론됩니다. 여기에 AI 코딩 도구를 넣으면 명령은 컨테이너 안에서 돌고 편집 결과만 내 저장소에 나타나니 격리와 편의를 같이 얻는 구성이죠. 공식 문서를 읽어 보니 그 그림은 맞는데, 문서가 스스로 두 군데에서 "이건 생각대로 안 된다"고 적어놨습니다. 하나는 조직 정책, 다른 하나는 로그인 유지입니다. 그리고 두 번째의 해법이 첫 번째 경고와 정면으로 부딪힙니다.

📌 30초 요약

• 정책 파일을 컨테이너 이미지에 넣으면 최우선으로 적용됩니다. 다만 그 설정을 만드는 파일이 저장소 안에 있습니다.
• 저장소 쓰기 권한이 있는 사람이면 그 줄을 지울 수 있습니다. 문서가 직접 적어놓은 문장입니다.
• 기본값은 재빌드 때마다 홈이 지워지는 것이라 매번 다시 로그인해야 합니다.
• 볼륨을 걸어도 그대로 풀립니다. 계정 정보가 그 폴더 바깥의 별도 파일에 있어서요.
• 그 파일까지 볼륨 안으로 옮기면 로그인은 유지됩니다. 대신 유출 위험 목록에 자격증명이 추가됩니다.
• 버전 태그 1.0은 CLI 버전이 아닙니다. 설치 스크립트 태그라서 도구는 항상 최신이 깔리고 안에서 자동 업데이트까지 합니다.

컨테이너에 넣으면 무엇이 달라지나

구조는 단순합니다. AI가 실행하는 명령은 컨테이너 안에서 돌고, 내 저장소는 컨테이너 안 작업 폴더로 연결돼 있어서 편집 결과는 로컬 저장소에 그대로 나타납니다. 에디터는 호스트에 있지만 통합 터미널·언어 서버·빌드 도구가 전부 컨테이너 안에서 도는 형태죠. 그러니 AI가 보는 파일과 의존성이 팀 다른 사람이 보는 것과 정확히 같아집니다.

전제가 하나 있는데, 에디터가 데브컨테이너 규격을 지원해야 합니다. 문서가 예로 든 건 VS Code·깃허브 코드스페이스·젯브레인즈·커서고, 평범한 Vim처럼 지원이 없는 에디터는 이 방식의 대상이 아니라고 못 박습니다. 설치는 전용 기능 하나를 설정 파일에 적는 것으로 끝납니다.

// .devcontainer/devcontainer.json
{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    // 이 :1.0 은 CLI 버전이 아니라 설치 스크립트 태그입니다
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}

빌드가 Node 설치 실패 메시지로 멈추는 경우가 있는데, 기본 이미지에 Node가 없을 때입니다. 문서의 처방은 Node 기능을 이 기능보다 위에 한 줄 추가하고 다시 빌드하는 것입니다. 순서가 조건이라는 점만 기억하면 됩니다. 브라우저 로그인이 끝났는데 컨테이너로 돌아오지 않는 경우도 문서가 짚는데, 화면에 뜬 코드를 복사해 터미널에 붙여넣으면 됩니다.

조직 정책을 여기 넣으면, 정책 구실을 못 합니다

문서가 먼저 장점을 말합니다 — 같은 이미지와 같은 설정이 모든 엔지니어 기계에서 도니 정책을 적용하기 좋은 자리라고요. 실제로 컨테이너 안 특정 경로에 관리 설정 파일을 두면 설정 우선순위에서 가장 높게 적용돼, 개인이 자기 폴더나 프로젝트 폴더에 뭘 적어도 그 값이 이깁니다. 파일은 Dockerfile에서 복사해 넣으면 되고요.

⚠️ 그런데 문서가 바로 다음 문단에서 스스로 무너뜨립니다

원문 요지는 이렇습니다 — Dockerfile이 저장소 안에 있으니, 쓰기 권한이 있는 사람이면 누구나 그 단계를 바꾸거나 지울 수 있다. 정책을 이미지에 구워 넣어도 그 이미지를 만드는 설명서가 개발자가 편집할 수 있는 파일이라는 거죠. 한 줄 지우고 재빌드하면 그만입니다. 그래서 문서는 "엔지니어가 저장소 파일을 고쳐서 우회할 수 없는 정책"이 필요하면 서버에서 내려주는 관리 설정이나 기기 관리 시스템을 쓰라고 안내합니다. 정리하면 데브컨테이너의 정책은 "기본값을 맞추는 장치"이지 "못 하게 막는 장치"가 아닙니다. 둘을 구분하지 않으면 감사에서 "정책 적용됨"으로 보고했다가 곤란해질 수 있는 자리입니다.

정책을 내리는 경로	개발자가 우회 가능한가	쓸 자리
저장소의 Dockerfile로 복사	가능 — 그 줄을 지우면 끝	팀 기본값 통일
서버에서 내려주는 관리 설정	불가	지켜야 하는 규정
기기 관리 시스템	불가	회사 지급 기기 전체

정책이 아니라 환경 변수로 기본값을 맞추는 것은 이 방식이 잘 맞습니다. 문서 예시가 비필수 통신 끄기와 자동 업데이트 막기 둘인데, 여기에 조건이 하나 붙습니다 — 비필수 통신을 끄면 기능 플래그 조회까지 같이 꺼져서, 그걸 필요로 하는 기능은 컨테이너 안에서 아예 못 씁니다. 원격 제어가 대표적이고요. 이 구조는 제가 격리 방식 여섯 가지를 비교한 글에서 다룬 함정과 같은 계열입니다 — 조인 만큼 조용히 꺼지는 것이 생깁니다.

볼륨을 걸었는데 로그인이 안 남는 이유

기본 동작은 재빌드할 때 컨테이너의 홈 디렉터리가 버려지는 것입니다. 그래서 재빌드할 때마다 다시 로그인해야 하죠. 흔한 처방은 설정 폴더에 볼륨을 걸어 두는 것인데, 문서가 여기서 그것만으로는 로그인이 유지되지 않는다고 못 박습니다.

이유가 정확합니다. 인증 토큰과 사용자 설정, 세션 기록은 설정 폴더 안에 있는데, 계정 정보와 개인용 MCP 서버 목록, 프로젝트별 신뢰 여부는 그 폴더 바깥의 별도 파일에 들어 있습니다. 볼륨은 폴더만 붙잡으니 바깥 파일은 재빌드와 함께 사라집니다. 그래서 해법도 두 단계입니다 — 볼륨을 걸고, 설정 폴더 위치를 가리키는 환경 변수를 같은 경로로 지정해서 그 파일까지 볼륨 안에 쓰이게 만드는 것이죠. 어느 파일이 어디에 있는지가 왜 중요한지는 설정 파일 지도를 그려둔 글에서 한 번 정리했는데, 그 지도가 컨테이너에서는 바로 실전 문제로 나타납니다.

// 둘을 같이 해야 합니다 — 볼륨만 걸면 계정 정보가 안 남습니다
"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
],
"containerEnv": {
  "CLAUDE_CONFIG_DIR": "/home/node/.claude"
}

경로의 node 자리는 컨테이너가 쓰는 계정 이름으로 바꿔야 합니다. 저장소마다 상태를 나누고 싶으면 볼륨 이름에 컨테이너 식별 변수를 붙이면 되고요. 깃허브 코드스페이스에서는 조건이 조금 다른데 — 껐다 켜는 것으로는 남지만 재빌드하면 지워집니다. 그래서 같은 설정이 거기서도 필요하고, 아예 코드스페이스 비밀값에 토큰을 넣어 두는 방법도 문서가 안내합니다.

🔗 그 편의가 그대로 위험 목록에 올라갑니다

문서 맨 위 경고를 방금 얘기와 겹쳐 읽으면 그림이 달라집니다. 승인 절차를 통째로 건너뛰는 플래그로 실행하면, 악성 저장소가 컨테이너 안에서 접근 가능한 것을 빼낼 수 있고 거기에 설정 폴더의 자격증명이 포함된다는 내용입니다. 그런데 우리가 방금 한 일이 바로 그 자격증명을 재빌드에도 살아남는 볼륨에 영구히 얹은 것이죠.

편의와 위험이 같은 파일을 가리킵니다. 그래서 문서의 권고가 "신뢰하는 저장소에서만 쓰고 활동을 지켜보라"이고, 여기에 호스트의 SSH 키나 클라우드 자격증명 파일을 컨테이너에 마운트하지 말고 저장소 범위나 짧은 수명 토큰을 쓰라는 조건이 붙습니다. 컨테이너를 켰다고 안에 무엇을 넣어도 되는 방이 되는 게 아니라는 뜻입니다.

버전은 고정되지 않습니다

설정 파일에 적는 기능 이름 끝에 버전 태그가 붙습니다. 재현 가능한 빌드를 만들었다고 생각하기 쉬운 자리인데, 문서가 정확히 짚습니다 — 그 태그가 고정하는 건 설치 스크립트이지 도구 버전이 아닙니다. 기능은 항상 최신 릴리스를 설치하고, 게다가 컨테이너 안에서 스스로 자동 업데이트까지 합니다.

진짜로 고정하려면 기능을 쓰지 말고 Dockerfile에서 버전을 명시해 직접 설치하고, 자동 업데이트를 끄는 환경 변수를 같이 걸어야 합니다. 두 가지를 같이 해야 한다는 게 핵심입니다 — 하나만 하면 깔릴 때는 고정돼도 돌면서 올라갑니다. "모두가 같은 환경"을 목표로 컨테이너를 도입했다면 여기가 목표와 실제가 갈리는 지점입니다.

참조 구성의 파일	담는 것	필수인가
컨테이너 설정 파일	볼륨·추가 권한·확장·환경 변수	기능만 쓸 땐 최소 구성으로 충분
Dockerfile	기본 이미지·개발 도구·설치	버전 고정할 때 필요
방화벽 스크립트	허용 도메인 외 전부 차단	아님 — 추가 권한 두 개가 붙음

마지막 줄이 실무에서 갈리는 지점입니다. 컨테이너 안에서 방화벽을 돌리려면 네트워크 관련 추가 권한 두 개를 붙여야 하는데, 문서가 이 스크립트와 권한은 도구 자체에 필요한 게 아니고 빼고 회사 네트워크 통제를 쓰면 된다고 명시합니다. 참조 구성은 "이렇게 조합할 수 있다"는 예시이지 유지되는 기본 이미지가 아니라는 단서도 함께 붙어 있습니다.

🙋 정직하게 밝혀둘 것

• 제가 이 컨테이너를 직접 빌드해 돌려보지 않았습니다. 빌드 시간, 이미지 크기, 체감 속도에 대해 할 말이 없습니다.
• "컨테이너에 넣으면 안전하다"는 뜻이 아닙니다. 문서가 맨 앞에 어떤 시스템도 모든 공격에 면역이 아니다라고 적었고, 승인 건너뛰기와 겹치면 보호가 아니라 편의만 남습니다.
• 반대로 "정책이 무용하다"도 아닙니다. 저장소 안 정책도 기본값을 통일하는 효과는 실재합니다. 문제는 그걸 통제로 계산할 때이지 쓰지 말라는 게 아닙니다.
• 설정 항목과 경로 이름은 제가 우리말로 풀어 쓴 것이고, 도구 버전에 따라 달라질 수 있습니다.

🗺️ AI 지출 전체 지도

격리 환경을 어떻게 잡느냐는 회사 도입 비용에 그대로 붙습니다. 빌드 시간도, 다시 로그인하는 시간도, 정책을 잘못 계산해 다시 설계하는 시간도요. 구독과 종량제 선택부터 캐시, 모델 조합, 상한 걸기까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

자주 묻는 것

Q. 컨테이너 안이면 승인 절차를 꺼도 되나요?

문서가 조건부로 그렇다고 합니다. 컨테이너가 비관리자 계정으로 돌고 명령 실행이 컨테이너 안에 갇혀 있으니 무인 실행에 그 플래그를 쓸 수 있다는 것이죠. 관리자 계정으로 띄우면 도구가 그 플래그를 거부하니 계정 설정을 먼저 확인해야 하고요. 다만 바로 이어서 남는 위험을 적습니다 — 연결된 작업 폴더의 파일은 여전히 다 바꿀 수 있고 그건 내 호스트에 그대로 나타나며, 네트워크 정책이 허용하는 곳에는 다 닿습니다. 그래서 망 제한과 반드시 짝지으라고 하고, 프롬프트만 줄이고 싶은 거라면 검사를 거치는 자동 모드를 권합니다. 회사 차원에서 아예 못 쓰게 막는 설정도 따로 있습니다.

Q. MCP 서버는 컨테이너 안에서 어떻게 쓰나요?

문서 권고는 저장소 최상단의 프로젝트 범위 파일에 정의해서 컨테이너 설정과 함께 버전 관리에 들어가게 하라는 것입니다. 개인 설정에 넣으면 재빌드와 함께 사라지니 자연스러운 선택이죠. 여기에 조건이 둘 붙는데 — 내 컴퓨터에서 도는 방식의 서버가 의존하는 실행 파일은 Dockerfile에 같이 설치해야 하고, 원격 서버 도메인은 망 허용 목록에 추가해야 합니다. 로컬에서 잘 되던 게 컨테이너에서 안 되는 원인이 대개 이 둘 중 하나입니다.

Q. 클라우드 제공자 계정으로 쓰면 로그인 문제가 없어지나요?

브라우저 로그인 단계는 없어집니다. 세 곳의 클라우드 경유로 쓰면 그쪽 자격증명을 쓰니 브라우저 창이 안 뜹니다. 대신 문서가 전달 방식을 지정하는데 — 컨테이너 환경 변수나 코드스페이스 비밀값, 또는 클라우드의 워크로드 신원으로 넣고 호스트의 자격증명 파일을 마운트하지는 말라고 합니다. 위에서 본 경고와 같은 방향입니다 — 컨테이너 안에 있는 것은 컨테이너가 뚫리면 같이 나갑니다.

🔒 "우회 불가 경로"도 조건부였습니다 (8월 17일 추가)

이 글에서 컨테이너에 넣은 정책은 저장소 권한자면 지울 수 있으니, 우회할 수 없는 경로는 서버 관리 설정이나 기기 관리 시스템 둘뿐이라고 적었습니다. 그 서버 관리 설정을 따로 읽어 보니 "우회 불가"에 조건이 붙습니다. 셸 명령을 실행하는 설정·훅 정의·조직 지시문·일부 환경 변수는 사용자 승인을 받아야 적용되고, 거부하면 도구가 종료됩니다. 강제되긴 하지만 "모르는 사이에 적용"되지는 않는 구조죠. 한계도 있습니다 — 조직 전체에 균일하게만 적용되고 그룹별 구성은 아직 안 됩니다. 그렇다고 이 글의 결론이 뒤집히지는 않습니다 — 권한 규칙 같은 대부분의 정책은 묻지 않고 최상단으로 적용되니, 컨테이너는 여전히 통제가 아니라 기본값입니다. 승인이 갈리는 기준은 서버 관리 설정을 뜯어본 글에 표로 담았습니다.

✨ 오늘 확인한 것 정리

데브컨테이너에 넣은 조직 정책은 저장소 쓰기 권한이 있는 사람이면 지울 수 있어서 통제가 아니라 기본값입니다. 로그인은 볼륨만 걸어서는 안 남고 설정 폴더 위치를 가리키는 변수까지 같이 걸어야 하는데, 그렇게 하면 유출 위험 목록에 자격증명이 올라갑니다. 그리고 버전 태그는 CLI를 고정하지 않습니다 — 항상 최신이 깔리고 안에서 자동 업데이트까지 하니, 재현 가능한 빌드를 원하면 직접 설치 + 자동 업데이트 끄기를 같이 해야 합니다.

※ 확인 경로(2026년 8월 17일 기준): code.claude.com/docs/en/devcontainer. 설정 항목과 경로 이름, 메뉴 표현은 제가 우리말로 옮긴 것입니다.

※ 참조 구성은 예시로 제공되는 것이고 유지되는 기본 이미지가 아니라고 문서가 밝히고 있습니다. 그대로 쓰기보다 자기 도구 체계에 맞춰 옮기는 쪽을 권합니다.