헤르메스 에이션트를 윈도우 도커에 설치하느법 알려줘

핵심 요약

윈도우 Docker에서 Hermes Agent를 설치하려면 Windows 컨테이너가 아니라 Linux 컨테이너를 사용해야 합니다. 가장 일반적인 구성은 Windows 10 또는 11, Docker Desktop, WSL2 backend, Ubuntu 기반 Docker 이미지입니다.

중요한 점은 세 가지입니다.

1. Hermes는 Ubuntu 같은 Linux 컨테이너 안에 설치합니다.
2. Hermes 설정과 세션이 사라지지 않도록 /root/.hermes를 Docker volume에 연결합니다.
3. OpenRouter, OpenAI, Anthropic 같은 API 키는 Dockerfile에 넣지 말고 .env 파일이나 Docker 환경변수로 전달합니다.

설치 흐름

먼저 Windows에 Docker Desktop을 설치하고, 설정에서 WSL2 based engine을 활성화합니다. Docker가 정상 동작하는지 확인한 뒤, Hermes Docker용 폴더를 하나 만듭니다.

그 폴더 안에는 보통 Dockerfile과 .env 파일을 둡니다. Dockerfile은 Ubuntu 24.04 이미지를 기반으로 curl, git, Python, build-essential 같은 기본 도구를 설치한 다음 Hermes 설치 스크립트를 실행하도록 구성하면 됩니다. 컨테이너의 작업 폴더는 /workspace로 두는 것이 편합니다.

.env 파일에는 OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY 중 사용할 키를 넣습니다. 처음에는 OpenRouter 키 하나만 있어도 충분합니다. 단, .env 파일은 절대 GitHub에 올리면 안 됩니다.

실행 방식

이미지를 빌드한 뒤 hermes-home 같은 Docker volume을 만들어 /root/.hermes에 연결합니다. 이렇게 해야 컨테이너를 삭제해도 Hermes 설정, 세션, 스킬, 메모리 등이 유지됩니다.

컨테이너 실행 시에는 다음 구성이 핵심입니다.

• .env 파일을 환경변수로 전달
• hermes-home volume을 /root/.hermes에 연결
• 현재 작업 폴더나 Windows 프로젝트 폴더를 /workspace에 mount
• 필요하면 -w 옵션으로 작업 디렉터리를 지정

예를 들어 Windows의 C:\Users\kim\Desktop\my-project 폴더를 Hermes가 수정하게 하려면, Docker에서는 그 폴더를 /workspace/my-project 같은 경로로 mount해서 사용합니다. 컨테이너 안의 Hermes는 Windows 경로를 직접 보는 것이 아니라 /workspace/my-project 경로로 접근합니다.

설치 후 확인할 것

컨테이너가 실행되면 Hermes 설정을 진행하고, Hermes 명령이 정상적으로 잡히는지 확인해야 합니다. 확인 순서는 다음과 같습니다.

1. Hermes 명령이 실행되는지 확인합니다.
2. Hermes 설정을 완료합니다.
3. 사용할 모델을 선택합니다.
4. doctor 또는 진단 명령으로 설정 오류를 확인합니다.
5. 짧은 질문을 보내 실제 모델 응답이 오는지 확인합니다.
6. /workspace 아래에 mount한 Windows 프로젝트 파일이 보이는지 확인합니다.
7. 테스트용 파일을 읽고 수정할 수 있는지 확인합니다.

여기까지 성공하면 Windows Docker 안에서 Hermes Agent 설치는 완료된 것으로 볼 수 있습니다.

주의할 점

API 키를 Dockerfile에 직접 넣으면 안 됩니다. Docker 이미지 안에 키가 남을 수 있어 유출 위험이 있습니다. 반드시 .env 파일이나 Docker secret, 환경변수 방식으로 전달하는 것이 좋습니다.

/root/.hermes volume도 빼먹으면 안 됩니다. 이 연결 없이 컨테이너를 실행하면 컨테이너 삭제 시 Hermes 설정과 세션이 사라질 수 있습니다.

Windows 경로를 mount할 때는 C:\Users\kim\Desktop\project 같은 백슬래시 경로보다 C:/Users/kim/Desktop/project처럼 슬래시를 쓰는 편이 Docker에서 덜 헷갈립니다.

또한 컨테이너가 기본적으로 root 사용자로 실행되기 때문에 파일 권한 문제가 생길 수 있습니다. 개인 PC의 Windows mount 폴더에서는 보통 큰 문제는 적지만, 팀 프로젝트나 서버 배포까지 고려한다면 나중에 non-root 사용자 구성을 추가하는 것이 좋습니다.

브라우저 자동화 기능까지 Docker에서 쓰려면 Chromium, Playwright, 포트, 디스플레이 관련 설정이 추가로 필요할 수 있습니다. 처음에는 Hermes CLI 실행, 모델 응답, 파일 읽기와 쓰기, 프로젝트 폴더 mount까지만 먼저 확인하는 것을 권장합니다.

추천 시작 범위

처음부터 완전한 운영 환경을 만들기보다 다음 순서로 시작하는 것이 안전합니다.

1. Docker Desktop과 WSL2 backend를 준비합니다.
2. Ubuntu 기반 Hermes Docker 이미지를 만듭니다.
3. .env 파일로 모델 API 키를 전달합니다.
4. hermes-home volume을 /root/.hermes에 연결합니다.
5. 작업할 Windows 프로젝트 폴더를 /workspace에 mount합니다.
6. Hermes 설정과 모델 설정을 완료합니다.
7. 짧은 질문으로 응답이 오는지 확인합니다.
8. 실제 프로젝트 파일을 읽고 수정할 수 있는지 테스트합니다.

이 구성이 안정적으로 동작하면 그다음에 Docker Compose, Gateway, cron, MCP, 브라우저 자동화, 장기 실행 컨테이너 같은 고급 구성을 추가하면 됩니다.