[인공지능/Hermes] 헤르메스 리눅스에 설치하기

설치 명령어

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

설치 명령어 실행 시 위 사진처럼 자동으로 필요한 과정들을 진행하며 설치한다.

참고로 설치하고자 하는 서버에 오픈클로가 설치되었을 경우 위 사진의 상단부 노란색처럼 오픈클로 데이터를 가져올지 물어본다.
초록색으로 표시 된 "Wolud import"가 가져올 수 있는거고 "Would skip"이 가져오지 못하는 데이터인데 생각보다 가져오지 못하는 데이터가 많은 것을 볼 수 있다.

오픈클로 데이터 마이그레이션에 대해 워닝 메시지인데 그대로 진행하면 기존에 연동 된 메신저가 제대로 동작하지 않을 수 있기에 나는 "N"을 선택 후 세팅은 직접 하기로 했다.

헤르메스 셋업 여부를 결정하는데 간단하게 사용하기 위해 "Quick setup"으로 진행한다.

프로바이더 선택화면인데 원하는 프로바이더를 선택하면 된다. 나는 OpenAI (ChatGPT)를 메인으로 사용하고 있어서 코덱스를 선택했다.

가이드되로 인증하면 된다.

설치 과정에서 선택 여부에 따라 현재 사용 가능한 것과 가능하지 않은 것들을 보여주는데 추후 필요에 따라 부분 설정하면 모든 툴을 사용할 수 있다.
제일 하단에 노란색 글씨로 헤르메스 채팅을 런칭할지 물어보는데 Y를 누른다.

그러면 위 사진처럼 헤르메스 채팅이 런칭된다.

이하 내용 스크립트 상세 분석

스크립트 개요

이 스크립트는 Hermes Agent를 사용자의 홈 디렉터리 아래에 설치하고, Python/Node.js 의존성, CLI 명령어, 설정 파일, 브라우저 도구, 메시징 게이트웨이까지 한 번에 구성하는 설치 스크립트라고 보면 된다.

기본 설치 위치

기본 경로

스크립트는 기본적으로 아래 경로를 사용한다.

~/.hermes
~/.hermes/hermes-agent

구체적으로는 다음 변수를 사용한다.

HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
INSTALL_DIR="${HERMES_INSTALL_DIR:-$HERMES_HOME/hermes-agent}"

즉 기본 구조는 이렇게 된다.

~/.hermes/
├── hermes-agent/      # 소스 코드
├── .env               # API 키 설정
├── config.yaml        # Hermes 설정
├── SOUL.md            # 페르소나 설정
├── cron/
├── sessions/
├── logs/
├── pairing/
├── hooks/
├── image_cache/
├── audio_cache/
├── memories/
└── skills/

지원 옵션

실행 옵션

스크립트는 다음 옵션을 받을 수 있다.

--no-venv
--skip-setup
--branch NAME
--dir PATH
--hermes-home PATH
--help

옵션 의미

옵션	의미
`--no-venv`	Python 가상환경을 만들지 않는다
`--skip-setup`	설치 후 대화형 설정 마법사를 실행하지 않는다
`--branch NAME`	설치할 Git 브랜치를 지정한다. 기본값은 `main`이다
`--dir PATH`	Hermes Agent 소스 설치 위치를 지정한다
`--hermes-home PATH`	Hermes 데이터 디렉터리를 지정한다
`--help`	도움말을 출력한다

예시는 이렇게 쓸 수 있다.

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

OS 감지

감지 대상

스크립트는 uname -s와 Termux 환경 변수를 이용해서 OS를 감지한다.

Linux
macOS
Android Termux
Windows 계열

Windows 처리

Windows가 감지되면 이 Bash 설치 스크립트는 중단된다.

대신 PowerShell 설치 방식을 안내한다.

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

즉 이 install.sh는 Windows용이 아니라 Linux/macOS/Termux용이라고 보면 된다.

설치되는 주요 구성 요소

uv 설치 또는 확인

uv는 Python 패키지 관리자이자 Python 버전 관리 도구로 사용된다.

스크립트는 다음 순서로 uv를 찾는다.

PATH에 있는 uv
~/.local/bin/uv
~/.cargo/bin/uv
없으면 https://astral.sh/uv/install.sh를 통해 설치

curl -LsSf https://astral.sh/uv/install.sh | sh

이 부분도 원격 스크립트를 다시 받아 실행하는 구조다.

즉 이 설치 스크립트는 직접적으로 다음 원격 코드를 실행한다.

https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh
https://astral.sh/uv/install.sh

