Hermes Agent는 터미널에서 대화하고, 파일·브라우저·일정 작업 같은 도구를 연결해 쓰는 AI 에이전트다. 2026년 8월 7일 공식 설치 문서는 macOS, Windows, Linux/WSL2를 1차 지원 경로로 안내한다. 개인의 유휴 컴퓨터에 두든 VPS에 두든, 먼저 운영체제별 설치 명령으로 명령줄 도구를 준비하고 모델 제공자를 선택하는 순서는 같다.
이 글은 처음 설치하는 독자가 한 번의 대화를 성공시키는 데 초점을 둔다. macOS와 Windows는 데스크톱 설치 프로그램도 제공하고, 세 운영체제 모두 명령줄 전용 설치를 할 수 있다. 메시지 앱 연동이나 상시 실행은 기본 대화가 작동한 뒤에 붙이는 편이 설정 오류를 줄인다.
사전 조건: 설치할 컴퓨터와 운영체제별 준비물
VPS는 계속 켜 둘 서버를 빌리는 방식이고, 유휴 컴퓨터는 집이나 사무실에 이미 있는 PC·Mac을 쓰는 방식이다. 둘 중 무엇을 골라도 Hermes의 계정, 설정, 세션 데이터는 설치한 사용자별 ~/.hermes/에 저장된다. 여러 사람이 함께 쓰는 Linux 서버라면 시스템 전체에 한 번 설치하기보다 전용 일반 사용자 계정으로 설치하면 사용자별 설정을 분리할 수 있다.
| 운영체제 | 공식 1차 지원 범위 | 처음 고를 설치 경로 |
|---|---|---|
| macOS | Apple Silicon | Hermes Desktop 설치 프로그램 또는 install.sh |
| Windows | Windows 10/11, x86_64·aarch64 | Hermes Desktop 설치 프로그램 또는 PowerShell install.ps1 |
| Linux·WSL2 | x86_64·aarch64 | install.sh |
명령줄 설치에서는 macOS에 Git이 필요하고 Linux에는 Git, curl, xz-utils가 필요하다. Hermes Desktop까지 설치할 때는 g++가 추가로 필요하며 Debian·Ubuntu에서는 build-essential으로 준비할 수 있다. 설치 프로그램이 Python 3.11, Node.js 22, ripgrep, ffmpeg와 가상 환경을 처리하므로 이 항목들을 따로 설치할 필요는 없다. Debian·Ubuntu 계열 VPS라면 다음 명령으로 Linux 사전 조건을 채운다.
sudo apt install git curl xz-utilsmacOS·Windows에서 데스크톱 앱을 함께 쓰려면 Hermes Desktop 설치 프로그램을 내려받아 실행하는 경로가 공식 권장 경로다. 화면 없이 SSH로 접속하는 VPS나 명령줄만 쓰려는 경우에는 아래 OS별 명령을 고른다.
실행 명령: macOS·Windows·Linux에 Hermes Agent 설치하기
macOS: Terminal에서 설치하고 Portal로 모델 연결
Terminal을 열어 다음 명령을 그대로 실행한다. 설치가 끝나면 Zsh 설정을 다시 읽고, Nous Portal 구독을 쓰는 경우 hermes setup --portal로 로그인·모델·Tool Gateway를 한 번에 설정한다. 다른 제공자를 고를 때는 다음 절의 hermes model 명령을 쓴다.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc
hermes setup --portal
Windows: PowerShell 명령은 PowerShell에서 실행
Windows에서는 PowerShell을 열고 아래 한 줄을 실행한다. 설치가 끝나면 hermes model이 제공자와 모델 선택 과정을 시작한다. 설치 후 바로 대화를 시작하려면 hermes를 실행한다.
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
hermes model
hermes
PowerShell은 명령 앞에 PS C:\Users\utomo>처럼 표시된다. CMD나 Git Bash가 아니라 PowerShell에서 install.ps1 명령을 실행해야 한다.
Linux·WSL2: Bash에서 설치하고 셸을 다시 읽기
Ubuntu·Debian을 포함한 Linux와 WSL2에서는 아래 명령을 실행한다. Bash가 아닌 Zsh를 기본 셸로 쓰는 Linux라면 두 번째 줄을 source ~/.zshrc로 바꾼다.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes설치 프로그램은 일반 사용자 설치에서 코드 파일을 ~/.hermes/hermes-agent/에, 실행 명령을 ~/.local/bin/hermes에 둔다. 서버 운영용 전용 사용자처럼 sudo가 없는 계정도 설치할 수 있다. 브라우저 자동화가 필요하면 관리자가 먼저 Chromium이 요구하는 시스템 라이브러리를 설치한다.
sudo npx playwright install-deps chromium브라우저 자동화가 필요 없는 헤드리스 VPS라면 설치 스크립트에 --skip-browser를 붙인다.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser실행 결과와 초기 사용: 명령 하나가 정상 대화를 만들기까지
세 운영체제에서 설치 직후 해야 할 일은 제공자와 모델을 정하는 것이다. hermes model은 대화식 선택 화면을 열고, hermes setup은 제공자·도구·옵션을 한 번에 설정하는 마법사를 연다. 새 설치에서 Portal을 고르면 OAuth 로그인으로 모델과 Tool Gateway를 함께 설정한다.
hermes model
# 또는
hermes setup첫 대화는 추가 기능을 켜기 전에 hermes로 시작한다. 응답이 돌아온 뒤에만 Telegram·Discord 같은 메시지 채널을 붙일 때는 hermes gateway setup을 실행한다. 이 순서를 지키면 모델 인증 오류와 메시지 채널 오류를 한 번에 진단하지 않아도 된다.
hermes
hermes gateway setupUbuntu 26.04 LTS(2026-08-07)에서 hermes --version과 hermes doctor를 실행하면 설치 버전, Python·가상 환경, 설정 파일과 명령 실행 파일 상태를 확인할 수 있다. 이 두 명령은 대화를 시작하거나 설정을 바꾸지 않고 상태를 읽는다.
hermes --version과 hermes doctor의 설치 상태 확인 결과입니다.자주 막히는 지점과 해결법
hermes: command not found가 나온다
공식 설치 문서는 Linux·macOS에서 새 셸 설정을 읽도록 source ~/.bashrc 또는 source ~/.zshrc를 안내한다. 그래도 명령을 찾지 못하면 ~/.local/bin이 PATH(터미널이 실행 파일을 찾는 폴더 목록)에 들어 있는지 확인한다. 시스템 서비스 사용자라면 다음 두 방법 중 하나로 실행 경로를 추가한다.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# 또는 관리자가 실행
sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermesGitHub 이슈 #9792은 컨테이너의 외부 셸에서 가상 환경 경로가 PATH에 없어 명령을 찾지 못한 사례를 기록한다. 전용 서비스 계정과 컨테이너에서도 같은 원리로 실행 경로를 먼저 점검한다.
Windows 설치가 ripgrep·ffmpeg 단계에서 멈춘다
GitHub 이슈 #78085에는 Windows 11에서 설치기가 winget으로 ripgrep와 ffmpeg를 설치하는 단계에서 더 진행되지 않은 로그가 있다. 설치 출력이 그 단계에 머물면 창을 닫고 설치 과정을 반복하기보다, 설치 프로그램이 사용하는 winget 작업이 끝났는지 먼저 확인한 뒤 로그와 함께 이슈에 남긴다. 새 설치 경로에서 필요한 Python·Node.js·ripgrep·ffmpeg는 설치기가 관리한다.
Windows에서 Playwright Chromium 다운로드 뒤에 진행되지 않는다
GitHub 이슈 #76222은 Windows 11에서 Playwright Chromium 172.8MiB 다운로드가 100%가 된 뒤 설치가 끝나지 않은 사례를 담고 있다. 브라우저 도구가 당장 필요 없다면 Linux VPS에서는 --skip-browser 경로를 쓸 수 있다. Windows에서는 설치 명령, 운영체제 빌드, 마지막 출력 줄을 함께 기록해 해당 이슈의 재현 정보와 비교한다.
검증 방법: 버전·진단·첫 대화 세 단계
설치가 끝났다고 해서 모델 인증까지 끝난 것은 아니다. 아래 순서로 확인한다.
hermes --version으로 설치된 버전을 확인한다.hermes doctor로 Python, 가상 환경, 설정, 인증 제공자, 도구 상태를 읽는다.hermes를 실행해 짧은 질문을 보내고 응답을 확인한다.
hermes --version
hermes doctor
hermes업데이트 가능 여부만 먼저 보려면 hermes update --check를 쓴다. 이 명령은 원격 main과 커밋을 비교하지만 파일을 바꾸거나 gateway를 재시작하지 않는다. 실제 업데이트 뒤에는 다시 hermes doctor와 hermes --version을 실행한다.
출처: Hermes Agent 공식 Installation, 공식 Quickstart, 공식 Platform Support, 공식 Updating & Uninstalling, GitHub 이슈 #9792, GitHub 이슈 #78085, GitHub 이슈 #76222 (2026-08-07 확인)