homelabstack/docs/superpowers/specs/2026-06-27-hermes-ecosystem-integration-design.md

# Hermes Ecosystem Integration — Triage & Design

**Date:** 2026-06-27
**Author:** Claude (overnight autonomous research for ginnoir; for morning review)
**Status:** Draft — awaiting ginnoir's decisions on the flagged items below

---

## 0. TL;DR for the morning

You asked me to research seven Hermes-ecosystem repos and plan how each fits. I verified all
seven are real and active, mapped each against your **actual** Hermes deployment (host systemd
install on valhalla, llama-swap/P100 backend, ~29-tool curated MCP surface, Codex + Claude Code
also installed), and triaged them into adopt / trial / decide / skip.

**Recommended path:**

| Phase | Repo | Verdict | Why |
|---|---|---|---|
| **1** | `hermes-agent-acp-skill` | **ADOPT** | Pure skill drop-in; lets the local 20B offload hard work to Codex/Claude Code, which you already run. Highest leverage, lowest risk. |
| **1** | `hermes-curator-evolver` | **ADOPT (dry-run first)** | Closes Hermes' self-improvement loop; read-only by default; aligns with your curation habit. |
| **2** | `camofox-browser` | **ADOPT (new homelab stack)** | Gives the local agent real web browsing; clean Docker/Caddy fit; independent of Hermes internals. |
| **2** | `eagle-eye` | **TRIAL / DEFER** | Solves the exact tool-overload pain you already hit — but very early (5★, 1 commit) and carries a required Chinese-tokenizer dep. Trial behind a flag; don't depend on it. |
| **3** | `hermes-ui` | **TRIAL (low-cost UI upgrade)** | Single-HTML + stdlib proxy; trivial to stand up next to the bundled webui. |
| **3** | `hermes-workspace` | **DECISION** | The full "command center," but a real React build + a swarm model your single P100 can't actually parallelize. |
| **3** | `mission-control` | **SKIP / DEFER** | Not Hermes-native (built for OpenClaw/CrewAI/LangGraph/AutoGen). Redundant with the two Hermes UIs unless you want a framework-agnostic ops plane. |

**Decisions I need from you (Section 6):** (1) which UI, if any; (2) whether curator-evolver may
ever run in `--approve` mode or stays report-only; (3) whether to trial eagle-eye at all given its
maturity/dependency profile.

---

## 1. The anchor: your current Hermes deployment

Everything below is sized against what you actually run (from project memory, verified against the
repo and host conventions):

- **Hermes Agent v0.17.0 (NousResearch)** runs on the **valhalla host**, not in Docker — systemd
  units `hermes-gateway.service`, `hermes-dashboard.service`, `hermes-webui.service`. Editable
  install at `~/.hermes/hermes-agent/`; config at `~/.hermes/config.yaml`; CLI `~/.local/bin/hermes`.
  Workspace at `/storage1/hermes/workspace/`.
- **Backend:** llama-swap (`stacks/llm`, Portainer id 34) on a single **Tesla P100 16GB**, serving
  one GGUF at a time, `--parallel 1`, 64k ctx, default `gpt-oss-20b`. OpenAI API at
  `http://172.20.0.1:8090/v1`.
- **MCP surface deliberately curated to ~29 tools** because gpt-oss-20b drowns in tool overload.
  This is the single most important constraint for everything below: **the local model is weak at
  selection under load, and the GPU runs one model, one sequence at a time.**
- **You also run Codex (`~/.codex`) and Claude Code**, kept in sync with your Claude global config.
  This is what makes the ACP delegation skill genuinely useful rather than theoretical.

### 1.1 Two integration classes (this drives the whole plan)

- **Class A — host-side Hermes extensions** (plugins & skills): live in `~/.hermes/` on valhalla,
  applied by SSH + `hermes ...` + gateway restart. **These are NOT homelabstack repo content.**
  They are host-managed exactly like the rustdesk/obsidian/xvfb units — tracked in project memory
  and the Obsidian vault, not committed here. Fully reversible (config backups + plugin uninstall).
  → `hermes-agent-acp-skill`, `hermes-curator-evolver`, `eagle-eye`.
