2026-06-09 — systemd restart guardrails for Hermes gateway/cron reliability

핵심 요약

오늘의 단일 학습 주제는 Hermes gateway/cron을 systemd user service로 운영할 때의 재시작 가드레일이다. 장기 실행 gateway는 Restart=on-failure로 자동 복구하되, RestartSec와 StartLimitIntervalSec/StartLimitBurst를 명시해 OAuth/provider 장애나 잘못된 profile 설정으로 인한 crash loop를 제한해야 한다.

웹 검색/추출은 Tavily 오류 및 DNS 오류로 실패했다. 대신 현재 세션에 로드된 Hermes Agent skill 문서와 로컬 man systemd.service, man systemd.unit, man systemd.exec를 기준으로 정리했다. 외부 링크는 공식 문서 URL만 기록하되, 오늘 실행 시점의 웹 본문 검증은 미완료다.

왜 중요한가

Phillip의 서버에서 Hermes는 Telegram/Mattermost gateway, cron briefing, profile별 specialist agent처럼 장시간 무인 실행되는 역할이 많다. 이 계층의 장애는 코드 버그보다 운영 설정 문제인 경우가 많다.

중요한 이유:

• gateway가 죽으면 agent가 살아 있어도 사용자는 응답을 받지 못한다.
• cron job은 실행 성공과 delivery 성공을 분리해서 봐야 한다.
• OAuth/provider 오류가 반복될 때 즉시 무한 재시작하면 로그만 증폭되고 원인 파악이 어려워진다.
• profile별 .env, auth.json, service unit이 달라 default profile 정상만으로 specialist profile 정상까지 보장되지 않는다.

실무 적용

Hermes gateway 또는 profile gateway가 불안정할 때의 기본 흐름:

1. unit 이름 확인

   systemctl --user list-units 'hermes-gateway*'
   hermes profile list
   

2. Hermes 관점 상태 확인

   hermes gateway status
   hermes -p <profile> gateway status
   hermes cron list
   

3. systemd 관점 상태 확인

   systemctl --user status <unit> --no-pager
   journalctl --user -u <unit> -n 80 --no-pager
   

4. 로그에서 provider/auth와 transport를 분리
   • provider/auth: OAuth refresh failure, HTTP 401/403, token consumed, missing API key
   • transport: Telegram/Slack/Mattermost token, webhook/polling, chat/channel id
5. 재시작 정책은 unit 원본 수정 대신 drop-in override 사용
   • Hermes CLI가 생성한 service 파일은 업데이트될 수 있으므로 직접 편집보다 override가 안전하다.

구현/운영 패턴

재사용 패턴은 [[hermes-gateway-cron-systemd-guardrails]]에 반영했다.

핵심 drop-in 형태:

[Unit]
StartLimitIntervalSec=10min
StartLimitBurst=5

[Service]
Restart=on-failure
RestartSec=10s

적용 명령 예시:

UNIT=hermes-gateway.service
mkdir -p "$HOME/.config/systemd/user/${UNIT}.d"
$EDITOR "$HOME/.config/systemd/user/${UNIT}.d/10-restart-guardrails.conf"
systemctl --user daemon-reload
systemctl --user restart "$UNIT"
systemctl --user status "$UNIT" --no-pager

운영 원칙:

• Restart=on-failure: long-running service 오류 자동 복구 기본값으로 적합.
• RestartSec=10s: systemd 기본 100ms보다 완만하게 재시작해 로그 폭주를 줄인다.
• StartLimitIntervalSec/StartLimitBurst: 반복 실패 시 멈추게 해서 운영자가 원인 분석할 기회를 만든다.
• SSH logout 후 user service 유지가 필요하면 loginctl enable-linger <user> 상태를 확인한다.
• cron 보고서 prompt에는 delivery, archive path, source rule, failure rule, duplicate job 확인을 명시한다.

리스크/검증 필요

• 오늘 웹 검색이 실패했으므로 공식 웹 문서 최신 본문은 직접 검증하지 못했다. 단, 로컬 man page는 현재 서버의 systemd 구현 기준으로 신뢰 가능하다.
• Hermes가 실제 생성한 unit 이름/내용은 설치 방식과 profile alias에 따라 다를 수 있다. 적용 전 반드시 systemctl --user list-units 'hermes-gateway*'로 확인한다.
• 너무 낮은 StartLimitBurst는 일시적 네트워크 장애에서 자동 복구를 막을 수 있다. gateway 중요도와 장애 빈도에 맞춰 조정한다.
• WatchdogSec=는 service가 sd_notify()로 heartbeat를 보내는 구조일 때 의미가 크다. Hermes gateway에 바로 적용하기 전 지원 여부 확인이 필요하다.
• provider OAuth 충돌은 systemd 재시작 정책으로 해결되지 않는다. refresh token 재인증, stale CLI/tmux process 정리, profile별 auth.json 점검이 별도 필요하다.

다음 학습 질문

• Hermes gateway service 파일이 profile별로 정확히 어떤 이름과 ExecStart를 생성하는가?
• Hermes cron scheduler 자체도 systemd user unit으로 관리되는지, gateway와 분리된 failure domain인지 확인할 필요가 있는가?
• profile별 gateway smoke test를 no_agent watchdog으로 만들 때 가장 안전한 stdout/silent contract는 무엇인가?
• Mattermost/Telegram gateway에서 transport 성공과 model/provider 실패를 자동 분류하는 로그 parser를 만들 수 있는가?

관련 링크

• [[hermes-gateway-cron-systemd-guardrails]]
• Hermes Cron docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
• Hermes Messaging docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/
• systemd.service official manual: https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
• systemd.unit official manual: https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html
• systemd.exec official manual: https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html