Wave Terminal에서 Hostinger VPS의 Hermes Agent에 안전하게 접속하기

Hostinger 원클릭 배포로 설치한 Hermes Agent는 일반적으로 Docker 컨테이너 안에서 실행됩니다. Wave Terminal은 그 컨테이너가 아니라 먼저 VPS 호스트의 SSH에 접속합니다. 따라서 Wave에서 hermes를 새로 설치하면 원클릭으로 설치된 Hermes와 별개의 인스턴스가 생깁니다.

이 가이드는 다음 원칙으로 진행합니다.

1. Tailscale은 컨테이너가 아닌 VPS 호스트에 설치합니다.
2. Wave는 Tailscale 사설 IP로 VPS 호스트에 SSH 접속합니다.
3. Hermes를 실행할 때는 실제 실행 중인 컨테이너를 찾아 docker exec로 들어갑니다.

💡 Hostinger 화면의 프로젝트명·컨테이너명·포트는 계정과 배포 시점마다 달라질 수 있습니다. 이 문서의 명령은 이름을 고정하지 않고, 현재 VPS에서 실행 중인 컨테이너를 확인하는 방식입니다.

⚠️ 이 가이드를 따라 진행하는 VPS에서는 host에 hermes를 다시 설치하지 마세요. 원클릭 설치본과 host 설치본은 설정·세션·연동 정보가 공유되지 않습니다.

0단계. 현재 배포 상태 확인

Hostinger hPanel의 Docker Manager에서 Hermes Agent 배포가 Running인지 먼저 확인합니다. 이 단계에서 열어야 하는 것은 각 프로젝트 행의 열기·터미널 링크가 아니라, 화면 오른쪽 위에 있는 터미널 버튼입니다. 이 버튼은 Docker 컨테이너가 아닌 VPS 호스트 터미널을 엽니다.

VPS host 터미널 또는 기존 SSH 세션에서 아래 명령을 실행합니다.

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

출력에 hermes가 포함된 이미지와 Up ... 상태의 행이 있으면 원클릭 배포가 실행 중인 것입니다. 컨테이너명은 예를 들어 hermes-agent-xxxx-hermes-agent-1처럼 보일 수 있지만, 예시 이름을 복사하지 마세요. 다음 단계에서 내 VPS의 이름을 직접 선택합니다.

1단계. VPS 호스트에 Tailscale 설치

Tailscale은 Docker 컨테이너 안이 아니라 VPS 호스트에 설치합니다. hPanel 터미널은 보통 root로 열립니다. 별도 계정으로 접속했다면 앞에 sudo를 붙이세요.

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up

두 번째 명령이 보여 주는 로그인 URL을 브라우저에서 열어, Wave를 사용할 내 컴퓨터와 같은 Tailscale 계정으로 승인합니다.

승인 후 VPS의 사설 IP를 확인합니다.

tailscale ip -4
tailscale status

tailscale ip -4의 100.x.x.x 주소를 메모합니다. 이후 Wave는 이 주소로 접속합니다. 공인 IP가 아닙니다. tailscale status에는 같은 Tailnet의 여러 기기가 함께 나오므로, 현재 VPS의 호스트명 행과 tailscale ip -4 결과가 같은지 대조하세요.

⚠️ 컨테이너 안에서 tailscaled --tun=userspace-networking을 실행할 필요가 없습니다. 이 구성이 불필요하게 복잡해지고, Wave가 접속해야 할 SSH 호스트와도 분리됩니다.

2단계. 내 컴퓨터에도 Tailscale 연결

Wave를 실행하는 Mac 또는 Windows 컴퓨터에도 Tailscale 앱을 설치하고, 1단계에서 쓴 것과 같은 계정으로 로그인합니다.

내 컴퓨터의 일반 터미널에서 다음 테스트가 먼저 성공해야 합니다.

ssh [email protected]

여기서 100.x.x.x는 1단계에서 확인한 VPS의 Tailscale IP로 바꿉니다. 기본 SSH 사용자가 root가 아니라면 root도 본인 사용자명으로 바꿉니다.

💡 이 명령이 먼저 성공하면 Wave도 같은 SSH 경로를 이용할 수 있습니다. 여기서 실패한 상태에서 Wave 설정부터 고치면 원인을 구분하기 어렵습니다.

