맥에서 도커로 띄운 헤르메스, 그 파일을 Wave로 다루는 두 가지 방법

맥에서 헤르메스를 도커 컨테이너로 띄우면 셸은 잘 붙는데, Wave 터미널 오른쪽 파일 브라우저에는 맥 파일만 보이고 헤르메스 파일(SOUL.md, config.yaml, skills/, memories/ 등)은 보이지 않는 경우가 있습니다. 숨김 파일 문제가 아니라, 컨테이너 안의 파일을 호스트(맥)에서 들여다보는 통로가 없어서 그렇습니다.

도커 컨테이너는 맥 안에 있지만 사실상 작은 독립 서버 한 대입니다. 그 안의 파일을 맥에서 다루려면 통로를 하나 내줘야 해요. 통로를 내는 길이 두 가지입니다.

💡 어떤 방법을 고를까요?

• 그냥 편하게 파일을 보고 싶다 → 방법 1(볼륨 마운트). 대부분 이걸 쓰시면 됩니다. 헤르메스 공식 도커 사용법이 원래 이 방식이에요.
• 컨테이너를 외부와 완전히 격리하고 싶다(파일을 맥에 노출하지 않음) → 방법 2(컨테이너 SSH 접속). 이전에 안내해 드린 Wave 터미널에서 VPS 원격 접속과 똑같은 패턴입니다. 도커 컨테이너도 하나의 서버라고 생각하시면 돼요.

⚠️ 아래 명령의 경로·포트·키는 예시입니다. 본인 환경에 맞게 바꿔 넣으세요. SSH 개인키는 누구에게도 공유하지 마세요.

📌 이 가이드는 헤르메스 공식 도커 이미지(nousresearch/hermes-agent)를 기준으로 합니다. 공식 이미지는 컨테이너 안 /opt/data 한 곳에 모든 헤르메스 데이터(설정·키·세션·스킬·기억)를 모아 둡니다. 그래서 통로를 낼 지점도 /opt/data 하나로 단순합니다.

왜 안 보였을까 — 컨테이너의 데이터 위치

헤르메스를 도커로 띄우면, 헤르메스 데이터는 컨테이너 안 /opt/data에 쌓입니다. 맥의 ~/.hermes가 아니라요. Wave의 파일 브라우저는 기본적으로 맥(호스트) 파일 시스템을 보기 때문에, 컨테이너 안 /opt/data는 눈에 들어오지 않습니다. 통로를 내주면 그때부터 보입니다.

방법 1. 볼륨 마운트 — 컨테이너 데이터를 맥 폴더에 그대로 두기 (권장·쉬움)

컨테이너의 /opt/data를 맥의 실제 폴더에 연결해 두는 방식입니다. 연결해 두면 헤르메스 데이터가 물리적으로 맥에 저장되고, 컨테이너와 맥이 같은 파일을 바라봅니다. 그러면 Wave는 평소처럼 맥 로컬 폴더를 열기만 하면 헤르메스 파일이 다 보입니다.

1-1. 맥에 데이터 폴더를 정하고 그 폴더로 컨테이너를 띄웁니다

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

-v ~/.hermes:/opt/data가 핵심입니다. "맥의 ~/.hermes 폴더를 컨테이너의 /opt/data로 연결하라"는 뜻이에요. 처음 띄우면 설정 마법사가 떠서 API 키 등을 묻고, 그 결과가 맥의 ~/.hermes에 바로 쓰입니다.

💡 설정을 이미 마쳤다면 setup 없이 평소처럼 띄우시면 됩니다. 게이트웨이로 상시 운영할 때는 이렇게요.

docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

1-2. 맥에 파일이 생겼는지 확인합니다

컨테이너가 한 번 뜨고 나면, 맥의 ~/.hermes 안에 헤르메스 데이터가 그대로 들어차 있습니다.

ls ~/.hermes
# config.yaml  SOUL.md  skills  memories  sessions  logs  home ...

config.yaml, SOUL.md, skills/, memories/가 보이면 성공입니다. 이게 곧 컨테이너 안 /opt/data와 같은 파일입니다.

1-3. Wave에서 맥 로컬 폴더로 열기

Wave 터미널에서 파일 브라우저(또는 wsh view ~/.hermes)로 **맥의 ~/.hermes**를 엽니다. 컨테이너를 거칠 필요 없이, 맥 로컬 파일을 여는 것만으로 헤르메스 파일이 다 보입니다. 여기서 SOUL.md를 고치면 컨테이너 안 헤르메스에도 즉시 반영됩니다(같은 파일이니까요).

⚠️ 이미 마운트 없이 컨테이너를 띄워서 데이터가 컨테이너 안에만 쌓인 상태라면, 그 데이터는 컨테이너를 지우면 사라집니다. 새로 -v ~/.hermes:/opt/data로 띄워 처음부터 맥에 쌓이게 하거나, 방법 2로 컨테이너 안 데이터를 직접 꺼내 보세요.

방법 2. 컨테이너에 SSH로 접속 — 완전 격리한 채 원격으로 다루기

데이터를 맥에 내놓지 않고 컨테이너 안에 그대로 둔 채, 컨테이너를 작은 서버처럼 취급해 SSH로 접속하는 방식입니다. Wave는 SSH로 연결되면 그 원격(컨테이너) 파일을 브라우저로 보여줍니다. VPS에 접속하던 것과 똑같아요.

공식 이미지에는 SSH 클라이언트만 있고 SSH **서버(sshd)**는 없습니다. 그래서 공식 이미지에 sshd만 얹은 나만의 이미지를 한 번 만들어 둡니다.

2-1. 맥에서 SSH 키 만들기 (이미 있으면 건너뛰기)

