설치 가이드

2026 Hermes Agent 완벽
설치·구성 가이드: 실전 사례 튜토리얼

nuzcloud 편집부 2026-05-23 9 분
한눈에 보기

Hermes Agent만 설치하고 실제 사례를 돌려보지 않으면, 정말 쓸 수 있는지 판단하기 어렵습니다. 이 글은 저위험 문서 처리 실전 사례를 먼저 정한 뒤, 2026년 Mac 기준 전체 설치·구성 경로(환경 → 설치 → 설정 → 검증 → 실행 → 트러블슈팅)를 따라갑니다. 격리된 테스트 폴더에서 샘플 텍스트를 읽고, 요약과 할 일 목록을 생성한 뒤 결과 파일을 쓰고, ~/.hermes/logs/에서 전 과정을 추적합니다. (2026-05-23 기준 확인; 모델명·요금은 각 provider 공식 문서를 따릅니다.)

실행에 성공했다고 끝이 아닙니다. 모델이 응답하는지, 파일이 경계 안에서만 읽히고 쓰이는지, 로그로 추적 가능한지, 실패 시 원인을 좁힐 수 있는지가 핵심입니다. 여기서의 사례는 별도 workflow 글이 아니라 설치와 구성이 실제로 동작함을 증명하는 수단이며, 통과한 뒤에야 실제 Hermes Agent workflow로 확장할 수 있습니다.

1먼저 돌릴 실전 사례 정의하기

첫 번째 사례는 저위험·되돌릴 수 있고·검증 가능해야 합니다. 첫날부터 프로덕션 저장소나 개인 폴더에 붙이지 마세요.