- **Class B — Docker services**: become `stacks/<name>/` entries, deployed via the normal
  Gitea-poll path, fronted by Caddy (`internal_only` + Authentik), secrets in `stack.env`,
  infra images pinned out of Watchtower.
  → `camofox-browser`, and (if adopted) `hermes-ui` / `hermes-workspace` / `mission-control`.

---

## 2. Per-repo analysis

### 2.1 `hermes-agent-acp-skill` (Rainhoole) — **ADOPT, Phase 1**

- **What:** A Hermes *skill* (`SKILL.md` + `README.md`, MIT) implementing `delegate_task()` —
  multi-agent delegation across Hermes internal subagents, **Codex**, and **Claude Code**. Handles
  agent routing (`agent=...`), context isolation, and safety controls (recommended 900 s external
  timeout, 24,000-char output cap).
- **Fit:** Strong and specific. Your local model is gpt-oss-20b — fine for orchestration and light
  tasks, weak for real implementation/review. This skill lets Hermes *route the hard parts to the
  frontier CLIs you already have installed and configured*. It turns the weak local brain into a
  dispatcher.
- **Risk:** Low. It's a skill file, not running code you didn't write — but it *invokes external
  agents*, so the real work is verifying Codex/Claude Code are launchable from the Hermes service
  environment (PATH, auth, non-interactive flags) and that timeouts/output caps are sane.
- **Implementation sketch:** Drop into `~/.hermes` skills dir (or `hermes skills install` if the
  repo packages it that way — verify on the host); set delegation targets to the Codex + Claude
  Code invocations; restart gateway; smoke-test a trivial delegated task end-to-end.

### 2.2 `hermes-curator-evolver` (pingchesu) — **ADOPT, dry-run first, Phase 1**

- **What:** Local-first Hermes *plugin* (Python 3.11, SQLite, `hermes plugins install`). Mines
  evidence from sessions/tool-calls, ranks skill-improvement candidates, and generates **dry-run,
  reviewable** proposals. **Read-only by default; mutations require explicit `--approve`.** Only
  touches *local agent-created* skills — skips bundled, hub-installed, and external skills. Size
  guardrails, backup/rollback manifests, optional Qwen-embeddings + BGE-reranker for semantic
  ranking, native scheduler (systemd) integration.
- **Fit:** This *is* Hermes' "self-improving" thesis made operational, and it matches how you
  already work (curate, gate, keep things reversible). The default posture (report-only, dry-run,
  human-review queue) is exactly the safe on-ramp.
- **Risk / caveats:**
  - It writes to skills with `--approve`. **Recommendation: run report-only / dry-run indefinitely
    at first**; promote to `--approve` only after you've seen a few proposal batches you'd have
    accepted anyway.
  - Optional embeddings/reranker want a model. **Do not load them onto the P100** alongside
    gpt-oss — the GPU is single-model/`--parallel 1`. Run ranking on **CPU**, or skip the dense
    layer initially (BM25/FTS ranking is enough to start).
  - Schedule the mining pass **off-peak** via a systemd timer so it never contends with live
    inference.
- **Implementation sketch:** `hermes plugins install` on the host; point it at the session store;
  run one manual `collect`→`rank`→`report` cycle by hand; inspect the review queue; only then wire
  a nightly systemd timer in report-only mode.

### 2.3 `eagle-eye` (willingning-coder) — **TRIAL / DEFER, Phase 2**

- **What:** Zero-invasive skill *pre-filter* plugin. Before the LLM call, narrows 50+ skills to the
  top ~5 via a 5-layer cascade (hard triggers → FTS5/BM25 → synonyms → dense embeddings → RRF
  fusion), degrading gracefully when optional deps are absent. "Not matching is a valid result."
- **Fit (conceptual):** Excellent — this is the **skill-side analog of the MCP tool-overload fix
  you already did**. Fewer, better skill candidates in the prompt = better selection by a weak
  model + less Pascal prefill. If it works, it directly improves gpt-oss-20b's behavior.
