Tony_tech/hermes-grokbot-manual
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
hermes-grokbot-manual/FLEET-MANUAL.md
T

7.8 KiB
Raw Permalink Blame History

Fleet Manual

Operator contract. Version 3.0 — 27 September 2026.

Changelog: v3.0 locks the fleet to jobs, not chat. The shared diary mailbox is retired as a bus. Wiring (Tailscale, SSH relay, :8642) is infra, not the operating model.

This file is the source of truth. MANUAL.md is historical.

1. What this is

Grok Bot is the front door you talk to. Hermes is the worker on your machine. Regis is an outside drafter. You are the Gatekeeper.

Agents do not chat. They pass jobs. A job has one owner, one state, one live surface, and an evidence slot. Anything irreversible is you.

2. Locked shape

You  →  CoS                 GO / no-go / "saved" / "stand down"
CoS  →  worker              open a job (what, who, done-when, live URL)
worker → CoS                event file: proposal | block | outcome
CoS  →  job file            the only rewrite: flip state
watcher → CoS routine       doorbell POST when a new event file appears

Illegal:

  • Regis talking to Hermes
  • Hermes talking to Regis
  • A third agent joining a job without CoS opening a second job
  • CURRENT text without a live URL and a live_read_at
  • "Done" without an evidence path
  • Secrets in git, chat, jobs, or events

3. Roles

Role Who Does Never
Gatekeeper Human GO, login, Save / Send / publish / spend, plant vault secrets Pastes secrets into chat
CoS One Grok Bot Opens jobs, fact-checks, owns state, wakes on doorbell Approves done without evidence; chats with workers
Worker (Regis) Outside runtime Reads live surface, drafts, drive-and-stop at login Send, post, login, Save, talk to Hermes
Worker (Hermes) Host agent Audit, research, desktop hands, evidence packs Page editing as the primary path; talk to Regis
Watcher Script or local Hermes cron Detects new event files, POSTs doorbell Calls a model to see if a file grew
Fleet Ops Optional later Host doctor / disk / updates Exists before a second host has been up 14 days

One human conversation: you talk to CoS. CoS does not freelance package upgrades.

4. The record

Repo: Tony_tech/personal-agent-os

memory-systems/agent-os/04_projects/<project>/jobs/
  JOB-<YYYYMMDD>-<slug>.md          # CoS owns this file
  events/JOB-<YYYYMMDD>-<slug>/
    001-<from>-<type>.md            # anyone may add; nobody edits

Old shared logs (regis-cos.md and any append-only diary) are archives. Do not append work to them.

Job file (CoS only)

---
id: JOB-YYYYMMDD-slug
project: <project>
surface: <one page or one artifact>
state: open
owner: regis
gate: human-login
live_url:
live_read_at:
current_hash:
proposed_hash:
evidence: []
blocker: null
---

# JOB-YYYYMMDD-slug

what:
who:
done-when:

state values, in order:

open → proposed → acked → ready_to_save → saved

Side exits: blocked | stand_down

Only CoS writes this file. A worker that rewrites state is out of contract.

Event file (workers and CoS)

---
job: JOB-YYYYMMDD-slug
from: regis
to: cos
type: proposal
at: 2026-09-27T10:50:00-07:00
live_url:
live_read_at:
---

type is one of: proposal | ack | reject | block | outcome | gatekeeper.

proposal without live_url and live_read_at is invalid. CoS rejects it and does not discuss it.

Body holds CURRENT (from that URL at that time), PROPOSED, and evidence paths. No secrets. Relayed human words are quoted verbatim and labeled who / where / when.

