docs: triage spec for Hermes ecosystem integrations (7 repos)
Research + fit analysis for hermes-agent-acp-skill, hermes-curator-evolver, eagle-eye, camofox-browser, hermes-ui, hermes-workspace, mission-control. Phased rollout; open decisions flagged for review. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
ginnoir
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
b7ff9b2411
commit
d794c98505
@@ -0,0 +1,246 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user