설정 파일의 키는 열 개, 읽지 않는 키는 넷.

/etc/vibeshell-gateway/gateway.yaml 을 고치고 서비스를 재시작하면 됩니다. 아래 표의 기본값은 install.sh 가 써 주는 값 그대로입니다.

코드가 읽는 키

키	기본값	뜻
server.listen	:8022	SSH 프록시가 받는 주소. 앱이 붙는 포트
server.health_listen	:8080	헬스체크 HTTP
server.max_connections	100	동시 연결 상한
server.idle_timeout	300s	유휴 연결 끊기
tailscale.enabled	true	false 면 Direct 모드. listen 포트에서 그냥 받습니다
tailscale.hostname	vibeshell-gateway	tailnet 에서 보이는 이름. 주소는 hostname.tailnet.ts.net
tailscale.auth_key	""	Tailscale Admin Console 에서 만든 tskey-auth-…. 비우면 첫 실행 때 로그인 URL 을 찍습니다
tailscale.state_dir	/var/lib/vibeshell-gateway/tsnet-state	tsnet 상태. 지우면 다시 인증
targets[0].host, port	localhost, 22	뒤에 있는 SSH 서버. 지금은 첫 항목만 씁니다
logging.level, format, output	info, text, stdout	journalctl 로 봅니다

있지만 아직 읽지 않는 키

install.sh 가 만드는 파일에 들어 있지만 v0.1.0 은 무시합니다. 적어 두는 이유는 있는 줄 알고 기대하지 않게 하려는 것입니다.

키	지금
auth.pairing_timeout, token_ttl, refresh_window	페어링과 토큰 인증. 설정만 있고 코드가 읽지 않습니다
targets[].allowed_users	사용자 제한. 읽지 않습니다. 인증은 SSH 서버가 합니다
access_control	읽지 않습니다
logging.metadata_only	읽지 않습니다. 로그는 원래 접속 메타데이터만 남깁니다

두 모드

	주소	누가 닿나	쓰는 때
Tailscale	hostname.tailnet.ts.net:8022 또는 100.x.x.x:8022	같은 tailnet 의 기기만	기본. 집이나 회사 사설망 서버
Direct	서버IP:8022	그 포트에 닿는 누구나	이미 닿는 내부망. 인터넷에 열지 않습니다

헬스체크

$ curl http://localhost:8080/health
{
  "status": "ok",
  "version": "v0.1.0",
  "uptime": "3h12m",
  "active_connections": 1,
  "tailscale_enabled": true,
  "tailscale_hostname": "vibeshell-gateway"
}

VibeShell 앱은 게이트웨이를 등록할 때 SSH 포트를 HTTP 포트로 바꿔 이 주소를 부릅니다. tailnet 안이면 hostname.tailnet.ts.net:8080 으로도 됩니다.

systemd

	명령
시작	sudo systemctl start vibeshell-gateway
부팅 시 자동 시작	sudo systemctl enable vibeshell-gateway
상태	sudo systemctl status vibeshell-gateway
재시작 (설정 바꾼 뒤)	sudo systemctl restart vibeshell-gateway
로그	sudo journalctl -u vibeshell-gateway -f
중지	sudo systemctl stop vibeshell-gateway

안 될 때 보는 여섯 가지

증상	원인	확인
시작이 안 됨	설정 파일이 없거나 포트가 이미 쓰이는 중	ls /etc/vibeshell-gateway/gateway.yaml, lsof -i :8022. 쓰는 프로세스를 끄거나 server.listen 을 바꿉니다
Tailscale 인증에서 멈춤	auth_key 가 비어 있고 로그에 login.tailscale.com URL 만 찍힘	그 URL 을 브라우저에서 열어 기기를 승인합니다. 꼬였으면 state_dir 을 지우고 재시작
앱에서 Connection refused	뒤에 있는 SSH 서버가 꺼져 있음	서버에서 ssh user@localhost 가 되는지 먼저. Ubuntu 는 systemctl status ssh
tailnet 에 안 보임	방화벽이 WireGuard 를 막음	UDP 41641 과 HTTPS 443 아웃바운드가 열려 있어야 합니다
비밀번호나 키 인증 실패	게이트웨이가 아니라 SSH 서버 문제	ssh user@localhost 로 재현. ~/.ssh 700, 키 600, authorized_keys 644
failed to parse config	YAML 문법	탭과 스페이스 섞임, 콜론 뒤 공백 누락, 따옴표 누락. python3 -c "import yaml; yaml.safe_load(open('/etc/vibeshell-gateway/gateway.yaml'))"

VibeShell Gateway 고객지원 VibeShell Hook