convez.ai
AgenteDevOps & InfraestruturaAvançado
MichaelZelbel

Hermes Claude Code DevOps Watchdog

MichaelZelbel/hermes-claude-code-devops-watchdog

Watchdog DevOps local para saúde contínua do servidor Hermes Agent

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent de monitoramento e reparo automático para servidores Hermes Agent, executado localmente via cron/systemd. Realiza verificações de saúde, alertas segmentados e reparos controlados, escalonando mudanças de risco para o operador.

Instalação

$npx convez-ai MichaelZelbel/hermes-claude-code-devops-watchdog

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 semanas
Versão
v1.2.1
Issues abertas
1
Contribuidores
2

Casos de uso

  • Monitorar saúde de servidor Hermes em produção
  • Reparos automáticos seguros (gateway, jobs, autenticação)
  • Alertas segmentados via Telegram quando necessário
  • Auditoria de 60+ dias com logs de verificações e escalações

Veredito

Solução madura e bem documentada para operações VPS do Hermes Agent, com limites de segurança claros e ciclo de feedback de produção real. Recomendado para operadores que rodam Hermes em máquinas próprias e precisam de observabilidade local confiável.

README

A tradução para o português deste README ainda está na fila.

Claude Code Hermes DevOps Watchdog

This repository contains a Claude Code DevOps workflow for keeping a Hermes Agent server healthy.

Goal: set up a VPS-local watchdog that checks Hermes Agent, the messaging gateway, scheduled jobs, provider authentication, configured tools, and host health; performs only clearly safe repairs; and escalates risky changes to the operator.

Made by Michael Zelbel, who also builds Godspeed Mission Control, a free personal AI you run yourself.

Want the whole server set up around this watchdog? The Hermes DevOps Kit is free on Ko-fi: an installer, a security baseline, backup and cost checks, safe upgrades and alerts on your phone, with this watchdog inside.

What does a watchdog like this fix on a real server? What my watchdog fixed and missed shows 60 days of logs from my own Hermes server: more than 15,000 checks, 25 alerts to my chat, and the week it could not fix.

TL;DR

  1. Install Hermes Agent on your VPS.
  2. Install Claude Code on the same VPS, or on a trusted machine that can SSH into the VPS.
  3. Open Claude Code and use this prompt:
Configure yourself as the Hermes watchdog for this server. Start here: https://raw.githubusercontent.com/MichaelZelbel/hermes-claude-code-devops-watchdog/main/AGENT_START.md

That starter file contains the safety boundaries, dry-run checks, and local cron/systemd recommendations.

Architecture note

The production watchdog should run locally on the VPS via cron or a systemd timer. Claude Code can help generate and test the scripts, but Claude Code /schedule and Claude Cloud Routines are remote cloud agents by default; they cannot access local VPS files, local services, /opt/hermes, /opt/data, or systemctl --user unless you explicitly add SSH/MCP/connectors.

Recommended default:

VPS-local cron/systemd timer -> local check/repair scripts -> Telegram alert only when needed

See docs/local-cron-telegram.md for the recommended setup.

Quick start

  1. Clone or copy this repository onto the machine where Claude Code will run.
  2. Make sure Claude Code can reach the Hermes VPS, either by running directly on the VPS or by SSHing into it.
  3. Open this repository in Claude Code.
  4. Start with a manual dry run before scheduling anything.

Suggested first prompt for Claude Code:

You are setting up this repository as a Hermes DevOps watchdog.

Read README.md, CLAUDE.md, and hermes-devops-runbook.md first.

Then do a manual safe dry run of the quick repair workflow from prompts/hourly-quick-repair.md.

Important boundaries:
- Do not change firewall, SSH, Tailscale, secrets, auth, config, packages, or OS settings.
- Do not delete data.
- Do not update Hermes yet.
- Do not reveal tokens from /opt/data/.env, auth.json, provider configs, or chat logs.
- Only run read-only checks unless the Hermes messaging gateway is clearly down.
- If the installed Hermes gateway service is down, you may run `hermes gateway restart` once, then verify and report.
- If Hermes is only running as a foreground process or inside an interactive terminal, do not kill/restart it without operator approval.

After the dry run, report:
1. whether Hermes and the gateway are healthy,
2. which commands worked,
3. any warnings that should be documented,
4. whether this machine is suitable for scheduled watchdog runs,
5. the exact scheduled task prompt/frequency you recommend.

Manual VPS validation

Before enabling a scheduled watchdog, verify the basic commands on the VPS:

hermes status
hermes doctor
hermes gateway status
hermes cron list
hermes model --help
hermes logs --since 1h
hermes logs errors --since 24h
ps -eo pid,cmd --sort=pid | grep -Ei '[h]ermes|gateway|telegram|discord|whatsapp'
df -h
df -i
free -h
uptime

