hermes-bsd

FreeBSD-native build, packaging, and service layer for Hermes Agent, maintained by Clawdie at the canonical Forgejo instance:

https://code.clawdie.si/clawdie/hermes-bsd
ssh://git@code.clawdie.si:2222/clawdie/hermes-bsd.git   (SSH port 2222)

This repository is a downstream fork. Upstream (NousResearch/hermes-agent) moves fast; our own delta is a small, well-defined FreeBSD layer that gets replanted onto each fresh upstream tip. See SYNCING-UPSTREAM.md for the sync procedure and CLAWDIE-PLAN.md for the operating plan and its status.

Operator

The operator is the human maintainer. Agents report status, blockers, and verification results to the operator.

operator:  Samo
email:     hello@clawdie.si   (operator-only; never used for agent commits)

Agent identities

Each coding agent has one Forgejo account, one commit identity, and its own SSH keys (one per host). Agent commit emails are identity aliases, not mailboxes.

Agent	Forgejo account	Commit identity	Notes
Hermes	agent-hermes	agent-hermes <agent-hermes@clawdie.si>	orchestrator (debby)
Zot	agent-zot	agent-zot <agent-zot@clawdie.si>	coding agent (debby)
Pi	agent-pi	agent-pi <agent-pi@clawdie.si>	coding agent (valhala)
Codex	agent-codex	agent-codex <agent-codex@clawdie.si>	coding agent (osa/valhala)
Gemini	agent-gemini	agent-gemini <agent-gemini@clawdie.si>	runtime: agy (Antigravity CLI), formerly Gemini CLI

Telegram is a control-plane channel (operator commands such as future /rebuild), not a coding agent. It gets no Forgejo account and no push access; it dispatches approved, SHA-pinned workflows through the Forgejo API only.

Commit identity policy

Each agent checkout is configured once, repository-locally:

git config --local user.name  "agent-hermes"          # your agent name
git config --local user.email "agent-hermes@clawdie.si"

Before committing, confirm the identity that will sign the work:

git config --local --get-regexp '^user\.'

Commits use the checkout identity. Passing an unrelated identity through GIT_AUTHOR_* / GIT_COMMITTER_* environment overrides belongs to migration tooling only, never to normal work.

Branch workflow

feature branch  ->  push  ->  pull request  ->  operator review  ->  merge

• main carries the upstream history plus the FreeBSD layer; it changes via reviewed pull requests.
• Agents push feature branches only (feat/..., fix/..., docs/...).
• The operator reviews and merges.
• Verification before reporting: relevant tests, git status -sb clean of unstaged work, remote SHA equals local HEAD after push.

Platform boundary

The FreeBSD layer is a small set of files (verified 2026-09-23 by diffing this fork against its upstream merge point):

packaging/freebsd/hermes_daemon.in      rc.d gateway service (daemon(8))
packaging/freebsd/hermes_dashboard.in   rc.d dashboard service
packaging/freebsd/colibri_bridge.in     rc.d Colibri bridge
scripts/install-freebsd.sh              native installer (POSIX sh, pkg, uv)
hermes_cli/uninstall.py                 /usr/local/bin path handling
.github/workflows/ci.yml                CI adapted for Forgejo
README-FreeBSD.md                       service layouts + enable steps
SYNCING-UPSTREAM.md                     sync runbook
skills/github/hermes-bsd-upstream-sync/ sync skill

Runtime behavior differences that the layer exists for:

Aspect	Linux (debby)	FreeBSD (osa / valhala)
Enable service	systemctl enable	sysrc <svc>_enable=YES
Run service	systemd / s6-overlay	rc.d + daemon(8)
Packages	apt	pkg
Binary paths	~/.local/bin	/usr/local/bin
Gateway persist	systemd user service	rc.d service / tmux session
venv	full	stripped; ensurepip bootstrap

Everything else is upstream code and refreshes with each sync. The full verified delta and open platform items are listed in CLAWDIE-PLAN.md.

SSH keys and secrets

• One SSH authentication key per agent, per host (e.g. agent-hermes-debby, agent-pi-valhala), registered in the matching Forgejo account.
• Private keys and passphrases are stored in Vaultwarden, organization clawdie:
  • agent-secrets — agent account metadata and API credentials
  • deploy — SSH key material
  • bootstrap — operator-only recovery material
• Compromise of one host key is resolved by revoking that key only.
• The Telegram bot token, when the control plane is added, lives in agent-secrets and is scoped to workflow dispatch.

Verification checklist

Before declaring work complete:

1. git config --local --get-regexp '^user\.' — expected agent identity.
2. Relevant tests pass on the touched area.
3. git status -sb — committed and pushed; ahead 0.
4. git ls-remote origin <branch> — remote SHA equals local HEAD.
5. Pull request opened; report to the operator with commit, branch, and verification evidence.

Further reading

• README-FreeBSD.md — FreeBSD install and service layouts for operators.
• SYNCING-UPSTREAM.md — how to replant the FreeBSD layer onto a new upstream tip.
• CLAWDIE-PLAN.md — operating plan, migration status, identity/key model.
• AGENTS.md — contribution rules for agents (Clawdie section first, then the upstream development guide).
• Upstream: NousResearch/hermes-agent