3단계. SSH 키 만들기와 VPS 공개키 등록

내 컴퓨터의 Wave 터미널 또는 일반 터미널에서 Ed25519 키를 만듭니다.

ssh-keygen -t ed25519 -f ~/.ssh/hostinger_vps

~/.ssh/hostinger_vps.pub 파일의 한 줄 전체를 복사합니다. 그다음 VPS 호스트 터미널에서 공개키를 등록합니다.

mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys

열린 파일의 새 줄에 공개키를 붙여 넣고 저장한 뒤 권한을 맞춥니다.

chmod 600 ~/.ssh/authorized_keys

이제 내 컴퓨터에서 키를 명시해 다시 접속합니다.

ssh -i ~/.ssh/hostinger_vps [email protected]

4단계. Wave 연결 프로필 저장

Wave의 연결 드롭다운에서 Edit Connections를 열고 아래 연결을 추가합니다. ssh:hostname, ssh:identityfile, ssh:user만 본인 환경에 맞게 바꿉니다.

"HostingerVPS": {
  "conn:wshenabled": true,
  "ssh:addkeystoagent": true,
  "ssh:hostname": "100.x.x.x",
  "ssh:identitiesonly": true,
  "ssh:identityfile": ["~/.ssh/hostinger_vps"],
  "ssh:user": "root"
}

저장 후 연결 드롭다운에서 HostingerVPS를 선택합니다. 접속되면 VPS 호스트의 프롬프트가 보입니다.

⚠️ no route for conn:... 오류가 나면 Wave를 완전히 종료한 뒤 다시 열고, ssh:hostname에 공란이 아닌 실제 100.x.x.x 주소가 들어갔는지 확인하세요. 먼저 일반 터미널의 ssh [email protected]가 성공하는지도 확인합니다.

5단계. 현재 Hermes 컨테이너 찾기

Wave로 VPS에 접속한 뒤, 아래 명령으로 실행 중인 컨테이너를 목록으로 봅니다.

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

이제 각 후보가 실제 Hermes 컨테이너인지 확인합니다. 아래에서 컨테이너명 자리만 방금 목록에서 복사한 값으로 바꾸세요.

docker exec 컨테이너명 sh -lc 'command -v hermes && hermes --version'

/opt/hermes/bin/hermes 같은 경로와 Hermes 버전이 출력되는 컨테이너가 정답입니다. 그 이름을 현재 Wave 세션에서 변수로 저장합니다.

export HERMES_CONTAINER='컨테이너명'
printf '%s\n' "$HERMES_CONTAINER"

💡 HERMES_CONTAINER 변수는 현재 터미널 탭에만 남습니다. 새 Wave 탭을 열었다면 5단계를 다시 실행해 현재 이름을 확인하세요. 이것이 배포명 변경이나 컨테이너 재생성에도 안전한 이유입니다.

이름을 자동으로 후보 목록에 표시하기

실행 중인 모든 컨테이너 중 hermes 명령이 있는 컨테이너만 보고 싶다면 아래 명령을 사용합니다.

for id in $(docker ps -q); do
  if docker exec "$id" sh -lc 'command -v hermes >/dev/null 2>&1'; then
    docker inspect --format '{{.Name}}' "$id" | sed 's#^/##'
  fi
done

한 줄만 나오면 그대로 변수에 넣어도 됩니다.

export HERMES_CONTAINER="$(for id in $(docker ps -q); do
  if docker exec "$id" sh -lc 'command -v hermes >/dev/null 2>&1'; then
    docker inspect --format '{{.Name}}' "$id" | sed 's#^/##'
  fi
done)"
printf '%s\n' "$HERMES_CONTAINER"

두 줄 이상 나오면 자동 선택하지 말고, 각 이름에 대해 앞의 버전 확인 명령을 실행해 원클릭 Hermes Agent 컨테이너를 선택하세요.

6단계. Wave에서 기존 Hermes를 사용하기

컨테이너 내부 셸로 들어가려면 다음을 실행합니다.

docker exec -it "$HERMES_CONTAINER" sh

컨테이너 안에서 다음을 확인합니다.

printf 'HOME=%s\n' "$HOME"
readlink -f "$(command -v hermes)"
hermes --version

