RchGrav/claudebox

ClaudeBox – Anthropic의 Claude Code를 위한 Docker 기반 개발 환경

개요

• Claude Code CLI(Anthropic의 AI 코딩 어시스턴트)와 일련의 개발 도구가 미리 로드된 격리된 Docker 컨테이너를 설정하는 명령줄 도구입니다.
• 각 프로젝트는 고유한 Docker 이미지, Python 가상 환경, 방화벽 허용 목록, 영구적인 Claude 인증/기록을 가지므로 교차 오염 없이 여러 프로젝트를 동시에 작업할 수 있습니다.

주요 기능

기능	내용
컨테이너화된 Claude	Debian 기반 Docker 이미지 내에서 Claude Code를 실행합니다. Docker가 없으면 자동으로 설치됩니다.
개발 프로필	언어 스택(C/C++, Python, Rust, Go, Java, JavaScript 등) 및 전문 도구 세트(OpenWRT, DevOps, 보안, 데이터 과학 등)를 클릭 한 번으로 설치합니다.
프로젝트별 격리	각 프로젝트(슬롯이라고 함)마다 별도의 Docker 이미지, 인증 파일, 셸 기록, 도구 구성을 유지합니다.
영구 구성	프로필, 설치된 패키지, Python uv 가상 환경은 컨테이너 재시작 후에도 유지됩니다.
다중 인스턴스 지원	서로 다른 프로젝트 디렉토리에서 독립적인 Claude 세션을 동시에 시작할 수 있습니다.
보안 제어	프로젝트별 방화벽 허용 목록; --enable-sudo, --disable-firewall 또는 --dangerously-skip-permissions 플래그를 선택적으로 사용할 수 있습니다.
풍부한 개발 경험	GitHub CLI, Delta, fzf, Powerline 스타일의 Zsh, 다중 창 워크플로우를 위한 tmux 통합이 내장되어 있습니다.
클립보드 브리지 (macOS)	호스트 클립보드와 컨테이너 간에 이미지/텍스트를 전달하는 선택적 서비스(20 MiB 이미지 / 1 MiB 텍스트로 제한).
작업 엔진	Claude 내부에서 간단한 /task 명령을 사용하여 코드 생성 작업을 분해하고 반복할 수 있습니다.

설치 (빠른 시작)

# 자체 압축 해제형 설치 프로그램 가져오기
wget https://github.com/RchGrav/claudebox/releases/latest/download/claudebox.run
chmod +x claudebox.run
./claudebox.run          # ~/.claudebox/source/ 에 압축 해제하고 ~/.local/bin/claudebox 에 링크 생성

설치 프로그램은 첫 실행 시 Docker를 확인하고 비루트 사용자로 설정합니다.

수동 아카이브를 선호하는 경우, Releases 페이지에서 tarball을 다운로드하여 압축을 풀고 ./main.sh 를 실행하여 심볼릭 링크를 만드십시오.

일반적인 워크플로우

# 프로젝트 디렉토리 내부
claudebox create               # 새로운 '슬롯'(영구적인 Claude 세션) 생성
claudebox slots                # 기존 슬롯 및 상태 나열
claudebox add python           # 개발 프로필 추가(선택 사항)
claudebox slot 1               # 슬롯 1에 연결 – Claude가 준비된 셸로 진입

다른 claudebox create를 실행하여 동일하거나 다른 프로젝트에서 또 다른 슬롯을 시작할 수 있습니다. 인자 없이 claudebox를 실행하면 자동으로 비활성 슬롯이 선택됩니다.

프로필 관리

claudebox profiles                 # 사용 가능한 모든 프로필과 설명 나열
claudebox profile                 # 프로필 추가/제거를 위한 대화형 메뉴
claudebox profile status          # 현재 프로젝트에서 활성화된 프로필 확인
claudebox profile rust go         # 이 프로젝트에 Rust 및 Go 툴체인 설치

프로필은 프로젝트의 Docker 이미지 내에 캐시되므로, 새 프로필을 설치하면 해당 이미지만 다시 빌드됩니다.

사용자 지정 플래그로 Claude 실행

claudebox --model opus -c          # *opus* 모델과 코드 생성 모드로 Claude 시작
claudebox save --enable-sudo       # 플래그를 저장하여 향후 실행 시 상속

저장된 플래그는 로컬에 저장되며 후속 claudebox 명령에 자동으로 적용됩니다.

클립보드 지원 (macOS 전용)

claudebox --clipboard               # 호스트 클립보드를 읽고 쓸 수 있는 세션 시작

이 브리지는 localhost에 바인딩된 단기 HTTP 리스너를 생성합니다. 세션 토큰이 비밀 키 역할을 합니다. 보안상 기본적으로 비활성화되어 있습니다.

정리 및 유지 관리

• claudebox clean – 프로필 파일, 프로젝트 데이터, Docker 이미지 또는 현재 프로젝트의 모든 항목을 삭제하는 대화형 메뉴.
• claudebox clean --containers / --image / --cache / --volumes – 전역 Docker 정리 옵션.
• claudebox rebuild – 프로젝트의 Docker 이미지를 강제로 다시 빌드합니다.

데이터 저장 위치

• ~/.claudebox/source/ – 설치된 스크립트.
• ~/.claudebox/projects/<project-id>/ – 프로젝트별 상태(프로필, Docker 이미지 태그, 방화벽 규칙, Python venv 등).
• ~/.claudebox/projects/<project-id>/<slot-id>/.claude/ – Claude 인증 토큰, 세션 기록 및 구성 파일.
• 호스트 작업 공간은 컨테이너 내부의 /workspace에 읽기/쓰기 가능하게 마운트되며, 호스트의 ~/.gitconfig는 읽기 전용으로 마운트됩니다.

대상 사용자

• Docker, 언어 런타임 또는 보안 설정을 수동으로 구성하지 않고도 Claude Code를 위한 재현 가능하고 격리된 환경을 원하는 개발자.
• 단일 호스트 머신을 공유하면서 프로젝트별 샌드박스(다른 Python 버전, 개별 네트워크 허용 목록 등)가 필요한 팀.
• 전체 개발 워크스테이션을 미러링하는 '플러그 앤 플레이' AI 지원 코딩 설정을 찾는 모든 사람.

라이선스

• MIT (LICENSE 참조).

---

위의 모든 정보는 저장소의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.