# Hermes Agent — FreeBSD

This is a clean-room FreeBSD compatibility layer for [Hermes Agent](https://github.com/NousResearch/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:

```sh
# 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:

```sh
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
sh scripts/install-freebsd.sh
```

## License

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