hermes-bsd/README-FreeBSD.md

Hermes Agent — FreeBSD

This is a clean-room FreeBSD compatibility layer for Hermes Agent, built from the MIT-licensed upstream. No LGPL code, no Autolycus dependency.

Role in the Clawdie collective: hermes-bsd is the agent harness — the layer you talk to (CLI, Telegram, skills, memory, cron). Colibri is the control plane — the layer that supervises agents, runs the task board, and tracks cost. They connect via Colibri's glasspane observation and MCP bridge; they do not duplicate each other.

What's patched

Three targeted changes for FreeBSD native support:

File	Change
hermes_cli/setup.py	FreeBSD in platform detection, pkg for espeak-ng, rc.d service support
hermes_cli/uninstall.py	/usr/local/bin symlink removal on FreeBSD
scripts/install-freebsd.sh	Native FreeBSD installer (POSIX sh, pkg, uv)

Clipboard (xclip) and voice (ffplay) work on FreeBSD without code changes — xclip and ffmpeg are available via pkg.

Service (rc.d)

After installing, run Hermes as a persistent system service under daemon(8). There are two supported layouts:

Dedicated service user

Use this on a fresh host where Hermes owns its own account and state root:

# One-time setup
sudo pw groupadd hermes
sudo pw useradd hermes -g hermes -d /var/db/hermes -s /usr/sbin/nologin
sudo cp packaging/freebsd/hermes_daemon.in /usr/local/etc/rc.d/hermes_daemon
sudo chmod 555 /usr/local/etc/rc.d/hermes_daemon

# Configure Hermes before first start
sudo mkdir -p /var/db/hermes
sudo chown hermes:hermes /var/db/hermes
sudo -u hermes HERMES_HOME=/var/db/hermes hermes setup
sudo -u hermes HERMES_HOME=/var/db/hermes hermes model

# Enable and start
sudo sysrc hermes_daemon_enable=YES
sudo service hermes_daemon start
sudo service hermes_daemon status

This lane uses /var/db/hermes as persistent state and keeps the service user non-interactive with /usr/sbin/nologin.

Existing operator user

Use this when Hermes is intentionally running as an existing operator account such as clawdie and the authoritative state home is already under that user:

sudo cp packaging/freebsd/hermes_daemon.in /usr/local/etc/rc.d/hermes_daemon
sudo chmod 555 /usr/local/etc/rc.d/hermes_daemon

# Reuse the existing operator-owned Hermes home
sudo install -d -o clawdie -g clawdie -m 0750 /home/clawdie/.hermes
sudo sysrc hermes_daemon_enable=YES
sudo sysrc hermes_daemon_user=clawdie
sudo sysrc hermes_daemon_group=clawdie
sudo sysrc hermes_daemon_home=/home/clawdie/.hermes

# Hermes must already be configured in that home
sudo -u clawdie HERMES_HOME=/home/clawdie/.hermes hermes status

sudo service hermes_daemon start
sudo service hermes_daemon status

In this lane, keep the runtime state in the operator's existing HERMES_HOME without creating a separate hermes account. The account's shell stays whatever the operator already uses; the rc.d service launches hermes gateway run via daemon -u, not via an interactive login shell.

The service logs to /var/log/hermes/gateway.log. Runtime pidfiles live under /var/run/hermes.

Install

sh scripts/install-freebsd.sh

License

MIT — same as upstream NousResearch Hermes Agent. No LGPL encumbrance.