레퍼런스

문제 해결 & FAQ

자주 마주치는 이슈, 빠른 답, 그리고 가장 많이 들어오는 질문들.

여기 적힌 내용과 다른 증상이라면, 플랫폼·브라우저와 ~/.purplemux/logs/의 로그 파일을 첨부해 이슈를 열어주세요.

설치와 시작

`tmux: command not found`

호스트에 tmux 3.0 이상이 필요합니다. 설치:

# macOS (Homebrew)
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

# Fedora
sudo dnf install tmux

tmux -V로 확인. 기술적으로는 2.9+가 preflight를 통과하지만, 테스트 기준은 3.0+입니다.

`node: command not found` 또는 "Node.js 20 or newer"

Node 20 LTS 이상을 설치하세요. node -v로 확인. macOS 네이티브 앱은 자체 Node를 번들하므로 이 항목은 npx / npm install -g 경로에만 해당됩니다.

"purplemux is already running (pid=…, port=…)"

다른 purplemux 인스턴스가 살아 있고 /api/health에 응답합니다. 그것을 그대로 쓰거나(출력된 URL 열기), 먼저 종료하세요:

# 찾기
ps aux | grep purplemux

# 또는 lock 파일로 바로 종료
kill $(jq -r .pid ~/.purplemux/pmux.lock)

Stale 락 — 시작이 거부되는데 프로세스는 없음

~/.purplemux/pmux.lock이 남았습니다. 제거:

rm ~/.purplemux/pmux.lock

과거에 sudo로 실행한 적이 있다면 root 소유일 수 있으니 sudo rm로 한 번 정리하세요.

`Port 8022 is in use, finding an available port...`

다른 프로세스가 8022를 사용 중입니다. 서버는 임의의 빈 포트로 폴백하고 새 URL을 출력합니다. 직접 포트를 지정하려면:

PORT=9000 purplemux

8022을 잡고 있는 프로세스는 lsof -iTCP:8022 -sTCP:LISTEN -n -P로 찾을 수 있습니다.

Windows에서 동작하나요?

공식 지원 X. purplemux는 node-pty와 tmux에 의존하는데, 둘 다 Windows 네이티브로 동작하지 않습니다. WSL2에서는 대체로 동작하지만 (사실상 Linux이므로) 테스트 범위 밖입니다.

세션과 복원

브라우저를 닫았더니 다 사라졌어요

그럴 리가 없습니다 — tmux가 모든 셸을 서버에서 유지합니다. 새로고침해도 탭이 돌아오지 않으면:

