🪽 Hermes 02. 설치와 첫 실행

Hermes를 처음 깔 때 가장 흔한 실수는 설치 자체에 시간을 너무 많이 쓰는 것이다. 공식 문서를 기준으로 보면 실제 핵심은 세 단계뿐이다. 설치, 모델 연결, 첫 대화다. 여기서 한 번 제대로 잡아 두면, 다음 글에서 다룰 Telegram 연결과 메모리/지식 루프 설정도 훨씬 매끄럽게 이어진다.

이번 글은 “모든 기능을 한 번에 세팅하는 문서”가 아니다. 대신 처음 깐 사람이 10분 안에 정상 동작을 확인하는 경로에 집중한다. 이후 확장은 그다음 단계다.

안내: 이 글은 Hermes 공식 문서와 공식 저장소를 바탕으로 정리했고, 구조화와 문장 정리에 생성형 AI를 보조적으로 활용했습니다.

이번 글에서 끝내는 목표

이 글을 끝내면 아래 네 가지가 되어 있어야 한다.

Hermes가 정상 설치되어 있다
사용할 모델이 하나 연결되어 있다
CLI 또는 TUI에서 첫 대화가 가능하다
다음 단계인 Telegram 연결로 넘어갈 준비가 끝난다

flowchart LR
A[설치] --> B[모델 연결]
B --> C[첫 실행]
C --> D[첫 대화 확인]
D --> E[Telegram 준비]

가장 짧은 설치 경로

Hermes 공식 Quickstart는 원라인 설치 스크립트를 먼저 제시한다.

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

지원 축은 Linux, macOS, WSL2, Android Termux다. Windows는 네이티브보다 WSL2 안에서 실행하는 방식을 권장한다.

설치가 끝나면 셸을 다시 읽어야 한다.

source ~/.bashrc
# 또는
source ~/.zshrc

Quickstart: https://hermes-agent.nousresearch.com/docs/getting-started/quickstart
저장소: https://github.com/nousresearch/hermes-agent

여기서 중요한 건 설치 명령 자체보다, 설치 직후 바로 다음 단계로 넘어가는 흐름이다. 설치만 끝내고 멈추면 실제로는 절반도 온 게 아니다.

운영체제별로 먼저 알아둘 점

macOS / Linux

공식 문서 흐름대로 가장 무난하다. 설치 후 바로 hermes 또는 hermes --tui로 시작하면 된다.

Windows

공식 문서는 WSL2 설치 후 그 안에서 Hermes를 실행하는 경로를 권장한다. Windows 본체에서 바로 붙잡고 씨름하기보다, WSL2 안에 기준 환경을 먼저 만들고 들어가는 편이 훨씬 덜 꼬인다.

Android / Termux

공식 문서에 별도 Termux 가이드가 있다. 다만 이 시리즈에서는 모바일을 설치 지점으로 삼기보다, 데스크톱에서 세팅한 뒤 Telegram과 Gboard로 모바일 사용 루틴을 붙이는 쪽을 더 추천한다.

설치 직후 가장 먼저 할 일, 모델 하나 연결하기

Hermes는 설치 직후 바로 대화가 가능해 보이지만, 실제로는 쓸 모델이 연결돼 있어야 의미가 있다. Quickstart 문서는 hermes model, hermes tools, hermes setup 세 명령을 먼저 제시한다.

hermes model
hermes tools
hermes setup

여기서 가장 실용적인 순서는 이렇다.

hermes model로 모델 제공자 하나를 고른다
hermes tools는 기본만 확인한다
처음에는 hermes setup으로 모든 걸 한 번에 만지기보다, 모델이 먼저 정상 연결되는지 본다

Quickstart 기준으로 Hermes는 Nous Portal, OpenAI Codex, Anthropic, OpenRouter, Gemini, Copilot, Custom Endpoint 등 꽤 넓은 provider를 지원한다. 그리고 공식 문서가 분명히 말하는 조건이 하나 있다.

최소 64K 컨텍스트 모델을 써야 한다.

즉, 너무 작은 컨텍스트 모델을 붙이면 설치는 돼도 실제 에이전트 워크플로가 만족스럽게 안 돌아갈 수 있다.