Expected healthy signs:

  • hermes status shows the expected model/provider and configured messaging platforms.
  • hermes doctor has no critical failures for the configured deployment.
  • hermes gateway status matches the intended gateway mode.
  • The gateway process or installed service is running when Telegram/Discord/WhatsApp delivery is expected.
  • Scheduled jobs are present when the operator expects cron jobs.
  • Disk usage is comfortably below warning levels, ideally below 80%.
  • Memory and load are not under sustained pressure.

A gateway that is running but answers nothing after an update

The symptom: systemctl says the gateway is active and it still holds its connection to Telegram. Yet every message gets an error, or scheduled jobs stop running while hermes cron status looks fine. quick-check.sh sees nothing wrong, because by every liveness signal the gateway is up.

The cause: the Hermes files on disk changed under a running gateway. Python keeps the code it already loaded and loads the rest fresh from the new files, so old and new code meet. One restart fixes it.

Since Hermes v0.21.4 (21 September 2026), hermes update restarts such gateways itself, right at update time. templates/stale-check.sh is the net for everything else:

  • a git pull, a pip or uv install, or a hand edit
  • an update that crashed before its restart step
  • a changed config.yaml, which a gateway only reads when it starts

Every five minutes it compares each gateway's start time with the newest code file and with its profile's config.yaml. If the gateway is older, it restarts it once, then leaves it alone for an hour. It never restarts on a guess: whatever it cannot measure counts as fine.

It assumes gateways run as systemd units. It finds the code by asking hermes --version, so set HERMES_SRC if your install keeps it somewhere else. It ignores .py files a gateway never imports (node_modules, tests, virtual environments, caches, docs), because one touched file in node_modules once made a whole fleet look stale. Try it with DRY_RUN=1 first and read /var/log/hermes-watchdog/stale.log.

*/5 * * * *  UNITS="hermes-gateway.service" /opt/hermes-watchdog/templates/stale-check.sh

Recommended scheduling model

Use local cron or a systemd timer on the VPS as the default watchdog runner.

Recommended local jobs:

  1. quick-check.sh

    • Frequency: every 5 minutes, or hourly if you prefer less noise.
    • Source prompt/policy: prompts/hourly-quick-repair.md.
    • Purpose: fast health check, safe gateway repair, Telegram incident report only when needed.
  2. deep-check.sh

    • Frequency: every 6 hours.
    • Source prompt/policy: prompts/six-hour-deep-check.md.
    • Purpose: deeper Hermes, gateway, cron, provider auth, logs, disk/RAM health.
  3. Optional update-maintenance run

    • Frequency: weekly or manual.
    • Source prompt/policy: prompts/update-maintenance.md.
    • Purpose: safe Hermes update flow with pre/post smoke tests and explicit rollback boundaries.
    • Do not auto-update unless the operator explicitly approves that policy.

What about Claude Code /schedule?

Do not assume Claude Code scheduled tasks run on the VPS. Claude Code /schedule and Cloud Routines are remote agents unless you deliberately provide secure access to the VPS.

Use remote scheduled agents only for advanced setups such as:

  • SSH from the remote agent into a restricted watchdog user,
  • MCP/connectors that can safely run the local checks,
  • a strongly authenticated HTTPS status endpoint.

For most users, local cron + Telegram is simpler, safer, and more reliable.

Files

  • hermes-devops-runbook.md — operational policy and escalation rules.
  • docs/local-cron-telegram.md — recommended production architecture using local cron/systemd timer plus Telegram alerts.
  • prompts/hourly-quick-repair.md — main quick scheduled prompt.
  • prompts/six-hour-deep-check.md — deep scheduled prompt.
  • prompts/update-maintenance.md — update prompt.
  • templates/claude-settings.conservative.example.json — stricter permission template.
  • templates/claude-settings.autonomous-devops.example.json — more autonomous template after the operator explicitly approves it.
  • templates/desktop-scheduled-task-skill.example.md — optional Claude Code Desktop scheduled task SKILL.md wrapper.
  • templates/stale-check.sh — restarts a gateway that runs older code or settings than are on disk.

Support this project

This watchdog is free and MIT licensed, and it stays that way.

There is also an extended build, the Hermes DevOps Kit, free on Ko-fi. It takes this watchdog and sets up the rest of the server around it. You get an installer, a security baseline, backup and cost checks, safe upgrades, incident playbooks and remote control from your phone. It also sets up the Chrome Agent Bridge, so your agent can use a real, logged-in browser on your own computer.

Get the Hermes DevOps Kit free on Ko-fi

If it saved you time and you want to support the work, you can buy me a coffee there too. Either way, thanks for using the watchdog.

Related projects

Safety principle

Claude Code may repair Hermes within narrowly scoped boundaries, but it must not silently perform destructive, security-sensitive, or broad system changes. Restarting an installed Hermes gateway service can be safe after evidence and verification. Deleting unknown files, rotating secrets, changing firewall/SSH, changing provider credentials, and major updates are not.

Ver o original no GitHub

Bom para

Relacionados