- **Risk / caveats (why it's a trial, not an adopt):**
  - **Maturity:** 5 stars, single commit. Early. Treat as experimental.
  - **Dependency smell:** `jieba` (Chinese tokenization) is a *required* dep; your skill library is
    English. Works, but signals the author's primary use case differs from yours — watch for
    English-tokenization edge cases and maintenance drift.
  - Same P100 rule: keep its dense-embedding layer on **CPU** or disabled; lean on L1–L2
    (deterministic + BM25) first.
- **Implementation sketch:** Install behind an easy on/off switch on the host; A/B a handful of
  representative prompts with it on vs off; keep it **only if** measured skill-selection quality
  improves. Do not let any workflow depend on it.

### 2.4 `camofox-browser` (jo-inc) — **ADOPT as a homelab stack, Phase 2**

- **What:** Stealth headless browser (Camoufox/Firefox) exposing a **REST API for AI agents** —
  anti-fingerprinting, element-reference interaction (`e1`,`e2`), session isolation, proxy/GeoIP,
  YouTube transcripts, Docker/Fly/Railway deploy. 7.2k★, actively maintained. **No Hermes coupling**
  — it's a generic tool backend.
- **Fit:** Clean Class-B homelab fit and a real capability gap-filler: your agent currently has
  freshrss + obsidian but no general web browser. As `stacks/camofox`, internal-only behind Caddy,
  it gives Hermes (and Codex/Claude) reliable browsing.
- **Risk / caveats:**
  - It's anti-detection tooling — appropriate for personal research; **keep it strictly LAN/SSO-gated
    (`import internal_only` + Authentik)** and off the public internet. New attack surface; pin the
    image and read the Dockerfile before running.
  - Heavier service (~300 MB Camoufox binary, Firefox). Fine on valhalla, but it's not free.
  - **Wiring to Hermes:** either a thin MCP shim around its REST API, or a Hermes skill that curls
    it. Given your tool-overload sensitivity, expose it as **one or two** high-level tools (e.g.
    `browse(url)`, `search(query)`), not its full surface.
- **Implementation sketch:** New `stacks/camofox/docker-compose.yml` (bind config to `/config/camofox`,
  blobs/cache to `/storage1/labdata/camofox`, join `edge`), `stack.env`, a Caddy block
  (`camofox.ginnoir.com`, `import internal_only`), regenerate bookmarks, push. Then add the minimal
  Hermes tool/skill wrapper on the host and restart the gateway.

### 2.5 The three dashboards — pick **at most one** (Phase 3, DECISION)

You already run the bundled `hermes-webui.service`, so a UI is an *upgrade*, not a gap. These three
overlap heavily; adopting more than one is waste.

| | `hermes-ui` (pyrate-llama) | `hermes-workspace` (outsourc-e) | `mission-control` (builderz-labs) |
|---|---|---|---|
| Stars | 173 | 5.9k | 5.4k |
| Stack | 1 HTML file + Python **stdlib** proxy (`serve_lite.py`, :3333 → gateway :8642) | React/TS/**Vite build**, Node 22+, → gateway :8642 + dashboard :9119 | Next.js 16 / React 19, better-sqlite3 |
| Hermes-native? | **Yes** | **Yes** (best with vanilla hermes-agent) | **No** (OpenClaw/CrewAI/LangGraph/AutoGen/Claude SDK) |
| Effort to host | **Trivial** (no build) | Medium (build → container/stack) | Medium + **adapter work** |
| Headline features | chat, tasks/kanban, files, terminal, skills, MCP browser, cron, memory, health | all of the above + ops dashboards, "Conductor" missions, **Swarm Mode (tmux worker pools)** | 32 panels, RBAC, spend/trust scoring, multi-framework |
| Verdict | **Trial first** | **Consider as a proper stack later** | **Skip / defer** |

- **`hermes-ui` — recommended first move.** Lowest cost to evaluate a richer UI. Can run as a tiny
  host service or a minimal container next to the bundled webui; no build pipeline. If it's better
  than the bundled webui, keep it; if not, delete one file.
- **`hermes-workspace` — the ambitious option.** Genuinely the most capable, best run as a real
  `stacks/hermes-workspace` Docker build behind Caddy + Authentik. **Caveat to flag:** its
  marquee **Swarm Mode (parallel tmux worker pools) cannot actually parallelize inference on your
  setup** — the single P100 runs one model with `--parallel 1`, so "swarm" workers serialize on the
  GPU (or must use a different/remote backend per worker). Adopt for the workspace/observability
  features, not for swarm, unless/until you add GPU capacity or point swarm workers at cloud
  providers.
- **`mission-control` — skip unless requirements change.** It's framework-agnostic and **not
  Hermes-native** — using it means writing a Hermes adapter for a dashboard whose job the two
  Hermes-native UIs already do. Only worth it if you later want a single ops plane across *multiple*
  agent frameworks (you don't run those today).

---

## 3. Recommended phased rollout

**Phase 1 — host-side, reversible, high-leverage (no repo changes):**
1. `hermes-agent-acp-skill` — install skill, wire Codex + Claude Code delegation targets, smoke-test.
2. `hermes-curator-evolver` — install plugin in **report-only/dry-run**, manual cycle, then nightly
   systemd timer (report-only). CPU ranking; no P100 embeddings.

**Phase 2 — new capability + experiment:**
3. `camofox-browser` — new `stacks/camofox` (Class B), Caddy internal-only + Authentik, minimal
   Hermes tool wrapper.
4. `eagle-eye` — host-side trial behind an on/off switch; A/B skill-selection; keep only if it helps.

**Phase 3 — UI decision (your call):**
5. Trial `hermes-ui` alongside the bundled webui. Evaluate `hermes-workspace` as a stack if the
   workspace features justify the build. Skip `mission-control`.

Each phase is independently shippable and independently reversible. Stop after any phase.

---

## 4. Cross-cutting concerns (apply to every adoption)

- **Single-P100 discipline.** One GPU, one model, `--parallel 1`. Anything implying parallel or
  extra model loads — curator embeddings, eagle-eye dense layer, workspace swarm — must run on
  **CPU**, **off-peak**, or **not at all**. Never co-resident with gpt-oss on the P100.
- **Host vs repo boundary.** Class-A extensions are host-managed in `~/.hermes/` (document in memory
  + vault, like the rustdesk/obsidian units). Only Class-B services touch this repo. Don't
  accidentally commit host config here.
- **Tool/skill surface minimalism.** The whole reason your MCP is curated to ~29 tools. Expose new
  capabilities (camofox, delegation) as a *few high-level* tools, not raw surfaces, or you reintroduce
  the overload you fixed.
- **Provenance & safety.** Several repos are small/young (eagle-eye 1 commit; acp-skill 1 commit).
  **Read the code before running it**, especially anything that writes skills (curator) or executes
  shell / external agents (acp-skill, camofox). **Pin to a reviewed commit/tag**; keep stack images
  out of Watchtower auto-update.
- **Reversibility.** Back up `~/.hermes/config.yaml` before each Class-A change (you already do this);
  snapshot before promoting curator to `--approve`.
- **Security posture.** Class-B services: `import internal_only` + Authentik, secrets in `stack.env`
  (LF endings), never public.

---

## 5. What I am explicitly NOT proposing

- Not running curator-evolver in `--approve` (auto-skill-editing) mode out of the gate.
- Not loading any second model onto the P100 (no GPU embeddings, no GPU swarm).
- Not adopting more than one dashboard.
- Not committing host-side Hermes plugins/skills into the homelabstack repo.
- Not exposing camofox or any new UI to the public internet.

---

## 6. OPEN DECISIONS — please answer in the morning

1. **UI direction.** (a) Stay on bundled webui; (b) trial `hermes-ui` first *(my rec)*; (c) go
   straight to `hermes-workspace` as a stack; (d) something else. → gates Phase 3.
2. **Curator autonomy.** Keep `hermes-curator-evolver` **report-only forever**, or allow eventual
   `--approve` auto-edits after a trust period? *(My rec: report-only first, revisit.)*
3. **eagle-eye.** Trial it despite 1-commit maturity + the `jieba` dependency, or skip until it
   matures? *(My rec: short A/B trial, keep only if measurably better.)*
4. **camofox wiring.** MCP shim vs. a Hermes skill that curls the REST API? *(My rec: minimal
   2-tool skill to respect the tool budget.)*
5. **Scope confirmation.** Happy with the Phase 1 → 3 ordering, or want to cut/reorder anything?

The implementation plan that follows this spec details **Phase 1** concretely (it's unambiguous and
safe), with Phase 2/3 sketched pending your answers above.