첫 실행은 CLI보다 TUI를 추천하는 이유

공식 문서상 Hermes는 hermes와 hermes --tui 두 진입점을 모두 제공한다.

hermes
hermes --tui

문서 설명을 보면 TUI는 modal overlays, mouse selection, non-blocking input을 포함한 더 현대적인 인터페이스다. 처음 쓰는 사람에게는 hermes --tui가 더 직관적이다.

Quickstart: https://hermes-agent.nousresearch.com/docs/getting-started/quickstart
CLI Guide: https://hermes-agent.nousresearch.com/docs/user-guide/cli

왜 처음엔 TUI가 더 좋은가

상태를 눈으로 보기가 쉽다
slash command autocomplete가 빨리 익는다
세션 사용량과 흐름을 덜 헤맨다

CLI가 더 좋은 경우

터미널에 익숙하다
스크립트처럼 짧게 반복해서 쓴다
이후 worktree, skill preload, quick command까지 깊게 쓸 계획이다

처음엔 TUI로 감을 잡고, 익숙해지면 CLI와 병행하는 방식이 가장 무난하다.

첫 대화에서 꼭 해봐야 할 4가지

설치가 끝났다면 이제 “말이 통하는지”만 보지 말고, 에이전트로서 기본이 되는 행동을 체크해야 한다.

1) 일반 질문

What can you help me with?

가장 기본적인 응답과 로드된 도구 상태를 본다.

2) 도구 호출 확인

What's my disk usage? Show the top 5 largest directories.

Quickstart 예시처럼 terminal tool이 정상적으로 도는지 본다.

3) slash command 감 잡기

입력창에서 /를 눌러 /help, /tools, /model이 보이는지 확인한다.

4) 세션 재개 확인

한 번 종료한 뒤 아래 명령이 자연스럽게 되는지 본다.

hermes --continue
# 또는
hermes -c

이 네 가지만 되면 설치 성공이라고 봐도 된다.

미니 사례 1, 설치는 됐는데 뭘 해야 할지 모르겠을 때

가장 흔한 상태다. 프로그램은 깔렸는데, 막상 무엇이 정상인지 기준이 없어서 멈춘다.

이럴 때는 아래 순서만 보면 된다.

hermes model에서 모델 하나 연결
hermes --tui 실행
/tools 확인
디스크 사용량 같은 간단한 도구 호출 한 번
종료 후 hermes --continue 확인

이 흐름을 통과하면 “설치됨”이 아니라 “쓸 수 있음” 상태로 넘어간다.

미니 사례 2, 처음부터 모든 기능을 붙이려다 꼬일 때

처음부터 gateway, voice, skills, MCP, remote backend를 다 붙이려고 하면 거의 항상 복잡해진다. 공식 문서도 사실은 더 단순하다. Quickstart는 먼저 설치, 모델, 첫 대화만 본다. messaging, voice, cron, skills는 모두 그다음 단계로 소개한다.

즉, 첫날 목표는 이 정도면 충분하다.

모델 하나 연결
TUI 실행
기본 대화 성공
tool 호출 성공

이 기준이 잡혀야 나중에 Telegram 연결 문제도 원인을 분리하기 쉽다.

설정 파일 구조를 미리 알면 덜 헤맨다

Configuration 문서는 Hermes 홈 디렉터리를 이렇게 설명한다.

~/.hermes/config.yaml : 일반 설정
~/.hermes/.env : API 키와 비밀값
~/.hermes/auth.json : OAuth 자격 정보
~/.hermes/SOUL.md : 에이전트 정체성
~/.hermes/memories/ : 지속 메모리
~/.hermes/skills/ : 스킬
~/.hermes/cron/ : 예약 작업
~/.hermes/sessions/ : 게이트웨이 세션
~/.hermes/logs/ : 로그
Configuration: https://hermes-agent.nousresearch.com/docs/user-guide/configuration

이 구조를 먼저 알고 있으면, 나중에 설정이 꼬였을 때도 어디를 봐야 하는지가 빨라진다.

초보자용 규칙 한 줄