요소 본 튜토리얼 고정안 통과 기준
테스트 디렉터리 ~/hermes-lab/(언제든 rm -rf로 삭제 가능) Agent가 이 경로에서만 읽기/쓰기
입력 input/notes.md(직접 작성한 회의 메모 3~5단락) CLI가 전체 파일을 읽을 수 있음
출력 output/summary.md + output/todos.md 두 파일이 존재하고 내용이 타당함
로그 ~/.hermes/logs/ 모델 호출·도구 실행 흔적 확인
롤백 ~/hermes-lab/output/* 삭제 재실행 시 결과가 일관됨

검증 전에 한 번만 디렉터리 골격을 만듭니다:

mkdir -p ~/hermes-lab/{input,output}
# ~/hermes-lab/input/notes.md 에 테스트용 문단 몇 개 작성

2사례를 위한 설치 환경 준비

  • →하드웨어: Apple Silicon 또는 Intel Mac, RAM 16GB 이상·여유 디스크 5GB 이상 권장. uname -m, sw_vers로 칩·OS 확인.
  • →의존성: 사전에 필요한 것은 git --version뿐. Python 3.11, Node v22, ripgrep, ffmpeg는 공식 설치 스크립트가 처리합니다.
  • →네트워크: GitHub raw와 선택한 LLM API 엔드포인트(OpenRouter, Anthropic 등) 접근 가능.
  • →계정: provider API Key 최소 1개. 비밀값은 ~/.hermes/.env에만 저장하고 chmod 600.
  • →권한: 로컬 관리자 계정. 파일·터미널 도구 최초 사용 시 macOS 개인정보 보호 팝업을 필요에 따라 허용.
⚠️경계: 프로덕션 Git 저장소, 실제 개인 파일, 브라우저 저장 비밀번호, 클라우드 관리자 자격증명은 건드리지 마세요. 이 사례에서는 --yolo나 approvals.mode: off도 사용하지 않습니다.

3Hermes Agent 설치 및 버전 확인

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

이후 source ~/.zshrc를 실행하고, 공식 흐름대로 hermes setup 또는 hermes model을 진행합니다. 설치 직후 반드시 확인:

  • ✓which hermes → 보통 ~/.local/bin/hermes
  • ✓hermes doctor에 차단 항목 없음 (Key 없으면 모델 설정 안내)
  • ✓hermes update로 버전 확인. 코드는 ~/.hermes/hermes-agent/, 데이터는 ~/.hermes/

hermes doctor를 통과하기 전에는 사례 구성 단계로 넘어가지 마세요.

4사례용 모델·API Key 구성

hermes model로 provider와 기본 모델을 선택합니다(모델명·과금은 수시로 바뀌므로 공식 사이트 기준). ~/.hermes/.env에 직접 쓸 수도 있습니다:

# 예시 — 실제 provider에 맞게 수정
OPENROUTER_API_KEY=sk-or-...
chmod 600 ~/.hermes/.env

연결 검증: ~/hermes-lab에서 hermes를 실행하고 「OK로 답해줘」를 보냅니다. API 오류가 나면 hermes config check를 먼저 실행하고, 사례는 잠시 멈춥니다.

5디렉터리·권한 경계 설정

첫 검증은 테스트 디렉터리 안에서만 진행: cd ~/hermes-lab 후 hermes 실행. 이후 Messaging Gateway를 쓸 경우 ~/.hermes/.env에 MESSAGING_CWD=~/hermes-lab를 두면 민감 경로에서 시작하지 않습니다(공식 보안 문서 참고).

  • →approvals.mode: manual 유지(기본값). 위험 명령은 사람이 승인.
  • →고급 격리: ~/.hermes/config.yaml에 terminal.backend: docker (프로덕션 Gateway 권장).
  • →API Key를 ~/hermes-lab 아래 Git 추적 가능 파일에 넣지 마세요.

6본 사례 전 단계별 게이트 검증

  • ①모델 ping: 대화에 정상 응답이 옴
  • ②파일 읽기: input/notes.md 첫 단락 요약 요청
  • ③파일 쓰기: output/ping.txt에 ok 생성
  • ④로그 확인: ls ~/.hermes/logs/ — CLI 세션 기록 추적 가능

어느 단계든 실패하면 해당 계층에서 멈추고 원인을 좁힌 뒤, 전체 사례를 실행하세요.

7전체 실전 사례 실행

~/hermes-lab에서 hermes를 실행하고, 아래처럼 명확한 작업 지시를 보냅니다(복사 후 조정 가능):

이 디렉터리 안에서만 작업하세요. input/notes.md를 읽고, output/summary.md에 200자 이내 한국어 요약을, output/todos.md에 실행 가능한 할 일 최대 5개를 Markdown 목록으로 작성하세요. 이 디렉터리 밖 경로는 접근하지 말고, 파괴적 shell 명령은 실행하지 마세요.

실행 중 삭제·시스템 설정 변경 같은 위험 명령이 뜨면 CLI 승인 화면에서 거부하세요. 그것이 안전 설정이 살아 있다는 증거입니다.

8검수·트러블슈팅·롤백 확인

점검 항목 명령 / 위치
출력 파일 cat ~/hermes-lab/output/summary.md、todos.md
권한 침범 ~/, 바탕화면 등에 예기치 않은 새 파일 없는지 확인
로그 ~/.hermes/logs/(Gateway는 gateway.log 등)
비용 provider 대시보드에서 이번 실행 token 사용량
롤백 rm -rf ~/hermes-lab/output/* 후 재실행

실패 시 계층별 역추적:

  • →hermes: command not found → 설치 계층: PATH, source ~/.zshrc
  • →401 / 모델 무응답 → 모델 계층: hermes model, .env 권한
  • →파일 읽기·쓰기 실패 → 권한 계층: 작업 디렉터리, MESSAGING_CWD、macOS 개인정보 허용
  • →hermes doctor 구성 오류 → 설정 계층: hermes config migrate
  • →도구 루프·주제 이탈 → 작업 계층: 프롬프트 단순화, 출력 경로 고정

9테스트 사례에서 실제 workflow로 확장

사례가 통과한 뒤에는 검증을 건너뛰지 말고 단계적으로 권한·자동화를 넓히세요:

  • 1실제 자료 폴더는 읽기 전용, 출력은 별도 draft/에
  • 2hermes gateway setup + gateway install로 launchd 상시 실행 (plist: ~/Library/LaunchAgents/ai.hermes.gateway.plist）
  • 3더 높은 자동화가 필요할 때 Docker 백엔드, 명령 allowlist, 플랫폼 사용자 allowlist 검토

설치 전 전체 체크리스트는 Hermes Agent Mac 설치 체크리스트를 참고하세요.

10Mac mini에서 사례를 돌리면 더 수월합니다

이 글의 설치·구성·로그 검증은 macOS에서 네이티브로 가능합니다. 터미널, Homebrew, Docker, launchd를 WSL 없이 쓸 수 있습니다. Mac mini M4는 대기 전력 약 4W 수준, Apple Silicon 통합 메모리 덕분에 Hermes CLI·Gateway를 장시간 돌리기 좋은 조용한 노드입니다. Gatekeeper와 FileVault는 Agent가 상시 온라인일 때 노출면을 줄여 줍니다.

이 튜토리얼의 테스트 사례를 7×24 workflow로 올릴 계획이라면, Mac mini M4는 비용 대비 좋은 하드웨어 출발점입니다. 지금 바로 준비해, 장기 실행에 맞는 머신 위에서 설치·구성을 마무리하세요.

사례 중심 빠른 참조
  • ①사례 디렉터리·출력 기준 정의
  • ②공식 설치 + hermes doctor
  • ③모델 Key + 테스트 디렉터리 경계
  • ④단계 게이트 → 전체 사례 → 로그·롤백
  • ⑤이후 Gateway·실제 workflow 확장
nuzcloud · Mac 클라우드

Mac mini에서 Hermes Agent 실전 사례 돌리기

전용 Mac mini M4 베어메탈, 즉시 개통 · 상시 Gateway, 로컬 Agent 검증, 원격 개발에 적합. 이 튜토리얼의 각 단계를 안정적인 하드웨어 위에서 실행하세요.

지금 구매 →
Mac 클라우드 M4 베어메탈 · 즉시 개통
개통 →