5. Job loop

  1. Gatekeeper says GO.
  2. CoS creates the job file. state: open. Live URL required before any draft.
  3. Worker reads that URL now. Writes NNN-<from>-proposal.md. If the live surface cannot be read, writes block instead of inventing CURRENT.
  4. Watcher sees the new file and doorbells CoS.
  5. CoS fact-checks against the project's canonical facts. Writes ack or reject event. Flips job state to acked or blocked.
  6. Worker drives to the field and stops at login.
  7. Gatekeeper logs in. Worker pastes only the ACK'd text. Stops before Save.
  8. Gatekeeper clicks Save and tells CoS. CoS writes outcome, sets saved, attaches evidence.
  9. CoS opens the next job. One surface per job.

Approvals count only as a CoS ack/outcome event or a gatekeeper event quoting you.

6. Wake path

Do not pay a model to see if a file grew.

Primary: watcher lists jobs/events/** (mtime or git log --since). On a new file, one HTTPS POST to the CoS routine.

curl -fsS -X POST "<WEBHOOK_URL>" \
  -H "Authorization: <AUTH_HEADER_FROM_VAULT>" \
  -H "Content-Type: text/plain" \
  --max-time 10 \
  --data "JOB-id type=proposal"

Body is a doorbell. No secrets. No draft text. CoS acts only on job + event files. Duplicate ping with nothing new: stay quiet.

Backup until the doorbell has fired clean twice: hourly hash check, not a 15-minute model poll.

Pinger is outbound only. No Funnel. No new open port on Hermes hosts. Human plants URL and header in the pinger vault. The bot never sees the key.

STATUS: doorbell planted but not proven as of 2026-09-27. Keep the hourly backup until two clean wakes are logged as outcome events on any job.

7. Hermes wiring (infra only)

Need Hermes from CoS? Use what already works on the host.

  • Desktop-primary, no gateway: SSH relay MCP (ask, health).
  • Gateway up: HTTP http://<tailscale-host>:8642/v1, bind the Tailscale IP, never 0.0.0.0.
  • Tailscale only. No Funnel.
  • Grok may read Hermes memory plugins. Grok may not write them.
  • Account-scoped MCP is visible to every bot on the account. Treat every identity bot as able to see every connector. Do not pretend a prompt is isolation.
  • Do not add Fleet Ops or a second-host identity bot until a second host has been up 14 days.

Relay details and marketplace template URLs live in MANUAL.md if you need to rebuild a box. They are not the fleet.

8. Secrets

  • Vault holds API_SERVER_KEY, mailbox/job-repo token, webhook header, SSH keys.
  • Job-repo token: narrow, repo-scoped, planted by the human. Never an admin credential. Never pasted in chat.
  • Nothing secret in jobs, events, or this manual.
  • Rotate anything that appeared in a screenshot or a thread.

9. Cadence

  • You talk to CoS when there is work or a Save.
  • Watcher runs continuously or every few minutes. It does not use Grok.
  • CoS runs when you speak or when a doorbell arrives.
  • Workers run only on an open job.
  • Weekly: one secrets check, one "any job stuck in blocked?" pass.

10. Hard rules

  • One surface per job.
  • Live read on the same surface before CURRENT.
  • Evidence path before saved.
  • Re-read live immediately before paste; stand_down if it is already done.
  • Anything beyond the card (new account, payment, verification code, different listing): block.
  • Jobs are not memory. Do not copy them into Hermes memory by default.
  • Long goals go to a Hermes kanban or a project file, not a Grok thread.

11. Troubleshooting

Symptom Cause Fix
Two agents fighting a SHA Still writing one diary Use a new event file
Stale CURRENT Drafted from memory or another URL Reject; demand live_url + live_read_at
"Done" with no proof Prose status Leave state where it is
No wake Webhook unplanted or non-2xx Check vault, fall back to hourly hash
Agent "doesn't see it" Said in chat, not an event file Post the event
Other bots calling a host Account-scoped MCP Assume shared; don't put irreversible tools on it
tailscale ping to Regis fails Outbound-only by design Not a fault

12. Sources

Hostnames, URLs, keys, and ACL tags in any leftover examples are placeholders.

Reference in New Issue View Git Blame Copy Permalink