비밀키는 .env
나머지 설정은 config.yaml

이것만 기억해도 초반 실수가 많이 줄어든다.

첫날에는 로컬 백엔드로 시작하는 게 안전하다

Configuration 문서는 Hermes가 local, docker, ssh, modal, daytona, singularity까지 다양한 terminal backend를 지원한다고 설명한다. 하지만 처음부터 Docker나 SSH로 들어가면 문제 원인이 모델인지, 환경인지, 백엔드인지 구분이 어려워진다.

그래서 첫날 기본값은 단순하다.

terminal backend는 local로 시작
모델 연결 먼저 확인
그다음 안전이 필요할 때 Docker로 이동

이 순서가 좋은 이유는 간단하다. 처음에는 기능 검증이 먼저고, 격리와 고도화는 그다음이기 때문이다.

게이트웨이는 아직 설치 완료의 기준이 아니다

Messaging 문서를 보면 Hermes gateway는 여러 플랫폼을 묶는 단일 백그라운드 프로세스다. Telegram, Discord, Slack, WhatsApp, Signal, Email 등 다양한 플랫폼을 붙일 수 있다.

hermes gateway setup
hermes gateway

하지만 첫날 기준으로 gateway는 아직 “필수 완료 조건”이 아니다. 지금 단계에서는 CLI/TUI가 정상 동작하는지가 더 중요하다. gateway는 다음 글에서 다룰 Telegram 연결 편에서 본격적으로 가는 편이 맞다.

Messaging Gateway: https://hermes-agent.nousresearch.com/docs/user-guide/messaging

왜 Telegram은 다음 편으로 넘기나

설치 문제와 채널 문제를 분리할 수 있다
allowlist, pairing, gateway service 개념을 따로 잡는 편이 더 이해가 쉽다
폰에서 쓰기 전, 로컬에서 agent 성격을 먼저 보는 게 훨씬 덜 헷갈린다

처음부터 꼭 지켜야 할 보안 기준

Hermes Security 문서는 dangerous command approval, container isolation, DM pairing, allowlist를 꽤 분명하게 설명한다. 특히 gateway는 기본적으로 allowlist 또는 pairing 없는 상태에서 아무나 열어 두는 걸 권장하지 않는다.

Security: https://hermes-agent.nousresearch.com/docs/user-guide/security

처음 설치할 때 기억할 건 세 가지면 충분하다.

위험 명령 승인은 끄지 않는다
gateway 공개 전에 allowlist 또는 pairing 개념을 이해한다
처음엔 로컬에서만 정상 동작 확인을 끝낸다

이 세 가지만 지켜도 설치 초반 사고 가능성이 크게 줄어든다.

10분 체크리스트

🧠 칠판 치트시트

설치는 원라인으로 끝낸다

첫 목표는 모델 1개 + 첫 대화 1회다

처음 인터페이스는 hermes --tui가 가장 쉽다

gateway와 Telegram은 다음 단계로 분리한다

설치 스크립트 실행 완료
셸 재로드 완료
hermes model에서 모델 1개 연결 완료
hermes --tui 실행 확인
/tools 확인 완료
간단한 tool call 1회 성공
hermes --continue로 세션 재개 확인

이 다음에 바로 할 것

설치가 끝났다면 다음 질문은 하나다.

“이걸 이제 어떻게 폰에서 쓸까?”

그래서 다음 글은 Hermes를 Telegram에 붙이는 흐름으로 가는 게 가장 자연스럽다. 여기서부터 실제 사용감이 급격히 올라간다. 그리고 그다음에야 llm-wiki, Obsidian, Gboard 같은 지식 루프와 입력 루틴이 의미를 갖기 시작한다.

3줄 결론

Hermes 설치의 진짜 목표는 설치 완료가 아니라 첫 대화와 첫 도구 호출 성공이다.
처음에는 모델 1개, TUI 1개, tool call 1회만 확인하면 충분하다.
Telegram, llm-wiki, Obsidian, Gboard는 그다음 단계로 나눠야 덜 꼬이고 더 빨리 쓸 수 있다.

일하는 ai

탐색기