HolyClaude 소개
최근 인공지능 기반의 코딩 어시스턴트 도구들이 폭발적으로 성장하고 있는 가운데, Anthropic의 공식 CLI 도구인 'Claude Code'는 많은 개발자에게 강력한 터미널 기반의 AI 페어 프로그래밍 환경을 제공하고 있습니다. 하지만 이를 로컬 환경에 직접 설치하고 브라우저 테스트나 여러 모델을 동시에 구동하기 위해서는 꽤 복잡한 환경 설정과 종속성 관리가 필요합니다. 이러한 불편함을 혁신적으로 해결하기 위해 등장한 오픈소스 프로젝트가 바로 HolyClaude입니다. HolyClaude 프로젝트는 순정 Claude Code CLI를 기반으로 웹 UI, Headless 브라우저, 그리고 50여 개 이상의 다양한 개발 도구를 하나의 Docker 컨테이너 안에 완벽하게 번들링하여 제공합니다.
HolyClaude의 가장 큰 목적은 개발자가 언제 어디서나 브라우저만 열면 즉시 최고 수준의 AI 코딩 워크스테이션에 접속할 수 있도록 만드는 것입니다. 홈 서버나 원격 VPS(가상 사설 서버)에 이 컨테이너를 띄워두면, 로컬 노트북이나 심지어 모바일 기기에서도 포트(기본 3001번)를 통해 접속하여 무거운 작업이나 장시간이 소요되는 코드 분석을 서버 측에 온전히 위임할 수 있습니다.
특히, 이 프로젝트는 단순한 래퍼(Wrapper)나 서드파티 프록시 서버를 거치는 방식이 아니라, Anthropic의 공식 데스크톱 환경과 동일한 인증 방식을 사용하여 보안과 신뢰성을 확보했습니다. 이를 통해 개발자는 복잡한 환경 설정에 시간을 낭비하지 않고, 오직 코드 작성과 문제 해결이라는 본연의 업무에만 집중할 수 있는 쾌적한 환경을 구축할 수 있습니다.
HolyClaude vs. 기존 터미널 기반 CLI 환경과의 비교
기존의 Claude Code는 사용자의 로컬 머신 터미널에 직접 설치하여 구동하는 방식이었습니다. 이 경우 터미널 환경을 벗어나기 어렵고, 데스크톱이나 노트북을 켜두어야만 작업이 유지된다는 단점이 있었습니다.
┌─────────────────────────────────────────────────┐
│ Docker Container │
│ │
│ entrypoint.sh (runs once) │
│ ├── UID/GID remapping │
│ ├── Pre-create required files │
│ ├── bootstrap.sh (first boot only) │
│ │ ├── Copy settings.json │
│ │ ├── Copy CLAUDE.md (memory) │
│ │ ├── Configure git │
│ │ └── Create sentinel file │
│ └── exec /init (s6-overlay) │
│ │
│ s6-overlay (PID 1) │
│ ├── cloudcli (longrun) │
│ │ └── claude-code-ui --port 3001 │
│ └── xvfb (longrun) │
│ └── Xvfb :99 -screen 0 1920x1080x24 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Claude │ │ Chromium │ │ Dev Tools │ │
│ │ Code CLI │ │ headless │ │ Node, Python │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
│ │
│ Bind Mounts: │
│ ~/.claude ←→ ./data/claude (host) │
│ /workspace ←→ ./workspace (host) │
└─────────────────────────────────────────────────┘
반면 HolyClaude는 Docker 컨테이너 내부에 웹 UI를 구축함으로써, SSH 접속이나 복잡한 클라이언트 프로그램 설치 없이 웹 브라우저만으로 모든 기능을 제어할 수 있게 해줍니다.
또한, 기존 환경에서 Claude에게 웹 스크래핑이나 E2E(End-to-End) 테스트를 위해 브라우저 화면 캡처를 지시하려면 공유 메모리(Shared Memory) 제한 문제나 xvfb 디스플레이 설정, 샌드박스 우회 등 Docker와 브라우저 간의 골치 아픈 충돌을 개발자가 직접 해결해야 했습니다.
HolyClaude는 이러한 Headless Chromium 및 Playwright 설정을 컨테이너 단계에서 모두 사전 구성하여 배포하므로, 사용자는 아무런 추가 설정 없이도 "이 웹사이트에 들어가서 스크린샷을 찍어줘"와 같은 명령을 즉시 실행할 수 있다는 결정적인 차별점을 가집니다.
HolyClaude 주요 기능 및 특징 상세
graph TB
subgraph Docker Container
EP["entrypoint.sh"] --> BS["bootstrap.sh\n(first boot only)"]
EP --> S6["s6-overlay\n(PID 1)"]
S6 --> CC["CloudCLI\n(:3001)"]
S6 --> XV["Xvfb\n(:99)"]
CC --> CLAUDE["Claude Code CLI"]
CLAUDE --> TOOLS["Dev Tools\n(Node, Python, Git...)"]
CLAUDE --> CHROME["Chromium\n(headless)"]
XV -.-> CHROME
end
subgraph Host
DATA["./data/claude"] -.->|bind mount| HOME["~/.claude"]
WS["./workspace"] -.->|bind mount| WORK["/workspace"]
end
USER["Browser"] -->|":3001"| CC
style S6 fill:#2d3748,color:#fff
style CC fill:#6366f1,color:#fff
style CLAUDE fill:#f59e0b,color:#000
Anthropic 구독 플랜(Subscription) 및 API 완벽 지원
HolyClaude는 사용자가 API 키를 발급받아 종량제로 사용하는 방식뿐만 아니라, 기존 공식 웹사이트에서 사용하는 Anthropic 계정 로그인을 그대로 지원합니다. 데스크톱에서 로그인하는 것과 완전히 동일한 방식을 취하기 때문에, Claude Pro 플랜이나 Max 플랜과 같은 정기 구독(Subscription) 서비스 사용자들도 추가적인 API 비용 지불 없이 자신의 구독 혜택을 컨테이너 환경에서 그대로 누릴 수 있습니다. 물론 필요에 따라 API 키를 입력하여 사용하는 하이브리드 방식도 모두 정상적으로 작동하므로, 사용자의 예산과 상황에 맞춰 가장 유리한 요금제를 선택할 수 있는 뛰어난 유연성을 제공합니다.
다중 코딩 에이전트(Coding Agents) 환경 통합
HolyClaude 프로젝트는 Claude 모델에만 국한되지 않습니다. 개발자가 다양한 AI 모델의 특성을 비교하고 교차 검증할 수 있도록, 컨테이너 내부에 Gemini CLI, OpenAI Codex, Cursor, 그리고 Taskmaster AI 등 다양한 서드파티 코딩 에이전트(Coding Agents)들을 함께 번들링하여 제공합니다.
이는 매우 강력한 장점입니다. 별도의 가상 환경(Virtual Environment)이나 각각의 CLI 도구를 일일이 설치할 필요 없이, HolyClaude 컨테이너 하나만 실행하면 동일한 작업 공간(Workspace) 및 코드베이스 위에서 여러 AI 모델을 즉시 호출할 수 있습니다. 예를 들어, Claude가 작성한 복잡한 로직을 OpenAI Codex를 통해 이중 검증(Double-check)하거나, 특정 작업에 더 특화된 Gemini 모델을 유연하게 꺼내어 쓰는 등 진정한 의미의 멀티 에이전트 워크플로우를 손쉽게 구현할 수 있습니다.
Headless Chromium 및 Playwright 사전 구성 완료
AI 에이전트가 코드를 작성하는 것을 넘어 실제로 웹 애플리케이션을 테스트하고 시각적인 디버깅을 수행하려면 브라우저 제어 권한이 필수적입니다. HolyClaude 컨테이너는 내부적으로 Headless Chromium과 Playwright를 이미 완벽하게 설정해 두었습니다.
일반적인 Docker 환경에서는 브라우저를 띄울 때 기본 할당된 64MB의 공유 메모리 제한으로 인해 브라우저가 즉시 크래시(Crash)되는 현상이 빈번하게 발생합니다. 이 프로젝트는 docker-compose.yml 단계에서 shm_size: 2g, SYS_ADMIN, SYS_PTRACE 권한 부여 및 seccomp=unconfined 보안 옵션 해제 등을 통해 샌드박스 충돌 문제를 원천적으로 해결했습니다. 또한 가상 디스플레이(xvfb)의 실행 순서 문제까지 s6-overlay 프로세스 관리자를 통해 깔끔하게 제어하므로, 사용자는 브라우저 자동화와 관련된 어떠한 스트레스도 받을 필요가 없습니다.
s6-overlay 기반의 안정적인 프로세스 관리와 다중 아키텍처 지원
하나의 컨테이너 안에서 웹 UI 포트(3001번), 가상 디스플레이, 다양한 AI CLI, 그리고 프로세스 통신 로직이 동시에 돌아가기 위해서는 강력한 프로세스 감독 시스템이 필요합니다. HolyClaude는 단순한 Bash 루프나 Supervisord 대신 s6-overlay를 채택하여, 각 데몬(Daemon) 간의 종속성 실행 순서를 보장하고 컨테이너 종료 시 좀비 프로세스(Zombie Process)가 남지 않도록 깔끔한 셧다운(Clean Shutdown)을 지원합니다.
또한, 이 이미지는 Buildx와 QEMU를 활용해 x86(amd64) 머신뿐만 아니라 라즈베리 파이나 최신 Mac에서 사용되는 ARM64 아키텍처까지 네이티브로 완벽하게 지원하므로, 어떤 홈 서버나 클라우드 환경에서도 호환성 걱정 없이 바로 배포할 수 있습니다.
라이선스
HolyClaude 프로젝트는 MIT License로 공개 및 배포되고 있습니다.
HolyClaude 공식 홈페이지
HolyClaude 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 