AI 에이전트 자체 호스팅: Hermes Agent 설치 가이드 (WSL·macOS·Linux)
Hermes Agent 설치하기
LLM에게 묻기만 하면 모든 정보가 나오므로, 상세한 설치 가이드를 나열하지는 않겠습니다. 하지만 어디서부터 시작해야 할지 모르는 경우가 있기 때문에, 설치를 위해 이것만은 최소한으로 알아야 한다는 것을 가볍게 설명하겠습니다.
(진짜 꿀팁은, LLM에게 명령어를 받아서 입력하고, 오류가 날 경우 그 코드를 복사해서 다시 묻는 게 제일 좋습니다. 그래도 안 된다면 스크린샷을 첨부하면 대개는 해결이 됩니다. 1년 전부터 혼자 LLM을 이용해서 세팅 중인데, 꽤 원활하게 운용하고 있습니다.)
어디에 설치할 것인가?
AI에 이제 막 관심을 가지기 시작한 분, 주변에서 "이런 게 있다더라" 하고 에이전트의 존재를 알게 된 분이라면 Windows를 사용할 거라 추측됩니다. 리눅스나 macOS에 설치하는 것이 훨씬 편하다고 생각합니다만, 현재 사용 가능한 기기에 맞게 시도해보는 것만으로도 가치가 있다고 생각합니다.
Hermes Agent는 Windows에 직접 설치되지 않습니다1. 그래서 윈도우 사용자라면 먼저 WSL22를 설치하고, 그 안에서 Homebrew3까지 깔아두는 것이 가장 매끄럽습니다. PowerShell을 관리자 권한으로 실행한 뒤 아래 두 명령을 순서대로 실행합니다. (Linux/macOS 사용자는 이 단계를 건너뛰고 다음 카드로 가시면 됩니다.)
# 1) PowerShell(관리자) — WSL2 + Ubuntu 설치
wsl --install
2) WSL Ubuntu 진입 후 — Homebrew 설치
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
준비가 끝났다면 Hermes Agent를 한 줄로 설치합니다. install.sh4가 OS·셸을 감지해 의존성을 알아서 잡아줍니다. Linux/macOS/WSL2 모두 동일한 명령어입니다.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash리눅스와 맥의 경우에도 OS에 맞게 LLM에게 질문을 하면 설치 명령어를 알려줄 텐데, 때때로 LLM이 이 에이전트의 존재 사실을 모를 때가 있습니다. 아마도 학습 시점과 관계될 텐데, 그때는 공식문서 주소 →를 함께 주며 "이거 검색해서 알려줘"라고 하시면 됩니다.
(1) Hermes Agent의 Windows 직접 설치 불가 — 공식 Quickstart 기준 Hermes Agent는 Linux / macOS / WSL2 / Android(Termux)에서 동작합니다. Windows는 WSL2를 통해서만 설치 가능합니다. Hermes Agent Quickstart →
(2) WSL2 (Windows Subsystem for Linux 2) — Microsoft가 공식 제공하는, 윈도우 안에서 리눅스 환경을 그대로 돌릴 수 있게 해주는 기능. 가상머신 기반이라 성능과 호환성이 좋습니다.
(3) Homebrew — macOS에서 널리 쓰이는 패키지 매니저이며, Linux와 WSL2 Ubuntu에서도 사용할 수 있습니다. 다만 WSL2에서는 기본 패키지 관리는 apt를 우선 사용하고, Homebrew는 특정 개발 도구를 설치·갱신할 때 보조적으로 쓰는 편이 자연스럽습니다.
기본 세팅하기
처음 사용하는 경우 혹시 모를 사고를 대비해서, 해당 PC를 포맷하고 하시길 권장드립니다. 기본적으로 이 에이전트는 권한 자체가 많고 다양한 파일을 읽을 수 있으므로, 민감 정보가 없는 환경에서 시험적으로 운용하고 판단 후 넣어야 합니다.
체감상 코딩 에이전트나 ChatGPT류의 딥리서치의 중간 정도로 검색을 잘한다고 생각합니다. 흩어져 있는 정보를 찾는 일이 제법 많을 수 있는데, 프롬프트 인젝션5의 위험은 항상 있다고 가정하는 것이 좋습니다.
그리고 기본적으로 이 에이전트는 24시간 돌아가야 하므로, 맥과 윈도우의 경우 절전모드 옵션을 꺼야 합니다.
설치를 마쳤다면 셸을 다시 불러오고, 모델을 골라 첫 셋업을 끝냅니다. (zsh 사용자는 ~/.zshrc로 바꿔주세요.)
source ~/.bashrc
hermes model(4) install.sh — Hermes Agent 공식 설치 스크립트. OS와 셸을 감지해 uv·Python 가상환경·hermes 명령어를 한 번에 세팅합니다.
(5) 프롬프트 인젝션(Prompt Injection) — 외부 콘텐츠(웹페이지·문서·메일)에 숨겨진 지시문이 LLM의 원래 명령을 덮어써서 의도하지 않은 동작을 시키는 공격 기법입니다. 에이전트가 자율적으로 외부 정보를 읽을수록 노출 위험이 커집니다.
게이트웨이 선택하기
편하게 세팅 가능한 곳은 디스코드와 텔레그램 정도 될 텐데, 텔레그램이 디스코드보다 3배쯤 설정하기가 쉽습니다. 디스코드의 경우 개발자 페이지에서 별도로 설정해야 하는데 생각보다 설정이 꽤 귀찮았습니다. 반면 텔레그램은 앱 내에서 필요한 대부분의 정보를 구할 수 있으므로 설치 난이도가 훨씬 낮습니다.
게이트웨이 연결은 한 줄이면 됩니다. 대화형으로 텔레그램·디스코드·슬랙·왓츠앱·시그널·이메일·Home Assistant 중에서 고를 수 있습니다.
hermes gateway setup추가로 알아두면 좋을 것들
테일스케일
Tailscale6은 WireGuard 기반의 메시 VPN 서비스입니다. 포트포워딩을 대체해서 사용 가능합니다. 만약 외부 포트를 열게 되면 전 세계 해커들의 무수한 악수요청을 받게 될 가능성이 높습니다. 개인이 활용하는 단계에서는 테일스케일을 추천합니다. 간단한 웹앱이나 대시보드를 만들어서 외부에서 접속이 필요할 때 사용합니다.
사용법도 간단합니다. 서버에서 Tailscale에 로그인하고, 내 폰·작업 PC·태블릿에서도 같은 계정으로 로그인하면 자동으로 서로 연결됩니다.
(6) Tailscale — WireGuard 기반의 메시 VPN 서비스. 별도의 포트 개방·방화벽 설정 없이 본인 소유의 기기들끼리 안전한 사설망을 만들어 어디서나 접속할 수 있게 해줍니다. Personal 플랜은 디바이스 수 무제한·사용자 6명까지 영구 무료(2026년 기준). Tailscale Pricing →
LLM에게 물어볼 때 알아두면 좋은 키워드
설치 중 막히면 아래 카테고리별 키워드를 LLM에게 던져보세요. 검색 정확도가 훨씬 올라갑니다.
| 카테고리 | 키워드 | 한 줄 설명 |
|---|---|---|
| 실행 환경 | WSL2, Ubuntu, Linux 환경, Windows 네이티브 미지원 |
Hermes는 Linux 계열에서만 동작합니다. Windows는 WSL2 안의 Ubuntu에서 실행해야 합니다. |
| 명령 인식 | Shell 환경, PATH, 환경변수 |
설치는 끝났는데 hermes 명령이 안 먹힐 때. 셸 재시작·PATH 등록·.bashrc / .zshrc 점검. |
| LLM 연결 | API Key, Provider, Model |
어떤 LLM 회사(Anthropic·OpenAI 등)의 어떤 모델을, 어떤 키로 인증해 쓸지 설정합니다. |
| 메시지 연결 | Gateway, Telegram Bot, Allowlist |
외부 메신저로 에이전트를 호출할 때. 봇 토큰 발급 + 본인만 쓰도록 화이트리스트 설정. |
| 상시 실행 | Foreground 실행, Background 실행, tmux, Windows 절전모드 |
24시간 돌리려면 백그라운드 또는 tmux 세션. PC 절전모드 끄기는 필수. |
| 네트워크 | 방화벽, 포트 개방, 로컬 실행, 원격 접속 |
외부에서 접근하려면 방화벽·포트 설정 필요. 보안 노출 점검 필수. |
위 표는 외울 필요 없습니다. 막히는 단계의 카테고리만 보고, 그 줄의 키워드를 그대로 LLM에게 던지면 충분합니다.