문제 해결

실제 운영 환경에서 발생한 이슈와 해결 방법입니다.

VPN (wire)

증상	원인	해결
연결 안 됨	릴레이 서버 다운/방화벽	curl http://RELAY:8786/peers 확인, 8786/51830 포트 개방
피어 안 보임	설정 불일치	30초 대기, relay URL이 모든 노드에서 동일한지 확인
wire status 빈 출력	wire 미설치 또는 경로	python3 wire/wire_pkg/cli.py status (MeshPOP 내)

상세: 릴레이 서버에서 python3 wire/server.py 8786 실행 중인지 확인. 클라이언트는 curl -sSL http://RELAY:8786/install.sh \| sudo bash로 설치. wg show wire0 (Linux) 또는 wg show utun9 (macOS)에서 10.99.x.x 주소 확인.

vssh

증상	원인	해결
Connection refused	데몬 미실행	각 서버에서 vssh server 실행
Connection refused	VPN 미연결	mpop 또는 wg show로 VPN 확인
Connection refused	VSSH_SECRET 불일치	config.json의 vssh_secret과 서버 환경변수 일치 확인
vssh info IndexError	호스트명 누락	vssh info g1 (호스트명 필수)
느림	P2P 실패, 릴레이 경유	mpop matrix로 연결 상태 확인, s1/gram15 등 ?인 노드 점검

VSSH_SECRET 확인: config.json의 vssh_secret과 각 서버의 echo $VSSH_SECRET 출력이 동일해야 함. systemd 서비스라면 Environment=VSSH_SECRET=... 확인.

mpop

증상	원인	해결
서버 없음	config 미설정	mpop config auto 또는 ~/.mpop/config.json 수동 편집
exec 타임아웃 (30초)	전체 서버 실행 시 지연	mpop exec -t g1 "cmd" 로 단일 서버 지정
matrix에서 ? 표시	해당 노드에서 mpop 미실행/연결 불가	해당 노드 VPN/방화벽 확인
GPU Mem - 표시	nvidia-smi 파싱 실패	d2, d1 등은 정상 표시(4321/24564MB). GB10 등은 드라이버/형식 이슈

서버 추가 후 안 나올 때: 1) config.json에 ip, user, role 추가 2) mpop config test로 연결 테스트 3) 해당 노드 VPN 연결 확인, vssh server 실행 확인.

meshdb

증상	원인	해결
결과 없음	인덱스 미생성	meshdb index ~/projects 먼저 실행
--smart 안 됨	Ollama 미실행	g1 등 Ollama 호스트에서 ollama serve 확인
DB 용량 큼 (22GB+)	인덱스된 프로젝트 많음	meshdb status로 소스 확인, 불필요 경로 제외 후 reindex

인덱싱 시간: 프로젝트 크기에 따라 수 분~수십 분. meshdb status로 documents 수 확인.

Agent

증상	원인	해결
메트릭 안 옴	vssh 연결 실패	Agent 실행 노드에서 vssh info g1 등 테스트
메트릭 안 옴	VSSH_SECRET 불일치	config와 Agent 환경의 VSSH_SECRET 일치
mpop-agent 없음	미설치	mpop setup agent g1 -x 또는 수동 설치

MCP

증상	원인	해결
도구 안 보임	MCP 시작 시 로드	Cursor/Claude 재시작
경로 오류	상대경로 사용	mcp.json에 절대 경로 사용
stack_status 호출 실패	wire/vssh 미실행	로컬에서 wire, vssh 상태 확인