Claude Code History Viewer를 웹 서버로 실행하세요 — 어디서든 브라우저로 대화 기록을 확인할 수 있습니다.
- 어떤 방법을 선택해야 하나요?
- 방법 1: 로컬 + 터널 — 지금 바로 테스트
- 방법 2: VPS에 설치 — 상시 운영 추천
- 방법 3: Docker로 VPS 배포 — Docker 사용자용
- 방법 4: 소스에서 빌드 — 기여자/포크 사용자용
- 설정 레퍼런스
- 문제 해결
| 방법 | 추천 대상 | 난이도 | 비용 |
|---|---|---|---|
| 로컬 + 터널 | 빠른 테스트, 데모 | 쉬움 | 무료 |
| VPS + 바이너리 | 24/7 원격 접속 | 보통 | ~$5/월 |
| Docker + VPS | Docker 익숙한 분 | 보통 | ~$5/월 |
| 소스 빌드 | 기여자, 포크 | 어려움 | ~$5/월 |
지금 바로 테스트. VPS 없이, 카드 등록 없이 사용해볼 수 있습니다.
Cloudflare Tunnel을 사용해서 로컬 서버를 인터넷에 무료로 노출합니다.
- macOS 또는 Linux
- Homebrew (macOS) 또는 apt (Linux)
1. cloudflared 설치
# macOS
brew install cloudflared
# Ubuntu/Debian
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install -y cloudflared2. 서버 설치 및 실행
# Homebrew (추천)
brew install jhlee0409/tap/cchv-server
cchv-server --serve
# 또는 소스에서 빌드
git clone https://github.com/jhlee0409/claude-code-history-viewer.git
cd claude-code-history-viewer
just setup
just serve-build-run이런 출력이 나옵니다:
🔑 Auth token: e60ed7c7-36ba-4ab8-a6a5-bc9678300b39
Open in browser: http://192.168.1.10:3727?token=e60ed7c7-...
🚀 WebUI server running at http://0.0.0.0:3727
3. 터널 생성 (새 터미널에서)
cloudflared tunnel --url http://localhost:3727이런 공개 URL이 나옵니다:
https://random-words-here.trycloudflare.com
4. 브라우저에서 접속
터널 URL과 토큰을 합칩니다:
https://random-words-here.trycloudflare.com?token=e60ed7c7-36ba-4ab8-a6a5-bc9678300b39
LTE 폰, 다른 컴퓨터 등 어디서든 접속됩니다.
- 터널 재시작할 때마다 URL이 바뀜
- 가동 시간 보장 없음 (무료 서비스)
- 상시 접속이 필요하면 방법 2 (VPS) 사용
상시 운영 추천. 한 번 설정하면 항상 접속 가능합니다.
아래 중 하나에 가입하세요. 가장 저렴한 플랜이면 충분합니다:
| 업체 | 링크 | 가격 |
|---|---|---|
| DigitalOcean | digitalocean.com | $4/월 |
| Vultr | vultr.com | $3.50/월 |
| Hetzner | hetzner.com | 3.79€/월 |
| Oracle Cloud | cloud.oracle.com | 무료 (ARM) |
서버 생성 시:
- OS: Ubuntu 22.04 또는 24.04
- 크기: RAM 1GB이면 충분
- 지역: 본인과 가까운 곳
생성하면 공인 IP 주소를 받습니다 (예: 203.0.113.50).
ssh root@203.0.113.50
# (본인의 IP로 바꾸세요)# 방법 A: Homebrew (macOS / Linux)
brew install jhlee0409/tap/cchv-server
# 방법 B: 설치 스크립트
curl -fsSL https://raw.githubusercontent.com/jhlee0409/claude-code-history-viewer/main/install-server.sh | sh두 방법 모두 OS/아키텍처를 자동 감지해서 cchv-server를 PATH에 설치합니다.
대화 기록은 로컬 머신의 ~/.claude에 있습니다. VPS로 복사하세요:
# 로컬 머신에서 실행 (VPS가 아님!)
rsync -avz ~/.claude root@203.0.113.50:~/.claudeCodex CLI, OpenCode 데이터도 함께 복사하려면:
rsync -avz ~/.claude ~/.codex ~/.local/share/opencode root@203.0.113.50:~/# VPS에서 실행
sudo ufw allow 3727/tcp
sudo ufw enable주의: DigitalOcean, AWS 등 일부 업체는 웹 콘솔에서도 방화벽(Security Group) 설정이 필요합니다. 포트 3727을 허용하세요.
cchv-server --serve출력:
🔑 Auth token: a1b2c3d4-...
Open in browser: http://203.0.113.50:3727?token=a1b2c3d4-...
🚀 WebUI server running at http://0.0.0.0:3727
브라우저에서 출력된 URL을 열면 끝!
SSH를 닫으면 서버도 꺼집니다. 항상 켜두려면:
# 서비스 파일 다운로드
curl -fsSL https://raw.githubusercontent.com/jhlee0409/claude-code-history-viewer/main/contrib/cchv.service | sudo tee /etc/systemd/system/cchv.service > /dev/null
# 편집 — YOUR_USERNAME_HERE를 본인 계정으로 변경
sudo systemctl edit --full cchv.service
# 활성화 및 시작
sudo systemctl enable --now cchv.service
# 상태 확인
sudo systemctl status cchv.service이제 VPS가 재부팅되어도 서버가 자동으로 시작됩니다.
로컬에서 새 대화를 할 때마다 VPS에도 반영하고 싶다면:
# 로컬 머신에서 crontab 편집
crontab -e
# 아래 줄 추가 (30분마다 자동 동기화):
*/30 * * * * rsync -avz ~/.claude root@203.0.113.50:~/.claude --quiet수동으로 동기화할 때:
rsync -avz ~/.claude root@203.0.113.50:~/.claudeDocker를 선호한다면 가장 간편합니다.
- Docker가 설치된 VPS (설치 가이드)
1. VPS에 접속
ssh root@203.0.113.502. 클론 및 시작
git clone https://github.com/jhlee0409/claude-code-history-viewer.git
cd claude-code-history-viewer
docker compose up -d3. 토큰 확인
docker compose logs webui
# 🔑 Auth token: ... ← 이 줄을 찾으세요4. 브라우저에서 접속
http://203.0.113.50:3727?token=여기에_토큰_붙여넣기
재시작할 때마다 토큰이 바뀌는 게 불편하면:
# docker-compose.yml의 command 수정:
command: ["--port", "3727", "--token", "내-고정-토큰"]기여자, 포크 관리자, 또는 커스텀 빌드가 필요한 분.
- Node.js 18+, pnpm, Rust 툴체인
- 자세한 요구사항: Build from Source
git clone https://github.com/jhlee0409/claude-code-history-viewer.git
cd claude-code-history-viewer
just setup
just serve-build바이너리 위치: src-tauri/target/release/claude-code-history-viewer
# 바이너리를 VPS로 복사
scp src-tauri/target/release/claude-code-history-viewer root@203.0.113.50:/usr/local/bin/cchv-server
# VPS에서 실행
ssh root@203.0.113.50
chmod +x /usr/local/bin/cchv-server
cchv-server --serve프론트엔드를 수정하면서 테스트할 때:
just serve-dev # dist/ 디렉토리에서 서빙 (내장 아님)코드 수정 → pnpm build → 브라우저 새로고침.
| 플래그 | 기본값 | 설명 |
|---|---|---|
--serve |
— | 필수. 서버 모드 시작 |
--port <숫자> |
3727 |
서버 포트 |
--host <주소> |
0.0.0.0 |
바인드 주소 (127.0.0.1이면 로컬 전용) |
--token <값> |
자동 (uuid) | 고정 토큰 지정 |
--no-auth |
— | 인증 비활성화 |
--dist <경로> |
내장 에셋 | 외부 dist/ 디렉토리로 오버라이드 |
/api/* 엔드포인트는 Bearer 토큰이 필요합니다.
| 접근 방법 | 사용법 |
|---|---|
| 브라우저 | http://host:3727?token=TOKEN (localStorage에 자동 저장) |
| API / curl | Authorization: Bearer TOKEN 헤더 |
| SSE | http://host:3727/api/events?token=TOKEN 쿼리 파라미터 |
팁: --token 내-고정-토큰을 사용하면 재시작해도 토큰이 바뀌지 않습니다. systemd와 함께 쓸 때 특히 유용합니다.
서버가 ~/.claude/projects/를 감시하고 파일이 바뀌면 SSE로 브라우저에 푸시합니다. Claude Code를 사용하면 뷰어가 자동으로 업데이트됩니다.
GET /health
→ { "status": "ok" }
| 원인 | 해결 |
|---|---|
| 서버가 꺼져 있음 | systemctl status cchv.service 확인 |
| IP 주소가 틀림 | VPS의 공인 IP를 사용 (0.0.0.0이나 192.168.x.x가 아님) |
| 방화벽이 포트 차단 | sudo ufw allow 3727/tcp + VPS 업체 보안그룹 확인 |
| 포트가 이미 사용 중 | lsof -ti :3727 | xargs kill 또는 --port 3728 |
토큰이 틀리거나 빠져 있습니다:
- URL에
?token=올바른_토큰확인 - 서버 로그에서
🔑 Auth token: ...확인 - 서버 재시작 시 토큰이 바뀜 →
--token플래그로 고정
서버가 로컬 머신에서 실행 중입니다. 로컬 IP(192.168.x.x)는 인터넷에서 접근할 수 없습니다.
해결:
- 방법 1 (터널) — 임시 접속
- 방법 2 (VPS) — 상시 접속
~/.claude를 로컬에서 VPS로 복사해야 합니다:
rsync -avz ~/.claude root@VPS_IP:~/.claude서버는 기본 HTTP입니다. HTTPS가 필요하면 리버스 프록시를 사용하세요:
# Caddy로 간단하게 HTTPS 적용 (인증서 자동 발급)
sudo apt install -y caddy
echo "your-domain.com { reverse_proxy localhost:3727 }" | sudo tee /etc/caddy/Caddyfile
sudo systemctl restart caddy이후 https://your-domain.com?token=...으로 접속.