LLM Wiki

Android Termux에서 Hermes Agent 설치 가이드

7 min read

Android Termux에서 Hermes Agent 설치 가이드

Android의 Termux 환경에서는 Hermes Agent를 바로 쓰는 수준이 아니라, Python·Rust 의존성을 직접 컴파일해야 하는 설치형 워크로드로 봐야 한다.

개요

이 가이드는 Android의 Termux 환경에 hermes-agent를 설치하는 실전 절차를 정리한 것이다. 모바일 환경은 데스크톱 Linux/macOS보다 패키지 빌드 여건이 훨씬 까다롭다. 특히 Python 네이티브 확장과 Rust 기반 의존성을 직접 컴파일해야 하므로, 설치 전 메모리·배터리·발열·화면 꺼짐 방지까지 함께 고려해야 한다.

핵심은 두 가지다. 첫째, Termux 기본 툴체인을 먼저 안정적으로 준비해야 한다. 둘째, Rust 의존성 때문에 공식 rustup을 억지로 쓰지 말고, Termux가 제공하는 네이티브 pkg install rust 패키지를 사용하는 편이 훨씬 안전하다.

설치 전 주의사항

1. RAM 부족 위험

  • RAM 4GB 이하 구형 기기에서는 컴파일 도중 OOM(Out of Memory)으로 Termux가 강제 종료될 수 있다.
  • 설치 전 백그라운드 앱을 모두 정리하는 편이 좋다.

2. 배터리·발열

  • 소스 코드 컴파일은 CPU를 오래 100% 가까이 사용한다.
  • 충전기를 연결한 상태에서 진행하는 편이 안전하다.

3. 화면 꺼짐 방지

  • 설치 중 화면이 꺼지면 Android가 Termux 백그라운드 작업을 중단시킬 수 있다.
  • 설치가 끝날 때까지 화면 켜짐 상태를 유지하는 편이 좋다.

1) Termux 업데이트 및 필수 패키지 설치

먼저 패키지 목록을 최신화하고 Python, Git, 컴파일 도구를 설치한다.

pkg update && pkg upgrade -y
pkg install python git clang make pkg-config libffi openssl binutils -y

이 단계는 Python 가상환경 생성, C 확장 빌드, OpenSSL·ffi 링크를 위한 최소 준비로 보면 된다.

2) 자주 터지는 Rustup panic 우회

Hermes Agent의 일부 의존성(예: jiter, rpds-py)은 Rust 컴파일러가 필요하다. 문제는 Termux에서 공식 rustup 설치 스크립트를 그대로 쓰면 다음과 같은 panic이 자주 난다는 점이다.

  • Expect rustls-platform-verifier to be initialized
  • rustup panic / crash

왜 이런 문제가 생기나

공식 rustup은 설치 중 서버와 통신하면서 Android 시스템 인증서와 SSL/TLS 검증을 건드리는데, Termux의 파일 시스템·권한 구조가 일반 Linux와 달라 충돌하는 경우가 있다. 즉, rustup 자체를 억지로 살리기보다 Termux 전용 Rust 패키지를 쓰는 쪽이 현실적이다.

권장 해결 절차

① 꼬인 rustup 설정 제거

rm -rf ~/.cargo ~/.rustup

② Termux 네이티브 Rust 설치

pkg update
pkg install rust binutils -y

③ 설치 확인

rustc --version
cargo --version

버전 문자열이 정상적으로 출력되면 Rust 컴파일러 준비가 끝난 것이다.

3) Hermes Agent 설치 스크립트 실행

필수 도구가 준비되면 공식 설치 스크립트를 실행한다.

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

이 스크립트는 저장소를 클론하고, 가상환경을 만들고, 의존성을 설치한다. Android 기기 성능에 따라 이 단계는 꽤 오래 걸릴 수 있다.

4) 설치가 끊겼을 때 수동으로 재개

네트워크 문제나 메모리 부족으로 설치가 중단되더라도 처음부터 다시 할 필요는 없다. 이미 클론된 저장소에서 Termux 제약 파일을 사용해 재개하면 된다.

cd /data/data/com.termux/files/home/.hermes/hermes-agent
python -m pip install -e '.[termux]' -c constraints-termux.txt

이 절차의 의미는 다음과 같다.

  • -e '.[termux]' : Termux용 extra 의존성까지 포함한 editable 설치
  • constraints-termux.txt : 일반 데스크톱과 다른 Android/Termux 제약을 반영한 버전 고정

5) 설치 확인 및 실행 테스트

설치가 끝나면 가상환경을 활성화하고 CLI가 뜨는지 확인한다.

source ~/.hermes/hermes-agent/.venv/bin/activate
python -m hermes_agent --help

--help가 정상 출력되면 최소한 실행 가능한 상태까지는 올라온 것이다.

6) 실제 사용 전 마지막 준비

Hermes Agent를 실제로 구동하려면 LLM API 키 설정이 추가로 필요하다.

  • OpenAI
  • Anthropic
  • 기타 지원 프로바이더

즉 설치 성공과 실제 사용 가능 상태는 다르다. 설치 후에는 환경 변수나 .env를 통해 API 키를 등록해야 한다.

실전 요약

  • Termux에서는 Hermes Agent 설치가 패키지 설치 + 빌드 환경 준비 + 장시간 컴파일 작업이다.
  • 실패 원인의 대부분은 RAM 부족, 화면 꺼짐, 발열, rustup 충돌이다.
  • Rust는 공식 rustup보다 pkg install rust 경로가 더 안정적이다.
  • 설치가 끊겨도 constraints-termux.txt를 이용해 재개할 수 있다.
  • 최종 확인은 python -m hermes_agent --help로 한다.

그래프 뷰

백링크