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.