보안상으로는 다운로드 후 직접 검토하고 실행하는 방식이 더 안전하다.

Python 3.11 확인 또는 설치

스크립트는 Python 3.11을 요구한다.

PYTHON_VERSION="3.11"

일반 Linux/macOS에서는 uv를 통해 Python 3.11을 찾고, 없으면 설치한다.

uv python find 3.11
uv python install 3.11

Termux에서는 uv 대신 시스템 Python + venv + pip를 사용한다.

Python이 없으면 아래처럼 설치한다.

pkg install -y python

Git 확인 또는 설치 안내

스크립트는 git이 있는지 확인한다.

Git이 없으면 OS별 설치 방법을 안내한다.

Ubuntu/Debian 계열은 다음 명령을 안내한다.

sudo apt update && sudo apt install git

Fedora 계열은 다음 명령을 안내한다.

sudo dnf install git

Arch 계열은 다음 명령을 안내한다.

sudo pacman -S git

macOS는 다음 명령을 안내한다.

xcode-select --install

또는 Homebrew를 통해 설치할 수 있다.

brew install git

Termux에서는 다음 명령을 사용한다.

pkg install git

Termux에서는 Git을 자동 설치하려고 한다.

Node.js 확인 또는 설치

Node.js는 Hermes의 브라우저 도구, Playwright, TUI 관련 기능에 사용된다.

스크립트는 Node.js 22 버전을 기준으로 설치한다.

NODE_VERSION="22"

이미 node가 있으면 그대로 사용한다.

없으면 다음 경로도 확인한다.

~/.hermes/node/bin/node

그래도 없으면 OS/아키텍처에 맞는 Node.js 바이너리를 다운로드해서 설치한다.

설치 경로는 아래와 같다.

~/.hermes/node/

그리고 다음 심볼릭 링크를 만든다.

~/.local/bin/node
~/.local/bin/npm
~/.local/bin/npx

Termux에서는 아래 명령으로 설치한다.

pkg install -y nodejs

ripgrep, ffmpeg 설치

스크립트는 다음 도구를 확인한다.

도구	용도
`ripgrep` / `rg`	빠른 파일 검색
`ffmpeg`	TTS 음성 메시지 관련 기능

macOS에서 Homebrew가 있으면 자동 설치를 시도한다.

brew install ripgrep ffmpeg

Ubuntu/Debian 계열에서는 다음 명령을 사용한다.

sudo apt install -y ripgrep ffmpeg

Fedora 계열에서는 다음 명령을 사용한다.

sudo dnf install -y ripgrep ffmpeg

Arch 계열에서는 다음 명령을 사용한다.

sudo pacman -S --noconfirm ripgrep ffmpeg

Termux에서는 다음 패키지들을 설치하려고 한다.

pkg install -y clang rust make pkg-config libffi openssl ripgrep ffmpeg

Linux에서는 sudo가 필요할 수 있다.

스크립트는 ripgrep과 ffmpeg를 선택적 시스템 패키지로 보고, 설치 실패 시 Hermes 설치 자체를 반드시 중단하지는 않는다.

Git 저장소 클론 또는 업데이트

새 설치

설치 디렉터리가 없으면 저장소를 클론한다.

먼저 SSH를 시도한다.

git clone --branch main git@github.com:NousResearch/hermes-agent.git ~/.hermes/hermes-agent

SSH가 실패하면 HTTPS로 재시도한다.

git clone --branch main https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent

SSH는 BatchMode=yes와 ConnectTimeout=5를 사용해서 키가 없을 때 오래 멈추지 않도록 되어 있다.

기존 설치가 있는 경우

이미 설치 디렉터리가 있고 .git 저장소라면 업데이트한다.

수행 흐름은 이렇다.

설치 디렉터리로 이동한다.
로컬 변경사항을 확인한다.
변경사항이 있으면 자동 stash 한다.
git fetch origin을 실행한다.
지정 브랜치로 checkout 한다.
git pull --ff-only를 실행한다.
stash 했던 변경사항 복원을 시도한다.

즉 기존 설치를 덮어쓰기 전에 로컬 변경사항을 보존하려고 한다.

Python 가상환경 생성

기본 동작

기본적으로 venv를 만든다.

~/.hermes/hermes-agent/venv

일반 Linux/macOS에서는 uv를 사용한다.

uv venv venv --python 3.11

Termux에서는 Python 표준 venv를 사용한다.

python -m venv venv

no-venv 사용 시

--no-venv 옵션을 주면 가상환경 생성을 생략한다.

--no-venv