Hostinger 원클릭 Hermes Agent 기준으로 Hermes 프로그램은 보통 /opt/hermes/bin/hermes, 설정·세션·연동 데이터는 보통 컨테이너의 /opt/data에 있습니다. 이 경로와 이름은 배포 버전에 따라 달라질 수 있으므로, 위 명령의 실제 출력을 기준으로 삼으세요.

컨테이너 셸에 들어가지 않고 Hermes를 바로 실행할 수도 있습니다.

docker exec -it "$HERMES_CONTAINER" hermes

설정·모델·Slack·Telegram 상태도 이 컨테이너 안에서 확인하거나 변경해야 기존 원클릭 설치본에 반영됩니다.

하지 말아야 할 것

VPS host에서 hermes를 새로 설치하지 않기

다음처럼 host에 별도 Hermes를 설치하면 Docker 컨테이너의 Hermes와 별개입니다.

# 실행하지 마세요: 기존 컨테이너와 다른 Hermes가 생깁니다.
curl -fsSL https://get.hermes-agent.com/install.sh | sh

host의 hermes와 컨테이너의 /opt/hermes/bin/hermes는 세션, 모델, Slack, Telegram, 설정 파일을 공유하지 않습니다. 두 곳에서 각각 실행하면 서로 다른 세션과 다른 연동 상태가 보이는 것이 정상입니다.

/usr/local/bin/hermes와 /opt/hermes/bin/hermes만 보고 중복 설치로 판단하지 않기

컨테이너 안에서는 /usr/local/bin/hermes가 /opt/hermes/bin/hermes를 가리키는 심볼릭 링크일 수 있습니다. 아래 명령으로 실제 파일을 확인합니다.

docker exec "$HERMES_CONTAINER" sh -lc 'readlink -f "$(command -v hermes)"'

같은 /opt/hermes/bin/hermes가 출력되면 컨테이너 안의 중복 설치가 아닙니다.

빠른 점검표

아래 네 가지가 모두 맞으면 Wave 원격 운영 연결은 정상입니다.

# 1. VPS 호스트: Tailscale이 실행 중이고 100.x 주소가 나온다.
tailscale ip -4
tailscale status

# 2. VPS 호스트: Hermes 컨테이너가 실행 중이다.
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

# 3. 현재 선택한 컨테이너: Hermes가 실제로 있다.
docker exec "$HERMES_CONTAINER" sh -lc 'command -v hermes && hermes --version'

# 4. Wave가 아닌 일반 터미널에서도 같은 경로가 된다.
# 내 컴퓨터에서 실행
ssh -i ~/.ssh/hostinger_vps [email protected]

자주 만나는 문제

Wave에서는 접속되는데 hermes: command not found가 나와요.

정상일 수 있습니다. Wave가 접속한 곳은 VPS host이고, Hermes는 Docker 컨테이너 안에 있기 때문입니다. 5단계에서 컨테이너를 찾고 docker exec로 실행하세요.

Wave와 VPS 터미널에서 Slack·Telegram·모델 설정이 서로 달라요.

두 Hermes 인스턴스를 보고 있을 가능성이 큽니다. host에서 새 Hermes를 설치했다면 사용을 멈추고, 원클릭 Hermes 컨테이너만 사용하세요. 컨테이너 안의 /opt/data가 기존 설정이 있는 위치인지 확인합니다.

컨테이너명이 예전과 달라졌어요.

배포 재생성이나 Hostinger 프로젝트명 변경 때 자연스러운 현상입니다. 고정 이름을 수정하지 말고 5단계의 docker ps와 자동 후보 명령으로 다시 찾으세요.

100.x.x.x SSH가 안 돼요.

VPS와 내 컴퓨터가 같은 Tailnet에 로그인됐는지 확인합니다. VPS에서 tailscale status, 내 컴퓨터의 Tailscale 앱에서 두 장치가 모두 Online인지 봅니다. 먼저 일반 터미널에서 SSH를 성공시킨 뒤 Wave 연결을 다시 저장하세요.

이제 Wave는 안전한 Tailscale 경로로 VPS에 들어오고, Hermes 작업은 언제나 실제 원클릭 컨테이너에서 수행합니다. 이 경계를 지키면 WebUI, Wave, SSH 터미널 어디에서 접속하더라도 같은 Hermes 설정과 세션을 사용하게 됩니다.