ssh-keygen -t ed25519 -f ~/.ssh/id_hermes_docker -C "hermes-docker"

~/.ssh/id_hermes_docker(개인키)와 ~/.ssh/id_hermes_docker.pub(공개키)가 생깁니다. 공개키만 컨테이너에 넣을 거예요.

2-2. sshd를 얹은 파생 이미지 만들기

작업 폴더를 하나 만들고, 그 안에 공개키를 authorized_keys로 복사한 뒤 Dockerfile을 둡니다.

mkdir -p ~/hermes-docker-ssh
cp ~/.ssh/id_hermes_docker.pub ~/hermes-docker-ssh/authorized_keys

~/hermes-docker-ssh/Dockerfile:

FROM nousresearch/hermes-agent:latest

USER root
RUN apt-get update \
  && apt-get install -y --no-install-recommends openssh-server \
  && rm -rf /var/lib/apt/lists/* \
  && mkdir -p /var/run/sshd \
  && ssh-keygen -A \
  && sed -i 's/#\?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config

# 헤르메스 사용자(홈=/opt/data)로 공개키 로그인 허용
COPY authorized_keys /opt/data/.ssh/authorized_keys
RUN chown -R 10000:10000 /opt/data/.ssh \
  && chmod 700 /opt/data/.ssh \
  && chmod 600 /opt/data/.ssh/authorized_keys

💡 헤르메스 컨테이너의 로그인 사용자는 hermes(UID 10000)이고, 그 홈이 /opt/data입니다. 그래서 공개키를 /opt/data/.ssh/authorized_keys에 둡니다. 비밀번호 로그인은 끄고 키 로그인만 허용합니다.

이미지를 빌드합니다.

docker build -t hermes-ssh ~/hermes-docker-ssh

2-3. 격리 컨테이너 띄우고 sshd 켜기

마운트(-v) 없이 띄웁니다. 데이터는 컨테이너 안에만 남습니다. SSH용으로 맥의 2222 포트를 컨테이너 22에 연결합니다.

docker run -d --name hermes-iso -p 2222:22 \
  hermes-ssh gateway run
docker exec -d -u 0 hermes-iso /usr/sbin/sshd

첫 줄은 컨테이너를 띄우고(헤르메스 게이트웨이가 돌며 컨테이너가 유지됨), 둘째 줄은 그 안에서 SSH 서버를 켭니다.

2-4. 맥에서 접속해 보기

ssh -i ~/.ssh/id_hermes_docker -p 2222 hermes@localhost

접속하면 홈이 /opt/data라, 들어가자마자 ls만 쳐도 SOUL.md·config.yaml·skills·memories가 보입니다. 컨테이너 안 파일을 맥에서 직접 읽고 쓰는 거예요.

2-5. Wave에 영구 연결로 등록 (핵심)

Wave 터미널은 ~/.ssh/config에 등록한 SSH 별칭(alias)을 연결 목록에 자동으로 띄워 클릭 한 번으로 접속하게 해 줍니다. 파일 브라우저도 그 SSH 연결을 통해 원격(컨테이너) 파일을 보여줍니다.

맥의 ~/.ssh/config에 다음을 추가합니다.

Host hermes-docker
    HostName localhost
    Port 2222
    User hermes
    IdentityFile ~/.ssh/id_hermes_docker

이제 Wave의 연결 드롭다운(Connect to (username@host)...)에 **hermes-docker**가 뜹니다. 그걸 고르면 컨테이너 셸이 열리고, 오른쪽 파일 브라우저가 컨테이너 안 /opt/data를 보여줍니다. SOUL.md를 열어 고치고 저장하면 컨테이너 안 파일이 바로 바뀝니다.

💡 터미널에서 직접 ssh hermes-docker만 쳐도 접속됩니다(별칭 등록 덕분). Wave 목록 클릭과 같은 동작이에요.

두 방법 한눈에 비교

대부분은 방법 1이면 충분합니다. 보안·격리가 중요한 운영 환경이라면 방법 2를 쓰세요.

자주 만나는 문제

• 방법 1인데도 ~/.hermes가 비어 있어요. docker run에 -v ~/.hermes:/opt/data를 빠뜨렸는지 확인하세요. 마운트 경로 한 줄이 핵심입니다.
• 방법 2에서 Connection refused가 떠요. 컨테이너 안 sshd가 안 켜졌을 수 있어요. docker exec -d -u 0 hermes-iso /usr/sbin/sshd를 다시 실행하고, docker ps에 0.0.0.0:2222->22/tcp가 보이는지 확인하세요.
• 방법 2에서 Permission denied (publickey). authorized_keys에 넣은 공개키와 접속에 쓰는 개인키(-i ~/.ssh/id_hermes_docker)가 짝이 맞는지 확인하세요. 키를 바꿨다면 이미지를 다시 빌드해야 합니다.
• 2222 포트가 이미 쓰여요. -p 2223:22처럼 다른 포트로 바꾸고, ~/.ssh/config의 Port도 같이 바꾸세요.
• 컨테이너를 지웠더니 데이터가 사라졌어요(방법 2). 방법 2는 데이터가 컨테이너 안에만 있어 컨테이너 삭제 시 사라집니다. 데이터를 오래 보존하려면 방법 1처럼 볼륨을 마운트하거나, 별도 도커 볼륨을 /opt/data에 붙이세요.

마무리

도커 컨테이너 안의 헤르메스 파일이 Wave에 안 보이는 건 고장이 아니라, 통로를 아직 안 낸 것뿐입니다. 편하게 보려면 볼륨 마운트(방법 1), 격리한 채 원격으로 다루려면 컨테이너 SSH 접속(방법 2). 컨테이너를 작은 서버 한 대로 바라보면, 앞서 배운 VPS 접속 경험이 그대로 이어집니다.