다만 이 경우 시스템 Python 환경에 설치될 수 있으므로 충돌 가능성이 커진다.

Python 패키지 설치

일반 Linux/macOS

기본적으로 editable install을 수행한다.

먼저 모든 extra를 포함해서 설치를 시도한다.

uv pip install -e ".[all]"

실패하면 base install로 fallback한다.

uv pip install -e "."

Ubuntu/Debian 계열에서는 Python 패키지 빌드를 위해 다음 패키지 설치를 제안하거나 시도한다.

build-essential
python3-dev
libffi-dev

Termux

Termux에서는 다음 순서로 설치한다.

python -m pip install --upgrade pip setuptools wheel
python -m pip install -e '.[termux]' -c constraints-termux.txt

실패하면 기본 설치로 fallback한다.

python -m pip install -e '.' -c constraints-termux.txt

또한 Android 빌드 환경을 위해 ANDROID_API_LEVEL을 설정한다.

값을 못 가져오면 기본값으로 24를 사용한다.

Node.js 의존성 설치

루트 package.json

저장소 루트에 package.json이 있으면 아래 명령을 실행한다.

npm install --silent

이건 브라우저 도구 관련 Node 의존성을 설치하는 부분이다.

Playwright Chromium 설치

브라우저 자동화 도구로 Playwright Chromium을 설치한다.

Ubuntu/Debian 계열에서는 다음을 시도한다.

npx playwright install --with-deps chromium

Arch/Manjaro에서는 필요한 시스템 라이브러리를 pacman으로 설치하려고 한다.

sudo pacman -S --noconfirm --needed \
  nss atk at-spi2-core cups libdrm libxkbcommon mesa pango cairo alsa-lib

Fedora/RHEL/CentOS 계열은 자동 의존성 설치를 완전히 지원하지 않으므로 수동 설치 안내를 출력한다.

sudo dnf install nss atk at-spi2-core cups-libs libdrm libxkbcommon mesa-libgbm pango cairo alsa-lib

TUI 의존성 설치

아래 경로에 package.json이 있으면 TUI 의존성을 설치한다.

~/.hermes/hermes-agent/ui-tui/package.json

실행 명령은 다음과 같다.

cd ~/.hermes/hermes-agent/ui-tui
npm install --silent

hermes 명령어 등록

심볼릭 링크 생성

설치 후 hermes 명령어를 전역처럼 사용할 수 있도록 심볼릭 링크를 만든다.

일반 Linux/macOS에서는 다음 위치에 만든다.

~/.local/bin/hermes

Termux에서는 다음 위치에 만든다.

$PREFIX/bin/hermes

가상환경을 쓰는 경우 원본 바이너리는 보통 아래 위치다.

~/.hermes/hermes-agent/venv/bin/hermes

그리고 이렇게 링크된다.

ln -sf ~/.hermes/hermes-agent/venv/bin/hermes ~/.local/bin/hermes

PATH 설정

~/.local/bin이 PATH에 없으면 셸 설정 파일에 추가한다.

zsh에서는 다음 파일을 대상으로 한다.

~/.zshrc
~/.zprofile

bash에서는 다음 파일을 대상으로 한다.

~/.bashrc
~/.bash_profile
~/.profile

fish에서는 다음 파일을 대상으로 한다.

~/.config/fish/config.fish

추가되는 내용은 일반 셸 기준으로 다음과 같다.

# Hermes Agent — ensure ~/.local/bin is on PATH
export PATH="$HOME/.local/bin:$PATH"

fish는 다음 형식이다.

fish_add_path "$HOME/.local/bin"

설정 파일 생성

생성 디렉터리

스크립트는 ~/.hermes 아래에 설정 파일과 데이터 디렉터리를 만든다.

~/.hermes/cron
~/.hermes/sessions
~/.hermes/logs
~/.hermes/pairing
~/.hermes/hooks
~/.hermes/image_cache
~/.hermes/audio_cache
~/.hermes/memories
~/.hermes/skills

.env 생성

없으면 다음 파일을 생성한다.

~/.hermes/.env

저장소에 .env.example이 있으면 복사한다.

cp ~/.hermes/hermes-agent/.env.example ~/.hermes/.env

config.yaml 생성

없으면 다음 파일을 생성한다.

~/.hermes/config.yaml

저장소에 cli-config.yaml.example이 있으면 복사한다.

cp ~/.hermes/hermes-agent/cli-config.yaml.example ~/.hermes/config.yaml

SOUL.md 생성

없으면 기본 페르소나 파일을 만든다.

~/.hermes/SOUL.md

