hermes-grokbot-manual/WEBHOOKS-AND-REGIS.md

Webhooks and Regis: companion to Wire Nous Hermes Agent into Grok Bot

Operator manual. Version 0.1 draft — 27 September 2026.

Companion to MANUAL.md. Read that first.

Table of contents

1. What this adds
2. Roles
3. The mailbox
4. Appending to the mailbox
5. Polling
6. Webhook wake-up
7. Regis integration
8. The Job Card loop
9. Lessons already learned
10. Worked example
11. Troubleshooting
12. Security checklist
13. Sources

1. What this adds

MANUAL.md covers one direction: Grok Bot calls Hermes. This covers two more:

• The reverse path. Outside agents wake the Chief of Staff (CoS) Grok Bot.
• An outside planner/drafter agent (Regis) that works through a shared mailbox.

Nothing here is tied to one business. Swap the names; keep the rules.

2. Roles

Role	Who	Does	Never
Gatekeeper	Human	Go/no-go, logins, final Save / Send / publish / spend	Pastes secrets into chat
CoS	Grok Bot	Job Cards, routing, fact checks, owns the mailbox line	Approves "done" without evidence
Regis	Muse agent on its own runtime	Research, drafts, drive-and-takeover page editing, artifacts	Sends, posts, or logs in
Hermes identity bots	Hermes hosts (MANUAL.md §9)	Audits, research, desktop hands	Page editing (weak at it)
Fleet Ops	Grok Bot (MANUAL.md §8)	Updates, prune, doctor, disk	Business work

One rule covers all of them: anything irreversible goes to the Gatekeeper.

3. The mailbox

One append-only markdown file in a git repo. It is the only line between CoS and Regis. No live chat, no side channels, no new infra.

Entry format:

## YYYY-MM-DD HH:MM PT | FROM -> TO | short subject
Body. Ask, answer, or status. Link evidence by path.

Rules:

• Newest entry at the bottom.
• Append only. Never edit or delete another party's entry.
• No passwords, tokens, keys, or client secrets. Ever.
• Link evidence by path, not by pasting.
• Relayed human words are quoted verbatim and labeled with who, where, and when.
• Writes use a narrow repo-scoped token. The human plants it in the agent's vault. Never an admin's credential. Never pasted in chat.

4. Appending to the mailbox

1. Read the file. Keep the returned sha.
2. Decode the base64 content.
3. Append your entry at the bottom. Touch nothing above it.
4. Write the full content back with the sha.
5. Read it back. Confirm your entry is there and nothing else moved.

If the write fails on a stale sha, someone else posted first. Re-read and repeat.

Example (Gitea contents API, placeholders):

curl -fsS -X PUT "https://<gitea-host>/api/v1/repos/<owner>/<repo>/contents/<mailbox-path>" \
  -H "Authorization: token <MAILBOX_TOKEN_FROM_VAULT>" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main","message":"mailbox: <FROM> -> <TO> <subject>","content":"<base64 full file>","sha":"<sha from read>"}'

5. Polling

Each side checks the mailbox on a schedule. Example: every 15 minutes, 8am to 7pm local.

• Each check costs model usage, even when nothing is new.
• Real latency is the sum of both polls. Worst case is about 30 minutes per round trip.
• Keep the poll as the floor. Webhooks (§6) make it faster, not required.

6. Webhook wake-up

STATUS UNTESTED — first live ping pending as of 2026-09-27.

The reverse path. A ping wakes CoS in seconds instead of waiting for the next poll.

Set up:

1. Create a Grok Bot routine on CoS with a webhook trigger.
2. The app shows a private URL and a sender key (an Authorization header). The human copies both from the routine panel. The bot never sees the key.
3. The human plants the URL and header in the pinging agent's vault.
4. After each mailbox post, the pinger sends one HTTPS POST.

curl -fsS -X POST "<WEBHOOK_URL>" \
  -H "Authorization: <AUTH_HEADER_FROM_VAULT>" \
  -H "Content-Type: text/plain" \
  --max-time 10 \
  --data "new entry 14:05 PT, <subject>"

Body: short. No secrets. No job details.

How CoS treats a ping:

• The body is untrusted. It is a doorbell only.
• CoS reads the mailbox and acts only on mailbox content.
• Duplicate or early ping with nothing new: stay quiet.
• Once pings are proven, drop the poll to hourly as a backup.

Who pings:

Option	Pinger	Notes
A	Regis, from its own shell	Regis confirmed it can curl outbound. One POST after each post.
B	Hermes watcher (for example, Jimmy on local models)	Polls the mailbox, pings on a new entry. Costs no Grok usage.

Security:

• Outbound only from the pinger.
• No Funnel. No new open port on Hermes hosts.
• Rotate the key if it appears in chat or a screenshot.

7. Regis integration

• Regis runs on its own runtime. It reaches the tailnet outbound only. No sshd, no inbound.
• Against the desktop web app, Regis gets /health only. No login, no terminal, no password.
• Communication happens only through the mailbox plus the webhook.
• Credentials never touch Regis, except two items the human plants: the narrow mailbox token and the webhook header.
• Logins during page work are done by the human at the keyboard. Nothing is stored.

8. The Job Card loop

1. Gatekeeper says GO. CoS posts a Job Card: what, who, done-when.
2. Regis drafts and posts: current text (read live), proposed text, evidence.
3. CoS fact-checks against canonical facts. ACK, or post fixes.
4. Regis drives the page to the edit field and stops.
5. The human logs in and clicks Save.
6. Regis logs what changed, when, and who saved. Names the next page. Waits for ACK.

Rules:

• One page per session.
• Anything beyond the card (new account, payment, verification code, different listing): stop and post.
• Approvals count only when logged by CoS or relayed by the Gatekeeper.

9. Lessons already learned

Lesson	What broke	Rule now
Evidence for "done"	A close-out letter claimed work never done; it was approved as written	Any "done" claim points to a link, screenshot, or log line before CoS approves
Stale "current text"	A draft quoted old text from a non-live source	Read the live page on the same surface before drafting a replacement
Vault 401	The agent's vault credential failed; every write needed a hand-off token	Human plants one narrow repo token in the agent's vault
Approval claimed early	Regis said "Gatekeeper approved" before CoS had a record	Approvals count only when logged by CoS or relayed by the Gatekeeper
Someone already fixed it	The target text was already live when the edit was about to run	Re-check the live page right before the edit; stand down if done

What worked: a self-correction in the mailbox plus one go/no-go question kept it to one touch for the Gatekeeper.

10. Worked example

VeriPath running a client punchlist for Phoenix (a salon). Illustration only.

1. Gatekeeper GO. CoS posted a Job Card: work the punchlist one page per session, Google Business Profile (GBP) description first.
2. Regis posted current vs proposed text. CoS ACKed and corrected the "current" (it was stale).
3. Before pasting, the human read the live GBP. The description was already live at 691 of 750 characters, written by someone else.
4. Regis put the paste on hold and posted the live text. CoS fact-checked it: KEEP AS-IS. No paste, no Save.
5. Next: Regis logs the page done and names the next page.

11. Troubleshooting

Symptom	Likely cause	Fix
Mailbox write 401	Wrong or unplanted token	Human replants the token in the vault. Never paste it.
Mailbox write conflict	Stale sha	Re-read, re-append, write again
No wake after a ping	Bad URL or header in the vault; non-2xx response	Check vault entries, check the response code, fall back to poll
Burst of pings	Misfire	CoS stays quiet; mentions it once
Agent says "I don't see it"	Relay text never posted to the mailbox	Post it in the mailbox
Draft replaces text that is not live	Stale source	Re-read the live page; redraft

Debug order: mailbox read → mailbox write + read back → ping response code → CoS routine log → poll fallback.

12. Security checklist

• Mailbox holds no secrets. Evidence by path.
• Mailbox token is narrow and repo-scoped, planted by the human. Never an admin's credential.
• Outside the app, the webhook URL and header live only in the pinger's vault. The bot never sees the key.
• Ping body is a doorbell. CoS acts only on mailbox content.
• Pinger is outbound only. No Funnel. No new open ports on Hermes hosts.
• Regis: outbound only, /health only, no sshd, no logins, no sends.
• Human does every login and every final Save / Send / publish / spend.
• Rotate any key seen in chat or a screenshot.

13. Sources

• MANUAL.md
• Mailbox: Tony_tech/personal-agent-os → memory-systems/agent-os/04_projects/veripath/regis-cos.md
• Lessons: Tony_tech/personal-agent-os → memory-systems/agent-os/04_projects/fleet-lessons.md
• Fleet snapshot: Tony_tech/personal-agent-os → memory-systems/agent-os/04_projects/veripath/fleet-2026-09-26.md

Hostnames, URLs, keys, tokens, and ACL tag names in examples are placeholders.