튜토리얼 4: Hermes 업데이트 & 제거하기

Hermes 에이전트 튜토리얼 시리즈에 다시 오신 것을 환영합니다! 이번 편에서는 모든 사용자가 결국 알아야 할 내용을 다뤄볼게요: Hermes를 최신 상태로 유지하는 방법과, 때가 되었을 때 작별 인사를 하는 방법입니다. 걱정 마세요 — 생각보다 훨씬 간단하니까요.

Hermes 업데이트: 명령어 하나면 끝

Hermes를 업데이트하는 가장 쉬운 방법은 단 하나의 명령어입니다:

hermes update

끝입니다. 이 명령어가 모든 어려운 작업을 대신 처리해 줍니다. main 브랜치에서 최신 코드를 가져오고, 의존성을 업데이트하며, 마지막 업데이트 이후 추가된 새로운 구성 옵션이 있는지도 물어봅니다. 꽤 편리하죠?

업데이트 중에는 실제로 무슨 일이 일어날까?

뒤에서 어떤 일이 벌어지는지 궁금하실 수도 있겠네요. 정리해 드릴게요:

업데이트 전 스냅샷 — 변경 사항이 적용되기 전에 Hermes는 중요한 상태 파일들(페어링 데이터, cron 작업, config.yaml, .env 등)의 가벼운 스냅샷을 저장합니다. 1 GiB가 넘는 파일은 건너뛰므로 대용량 데이터베이스가 속도를 저하시키지 않습니다. 이 스냅샷은 설치된 모든 프로필에 대해 생성되며, 각각 고유한 state-snapshots/ 디렉토리에 저장됩니다.
Git pull — Hermes가 main 브랜치에서 최신 코드를 가져오고 서브모듈도 업데이트합니다.
Pull 후 구문 검증 + 자동 롤백 — Pull이 끝나면 Hermes는 모든 명령어가 시작 시 필요로 하는 9개의 핵심 파일을 검사합니다. 파싱에 실패하는 파일이 있으면(예: 병합 충돌 마커 같은 것), Hermes는 자동으로 이전 버전으로 롤백하여 셸이 부팅 가능한 상태를 유지합니다. 업스트림에서 수정 사항이 반영되면 hermes update를 다시 실행하기만 하면 됩니다.
의존성 설치 — uv pip install -e ".[all]"을 실행하여 새로 추가되거나 변경된 의존성을 설치합니다.
구성 마이그레이션 — 새로운 구성 옵션을 감지하고 설정하도록 안내합니다.
게이트웨이 자동 재시작 — 실행 중인 게이트웨이가 새로고침되어 새 코드가 즉시 적용됩니다. 서비스로 관리되는 게이트웨이(Linux의 systemd, macOS의 launchd)는 서비스 관리자를 통해 재시작되고, 수동 게이트웨이는 자동으로 다시 실행됩니다.

구성 프롬프트를 건너뛰었다고요? 문제없습니다!

업데이트 중에 구성 프롬프트를 건너뛰었다면, 나중에 다시 확인할 수 있습니다:

hermes config check    # 무엇이 빠졌는지 확인
hermes config migrate  # 대화형으로 추가

다른 브랜치에서 업데이트하기

기본적으로 hermes update는 origin/main을 추적합니다. 하지만 릴리스 후보나 기능 브랜치를 테스트하고 싶다면 어떻게 할까요? --branch 플래그를 사용하세요:

hermes update --branch release-candidate
hermes update --check --branch experimental   # 얼마나 뒤처져 있는지 미리 확인만 하기

로컬 체크아웃이 다른 브랜치에 있다면, Hermes는 커밋되지 않은 작업을 자동으로 스태시하고 대상 브랜치로 전환한 다음 pull을 수행합니다. 로컬에 존재하지 않는 브랜치는 origin/<이름>에서 자동으로 추적됩니다. 브랜치가 어디에도 존재하지 않으면 명령어는 깔끔하게 실패하고 스태시된 변경 사항을 복원합니다.

파킹된 브랜치는 어떻게 될까?

체크아웃이 기능 브랜치에 머물러 있다면, hermes update는 이를 스마트하게 처리합니다:

완전히 병합된 브랜치 — Hermes가 완전히 병합되었다고 알려주고 main으로 전환합니다.
병합되지 않은 커밋, 깨끗한 작업 트리 — Hermes는 여전히 main으로 전환하여 업데이트를 진행합니다(데스크톱 앱이나 cron 작업 같은 비대화형 호출자에게 중요). 커밋은 그대로 유지되며, Hermes는 브랜치 이름과 돌아가는 방법을 큰 소리로 알려줍니다.

의도적으로 브랜치에 커스텀 패치를 유지하고 있다면, config.yaml에 다음을 설정하세요:

updates:
  parked_branch_strategy: update_in_place

이렇게 하면 브랜치를 떠나는 대신 origin/main을 브랜치 안으로 병합합니다. 가능하면 fast-forward를 사용하고, 분기(divergence)가 발생하면 안전 태그를 만들고 충돌 시 깔끔하게 중단합니다.

비대화형 업데이트 중 로컬 변경 사항

터미널에서 hermes update를 실행하면, Hermes는 커밋되지 않은 변경 사항을 스태시하고 pull한 다음 복원할지 물어봅니다. 하지만 터미널 없이 업데이트가 실행될 때(데스크톱 앱에서처럼), Hermes는 작업 트리가 더티(dirty) 상태이면 업데이트를 건너뜁니다 — 브랜치 이름과 얼마나 뒤처져 있는지를 알리는 큰 경고와 함께요. 업데이트가 성공한 척하지 않습니다!

Hermes 제거하기

작별할 때가 되었다면, 제거는 간단합니다. 정확한 제거 절차는 해당 플랫폼의 문서를 확인하세요. 일반적으로 Hermes 바이너리를 제거하고 생성된 구성 디렉토리를 정리하면 됩니다.

마무리

hermes update 하나로 Hermes를 최신 상태로 유지하는 것은 정말 간단합니다. 스냅샷, 자동 롤백, 브랜치 처리 같은 내장 안전장치 덕분에 안심하고 업데이트할 수 있습니다. 그리고 떠나야 할 때가 온다면, 제거도 그만큼 간단합니다.

다음 튜토리얼도 기대해 주세요!