내용은 최소 형태다.

# Hermes Agent Persona

주의할 점은 여기서 # Hermes Agent Persona는 스크립트가 생성하는 파일 내용이다. 이 글의 제목 규칙과는 별개다.

skills 동기화

번들 skills를 사용자 디렉터리로 동기화한다.

~/.hermes/skills/

우선 Python 스크립트로 동기화를 시도한다.

~/.hermes/hermes-agent/tools/skills_sync.py

실패하면 단순 복사 fallback을 수행한다.

설치 후 setup wizard 실행

기본 동작

기본적으로 설치가 끝나면 대화형 설정 마법사를 실행한다.

python -m hermes_cli.main setup

가상환경 사용 시 정확히는 다음처럼 실행된다.

~/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main setup

skip-setup 사용 시

--skip-setup 옵션을 주면 이 단계는 생략된다.

--skip-setup

터미널이 없는 Docker build나 CI 같은 환경에서는 자동으로 생략하고 나중에 실행하라고 안내한다.

hermes setup

메시징 게이트웨이 처리

토큰 감지

설치 후 .env 파일에서 메시징 플랫폼 토큰이 설정되어 있는지 확인한다.

확인하는 변수는 다음과 같다.

TELEGRAM_BOT_TOKEN
DISCORD_BOT_TOKEN
SLACK_BOT_TOKEN
SLACK_APP_TOKEN
WHATSAPP_ENABLED

이 값들이 설정되어 있으면 게이트웨이 실행 또는 서비스 등록을 제안한다.

WhatsApp pairing

WHATSAPP_ENABLED=true인데 세션 파일이 없으면 QR 페어링을 위해 다음 명령 실행을 제안한다.

hermes whatsapp

세션 파일 위치는 다음과 같다.

~/.hermes/whatsapp/session/creds.json

systemd 서비스 설치

Linux에서 systemctl이 있으면 다음 명령을 실행하려고 한다.

hermes gateway install
hermes gateway start

systemd가 없거나 Termux인 경우에는 백그라운드 프로세스로 실행한다.

nohup hermes gateway > ~/.hermes/logs/gateway.log 2>&1 &

설치 완료 후 안내되는 명령어

주요 명령어

설치 완료 후 다음 명령어들이 안내된다.

hermes
hermes setup
hermes config
hermes config edit
hermes gateway install
hermes update

각 의미는 다음과 같다.

명령어	의미
`hermes`	Hermes 채팅 시작
`hermes setup`	API 키 및 설정 구성
`hermes config`	설정 확인/관리
`hermes config edit`	설정 파일 편집
`hermes gateway install`	메시징/cron용 게이트웨이 서비스 설치
`hermes update`	최신 버전으로 업데이트

저작자표시 비영리 변경금지 (새창열림)

'인공지능 > Hermes' 카테고리의 다른 글

[인공지능/Hermes] 슬랙 연동하기 (0)	2026.04.25
[인공지능/Hermes] 헤르메스 메시징 게이트웨이 이해하기 (0)	2026.04.25
[인공지능/Hermes] 헤르메스 메모리 시스템 이해하기 (0)	2026.04.25
[인공지능/Hermes] 헤르메스란 ( feat. 오픈클로와의 차이 ) (0)	2026.04.15

설치 명령어

이하 내용 스크립트 상세 분석

스크립트 개요

기본 설치 위치

기본 경로

지원 옵션

실행 옵션

옵션 의미

OS 감지

감지 대상

Windows 처리

설치되는 주요 구성 요소

uv 설치 또는 확인

Python 3.11 확인 또는 설치

Git 확인 또는 설치 안내

Node.js 확인 또는 설치

ripgrep, ffmpeg 설치

Git 저장소 클론 또는 업데이트

새 설치

기존 설치가 있는 경우

Python 가상환경 생성

기본 동작

no-venv 사용 시

Python 패키지 설치

일반 Linux/macOS

Termux

Node.js 의존성 설치

루트 package.json

Playwright Chromium 설치

TUI 의존성 설치

hermes 명령어 등록

심볼릭 링크 생성

PATH 설정

설정 파일 생성

생성 디렉터리

.env 생성

config.yaml 생성

SOUL.md 생성

skills 동기화

설치 후 setup wizard 실행

기본 동작

skip-setup 사용 시

메시징 게이트웨이 처리

토큰 감지

WhatsApp pairing

systemd 서비스 설치

설치 완료 후 안내되는 명령어

주요 명령어

'인공지능 > Hermes' 카테고리의 다른 글

티스토리툴바