Architecture
Five hops. Two are yours to build.
GitHub Actions
A run fails on
acme/reportd. GitHub sends the webhook, a JSON payload signed with your secret as X-Hub-Signature-256. It has no job logs.↓ HTTPS POST across the public internet
A server GitHub can reach you build this
Hermes listens on
http://your-server:8644/webhooks/ci-heal. A small VPS is the dull, reliable choice, and a tunnel from a homelab box also works. Put TLS in front.↓
Hermes gateway: webhook platform
Configured under
platforms.webhook.extra: port 8644, HMAC secret, rate_limit (default 30 a minute) and max_body_bytes. Bad signatures are dropped before any model runs. GitLab tokens and generic schemes are supported too.↓
Route:
ci-heal
It has
events it accepts, filters (the one that skips the agent’s own ci-heal/* branches stops loops), an optional script hook, a prompt template filled from payload fields, and deliver targets. The template is on the prompts page.↓ rendered prompt starts an agent run
Hermes agent run → terminal tool → Docker backend
Hermes has six terminal backends (
local, docker, ssh, singularity, modal, daytona). This plan uses docker: all capabilities dropped, no-new-privileges, 256-process limit, 512 MB tmpfs /tmp. The route prompt prompt glue has the agent run gh run view --log-failed, clone, check out, reproduce, patch and re-test. You build the image with git, gh and your toolchain you build this. Every command goes through approvals: approvals.mode (smart | manual | off), approvals.deny globs, and a hardline blocklist even --yolo can’t switch off.↓ only if the suite passes
The PR
gh pr create from a new ci-heal/* branch, with diagnosis, diff and sandbox test output in the body. Never merged.The report
Route
deliver targets: github_comment on the failed run, telegram or discord.Where state lives
~/.hermes/config.yaml: gateway, webhook platform, routes, terminal backend, approvals.~/.hermes/.env: the webhook secret and your model and GitHub tokens. Never in config.yaml or the repo.- The sandbox is disposable. Nothing survives outside the PR branch, and the design depends on that.
Two ways it goes blind
- If
ghis missing from the image or the token lacks scope, the agent diagnoses blind (traps). - If GitHub can’t reach you, nothing fires. Sort out reachability first (setup, stage 2).