서버가 살아 있는지 확인 (http://localhost:8022/api/health).
tmux 세션 존재 확인: tmux -L purple ls.
autoResumeOnStartup 중 에러가 없었는지 ~/.purplemux/logs/purplemux.YYYY-MM-DD.N.log 확인.

tmux가 "no server running"이라면 호스트가 재부팅됐거나 tmux가 죽은 것입니다. 세션은 사라지지만 레이아웃(워크스페이스, 탭, 작업 디렉토리)은 ~/.purplemux/workspaces/{wsId}/layout.json에 보존되어 있어 다음 purplemux 시작 시 다시 launch됩니다.

Claude 세션이 resume되지 않아요

autoResumeOnStartup이 각 탭의 저장된 claude --resume <uuid>를 다시 실행하지만, 대응되는 ~/.claude/projects/.../sessionId.jsonl이 더 이상 없으면(삭제, 아카이브, 프로젝트 이동) resume이 실패합니다. 탭을 열어 새 대화를 시작하세요.

모든 탭이 "unknown" 상태입니다

unknown은 서버 재시작 전에 busy였던 탭이 아직 복구 중임을 의미합니다. resolveUnknown이 백그라운드에서 돌면서 idle (Claude 종료) 또는 ready-for-review (마지막 어시스턴트 메시지 있음)를 확정합니다. 10분 이상 unknown에 머무르면 busy stuck safety net이 조용히 idle로 넘깁니다. 전체 상태 머신은 STATUS.md 참고.

브라우저와 UI

Web Push 알림이 오지 않아요

체크리스트:

iOS Safari ≥ 16.4 만 가능. 이전 iOS는 Web Push 자체가 없습니다.
iOS는 PWA 필수. 공유 → 홈 화면에 추가 후에만 푸시가 옵니다 — 일반 Safari 탭에서는 안 옵니다.
HTTPS 필수. 자체 서명 인증서로는 안 됩니다 — Web Push 등록 자체가 조용히 거부됩니다. Tailscale Serve(자동 Let's Encrypt)나 실제 도메인 + Nginx / Caddy를 쓰세요.
알림 권한 허용. purplemux 안의 설정 → 알림 → On 과 브라우저 레벨 권한 둘 다 허용되어야 합니다.
구독이 존재해야 함. ~/.purplemux/push-subscriptions.json에 해당 디바이스 항목이 있어야 합니다. 비어 있으면 권한을 다시 부여하세요.

전체 호환성 매트릭스는 브라우저 지원 참고.

iOS Safari 16.4+인데도 알림이 안 와요

일부 iOS 버전은 PWA가 오래 닫혀 있으면 구독을 잃습니다. PWA를 열어 알림 권한을 거부했다가 다시 허용하고 push-subscriptions.json을 다시 확인하세요.

Safari 프라이빗 창에서 아무 것도 저장되지 않아요

Safari 17+ 프라이빗 창은 IndexedDB가 비활성화되어 워크스페이스 캐시가 재시작 후 살아남지 않습니다. 일반 창을 사용하세요.

모바일 터미널이 백그라운드 후 사라져요

iOS Safari는 약 30초 백그라운드면 WebSocket을 끊어버립니다. tmux는 실제 세션을 계속 유지하므로 — 탭으로 돌아오면 purplemux가 재연결하고 다시 렌더링합니다. iOS 동작이지 purplemux 문제가 아닙니다.

Firefox + Tailscale serve 인증서 경고

*.ts.net이 아닌 커스텀 도메인을 tailnet에 쓰면 Firefox가 Chrome보다 HTTPS 신뢰에 까다롭습니다. 한 번 수락하면 계속 유지됩니다.

"Browser too old" 또는 일부 기능이 안 보여요

설정 → 브라우저 체크를 실행해 API별 리포트를 보세요. 브라우저 지원의 최소 버전 미만은 기능을 그레이스풀하게 잃지만 공식 지원은 아닙니다.

네트워크와 외부 접근

인터넷에 노출해도 되나요?

가능하지만 항상 HTTPS로. 권장:

Tailscale Serve — tailscale serve --bg 8022로 WireGuard 암호화 + 자동 인증서. 포트 포워딩 불필요.
리버스 프록시 — Nginx / Caddy / Traefik. Upgrade와 Connection 헤더를 반드시 포워딩하세요. 안 그러면 WebSocket이 깨집니다.

오픈 인터넷 위 평문 HTTP는 권하지 않습니다 — 인증 쿠키는 HMAC 서명이지만 WebSocket 페이로드(터미널 바이트!)는 암호화되지 않습니다.

LAN의 다른 디바이스에서 접근이 안 돼요

기본은 localhost 전용입니다. env 또는 앱 설정으로 접근 범위를 엽니다:

HOST=lan,localhost purplemux       # LAN
HOST=tailscale,localhost purplemux # tailnet
HOST=all purplemux                 # 모두

또는 앱의 설정 → 네트워크 접근 (이 값은 ~/.purplemux/config.json에 기록). env로 HOST를 지정한 경우 이 필드는 잠깁니다. 키워드와 CIDR 문법은 포트 & 환경변수 참고.

리버스 프록시 WebSocket 이슈

/api/terminal이 연결됐다가 즉시 끊긴다면 프록시가 Upgrade / Connection 헤더를 떨어뜨리고 있습니다. 최소 Nginx 설정:

location / {
  proxy_pass http://127.0.0.1:8022;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_set_header Host $host;
}

Caddy는 WebSocket 포워딩이 기본이므로 reverse_proxy 127.0.0.1:8022만 적으면 됩니다.

데이터와 저장소

데이터는 어디에 저장되나요?

전부 로컬 ~/.purplemux/ 안. 외부로 나가는 데이터는 없습니다. 로그인 비밀번호는 config.json 안의 scrypt 해시. 전체 구조는 데이터 디렉토리 참고.

비밀번호를 잊었어요

~/.purplemux/config.json을 지우고 재시작하세요. 온보딩이 처음부터 다시 시작됩니다. 워크스페이스, 레이아웃, 히스토리는 별도 파일이라 유지됩니다.

탭 인디케이터가 영원히 "busy"에서 멈춰요

busy stuck safety net이 Claude 프로세스가 죽었다면 10분 후 조용히 idle로 전환합니다. 기다리기 싫다면 탭을 닫았다 다시 열어 로컬 상태를 리셋하세요 — 다음 훅 이벤트가 깨끗한 상태에서 재개됩니다. 근본 원인 추적은 LOG_LEVELS=hooks=debug,status=debug로 실행하세요.

기존 tmux 설정과 충돌하나요?

아니요. purplemux는 전용 소켓(-L purple)에서 자체 설정(src/config/tmux.conf)으로 격리된 tmux를 실행합니다. ~/.tmux.conf나 기존 tmux 세션은 건드리지 않습니다.

비용과 사용량

purplemux를 쓰면 비용이 절약되나요?

직접 절약시키지는 않습니다. 다만 사용량을 투명하게 만듭니다: 오늘/이달/프로젝트별 비용, 모델별 토큰 분해, 5시간/7일 rate-limit 카운트다운이 한 화면에 모여 있어 한도에 부딪치기 전에 페이스를 조절할 수 있습니다.

purplemux 자체에 비용이 드나요?

아니요. purplemux는 MIT 라이선스 오픈소스입니다. Claude Code 사용료는 Anthropic이 별도로 청구합니다.

데이터가 외부로 전송되나요?

아니요. purplemux는 완전히 셀프호스팅입니다. 외부로 나가는 네트워크 호출은 (1) 로컬 Claude CLI가 알아서 Anthropic과 통신하는 것, (2) 시작 시 update-notifier의 버전 확인뿐입니다. 버전 확인을 끄려면 NO_UPDATE_NOTIFIER=1.

다음으로

브라우저 지원 — 자세한 호환성 매트릭스와 알려진 quirk
데이터 디렉토리 — 각 파일의 역할과 삭제 안전성
아키텍처 — 더 깊이 파야 할 때 컴포넌트가 어떻게 맞물리는지