Hermes Agent 설치와 첫 작업 실행

Hermes Agent를 설치한 뒤 첫 모델 응답까지 확인하는 가장 짧은 경로를 정리한다.

데스크톱 앱이 필요하면 macOS·Windows용 설치 프로그램을, CLI만 필요하면 shell 설치 프로그램을 선택한다.
hermes setup 또는 hermes model로 provider와 model을 정한다.
진단 예제는 credential 값을 읽거나 출력하지 않고 CLI, 설정 파일 존재 여부, secret 파일 권한을 점검한다.
hermes -z를 쓰면 script에서 최종 응답만 받을 수 있다.

1. 설치 방법 선택

macOS와 Windows에서 Desktop 앱까지 쓸 계획이라면 공식 Desktop installer가 간단하다. 터미널에서만 Hermes를 쓸 Linux, macOS, WSL2 환경은 CLI 설치 프로그램으로 충분하다. 표준 설치 프로그램은 uv, Python, Node.js 같은 실행 의존성을 함께 관리하므로 Python 환경을 미리 만들 필요가 없다.

Linux, macOS, WSL2에서는 다음 명령을 실행한다.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows native PowerShell에서는 다음 명령을 사용한다.

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

설치가 끝나면 새 shell을 열거나 shell 설정을 다시 불러온다. hermes를 찾지 못하면 ~/.local/bin이 PATH에 들어 있는지 먼저 본다.

2. Provider와 model 설정

처음 설정한다면 전체 안내를 여는 명령부터 시작한다.

hermes setup

이미 쓸 provider를 알고 있거나 model만 바꾸려면 model picker를 연다.

hermes model

API key, token, password 같은 secret과 일반 설정은 역할이 다르다. 일반 설정은 config.yaml, secret은 .env 또는 Hermes가 지원하는 인증 저장소에 둔다. 값을 확인하려고 두 파일을 터미널에 출력하지 않는다.

3. 설치 상태를 값 노출 없이 점검

이 편의 진단 예제는 Python 표준 라이브러리만 사용한다. 저장소 루트에서 다음처럼 실행한다.

bash examples/chapter-01-install-first-run/hermes-preflight.sh

hermes doctor까지 포함하려면 --doctor를 붙인다. doctor의 원문 출력은 다시 내보내지 않고 exit code만 결과에 담는다.

bash examples/chapter-01-install-first-run/hermes-preflight.sh --doctor

정상 설치에서는 다음 형태의 결과가 나온다. 버전은 설치 시점에 따라 달라진다.

Hermes preflight: PASS
version: 0.21.1
required commands: chat, doctor, model, setup
config present: yes
secret file present: yes
secret file permissions: private
doctor exit code: 0

secret file present: no가 항상 오류인 것은 아니다. OAuth만 쓰는 설정에는 .env가 없을 수 있다. 반면 config present: no, 필수 명령 누락, doctor의 nonzero exit는 실패로 처리된다.

4. 진단기가 확인하는 경계

진단기는 다음 정보만 결과에 포함한다.

semantic version
chat, doctor, model, setup 명령 제공 여부
config와 secret 파일의 존재 여부
secret 파일이 group 또는 other 사용자에게 열려 있는지 여부
선택적으로 실행한 doctor의 exit code

파일 경로, config 내용, 환경 변수, API key, OAuth token, auth.json 내용은 출력하지 않는다. hermes doctor --fix도 호출하지 않으므로 설정을 바꾸지 않는다.

JSON 결과가 필요하면 --json을 추가한다.

bash examples/chapter-01-install-first-run/hermes-preflight.sh --doctor --json

이 출력은 CI에서 status와 exit code를 판정하기에는 충분하지만 credential 감사를 대신하지 않는다.

5. 첫 작업 실행

설정이 끝났으면 짧고 판정하기 쉬운 prompt로 model 연결을 확인한다.

hermes -z "Reply with exactly: Hermes is ready"

-z는 script용 one-shot mode다. banner, spinner, tool preview 없이 최종 응답 text만 출력한다.

Hermes is ready

이 명령은 실제 model을 호출하므로 provider 인증과 사용 가능한 model이 필요하며, provider 정책에 따라 비용이 발생할 수 있다. 대화형 세션이 필요하면 hermes를 실행한다.

hermes

6. 예제 테스트

예제 테스트는 실제 credential 대신 임시 fake CLI를 사용한다. secret sentinel과 임시 경로가 결과에 섞이지 않는지, 필수 명령이 없을 때 fail-closed로 끝나는지, doctor 실패가 요약되는지를 다룬다.

python3 -m unittest discover -s examples/chapter-01-install-first-run/tests -v
bash tests/test_preflight.sh

두 명령은 실제 provider를 호출하지 않는다.

7. 자주 막히는 지점

hermes를 찾지 못하면 새 shell을 연 뒤 PATH를 확인한다. CLI는 실행되지만 chat이 실패하면 hermes model을 다시 열어 provider, model, 인증 방식을 확인한다. doctor가 실패하면 원문 진단을 터미널에서 직접 읽되, issue나 chat에 붙여 넣기 전 key와 local path가 없는지 살핀다.

여기서 한 번의 clean chat까지 성공시킨 다음 Gateway, Cron, Skills 같은 기능을 추가하는 편이 문제 범위를 좁히기 쉽다. 다음 편에서는 CLI, TUI, Desktop의 역할과 session 재개 방식을 구분한다.

[Hermes Agent 실전 01] Hermes Agent 설치와 첫 작업 실행