clawdie/layered-soul
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(host-matrix): add FreeBSD prereqs & first-run checklist for hermes-osa

Browse source 
Fold blind spots P2-P5 into the install note: pkg-install prereqs first
(bash/uv/git/curl), bash required (shebang now portable via hermes-bsd PR #3),
run attended (interactive prompts), core-only first validation (native-build
extras may not compile on FreeBSD 15), and rc.d as a deliberate re-setup
(/var/db/hermes, hermes user) — validation state won't migrate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude (domedog) 2026-06-17 18:59:25 +02:00
parent f8c2dcf4e0
commit 4bff0eabbf
1 changed files with 22 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
docs/HOST-MATRIX.md
View file

@ -136,6 +136,28 @@ retired). Grounded in the actual code:
runtime path as a separate step after local Hermes validation.
- Install source is `hermes-bsd` main at `912e697d` (includes the Python 3.12 setup baseline).
**FreeBSD prereqs & first-run checklist** (verified blind spots before committing):
1. **Install prereqs via pkg first.** `setup-hermes.sh` only auto-provisions on
Linux/Termux/macOS; on FreeBSD it falls through to manual-instruction messages. Run:
`pkg install -y bash uv git curl`. Prefer pkg `uv` over the script's astral
`curl | sh` fallback (unreliable on FreeBSD).
2. **`bash` must be installed.** The script is bash. Its shebang is now portable
`#!/usr/bin/env bash` (hermes-bsd PR #3, `fix(freebsd): portable bash shebang`), so it
resolves FreeBSD's `/usr/local/bin/bash` — but bash itself must be present (step 1).
Until PR #3 is merged on the checkout, invoke as `bash setup-hermes.sh`.
3. **Run attended.** The script prompts (optional packages, setup wizard). Do **not** run
it unattended/agent-driven — it will hang on the `read` prompts.
4. **Core-only for first validation.** Decline optional extras initially. Several
(`matrix`→libolm, `voice`/`tts`→audio) are native builds that may not compile on
FreeBSD 15; the installer degrades rather than hard-failing, but a minimal install
gives a clean CLI proof. Add extras deliberately later.
5. **The rc.d service step is a separate re-setup, not a flip.** `setup-hermes.sh`
symlinks the `hermes` binary into `~/.local/bin` for the invoking user, but
`hermes_daemon` expects it at `/usr/local/bin/hermes` under a dedicated `hermes` user
with state at `/var/db/hermes`. Validation state at `/home/clawdie/.hermes` will **not**
migrate — re-run setup as the service user when promoting to rc.d.
---
_See [`../AGENTS.md`](../AGENTS.md) for the canonical agent matrix and operating rules._