---

Swarm Mode

Hermes Agent Swarm turns the workspace into a live control plane: unlimited Hermes Agents, 1 orchestrator, 0 humans manually dispatching. Persistent tmux workers keep context across tasks, rotate safely, and report proof-bearing checkpoints. Role-based dispatch routes builders, reviewers, docs, research, ops, triage, QA, and lab lanes without turning Eric into the task router. A byte-verified review gate protects release branches before PRs ship. Autonomous PR/issue lanes, lab experiments, and the repair playbook keep the machine moving while humans handle judgment.

Start here: docs/swarm/

• Orchestrator Chat — ask the control plane for one task, a decomposed mission, or a full broadcast.
• Multi-Agent Control Plane — see persistent Hermes Agents, roles, state, runtime, and routing wires in one surface.
• Kanban TaskBoard — plan backlog, ready, running, review, blocked, and done lanes without leaving the workspace.
• Reports + Inbox — review checkpoints, blockers, handoffs, and ready-for-human decisions.
• TUI View built in — attach to tmux-backed workers or fall back to a live shell/log stream.

---

✨ What's inside

• 💬 Chat — Real-time SSE streaming, tool call rendering, multi-session, markdown + syntax highlighting
• 🧠 Memory — Browse, search, and edit agent memory; markdown live editor
• 🧩 Skills — Browse 2,000+ skills with origin badges, filters, source paths, marketplace
• 🔌 MCP — Full /mcp page (catalog + marketplace + sources), or fallback to local config CRUD
• 📁 Files + Terminal — Full workspace file browser with Monaco; cross-platform PTY terminal
• 🎮 Operations — Multi-agent dashboard with profile presets (Sage/Trader/Builder/Scribe/Ops) and 'Needs setup' detection
• 📡 Conductor — Mission dispatch + decomposition with dashboard-backed missions when available and Workspace-native Swarm fallback otherwise
• 👥 Agent View — Live agent panel in chat with avatar, queue, history, usage meter
• 🐝 Swarm Mode — Persistent tmux-backed Hermes Agent workers with role-based dispatch
• 🗄️ Dashboard — Aggregated overview: sessions, model mix, cost ledger, attention card, ops strip
• 🎨 Themes — Hermes, Nous, Bronze, Slate, Mono (light + dark)
• 🔒 Security — Auth middleware on every route, CSP, path-traversal guard, fail-closed remote bind
• 📱 PWA + Tailscale — Install as a native-feeling app; access from any device on your tailnet
• ⚙️ Capability gates — Features that need upstream endpoints (Conductor) show a clean placeholder instead of failing mid-action

---

📸 Screenshots

Chat	Conductor

Dashboard	Memory

Terminal	Settings

Tasks	Jobs

---

🚀 Quick Start

Three paths — pick the one that matches you:

Path	Best for	Time
🐳 Docker Compose	Self-hosters, home labs, "give me a compose gig"	~2 min
🌐 One-line install	Local dev on macOS/Linux	~3 min
🔌 Attach to existing hermes-agent	You already run Hermes Agent	~1 min

One-line install

curl -fsSL https://raw.githubusercontent.com/outsourc-e/hermes-workspace/main/install.sh | bash

This installs hermes-agent via Nous's official installer, clones this repo, sets up .env, and installs dependencies. Then:

hermes gateway run                  # terminal 1
cd ~/hermes-workspace && pnpm dev   # terminal 2

Open http://localhost:3000. That's it.

---

Already running hermes-agent? Attach the workspace to it

If you already have hermes-agent installed (via Nous's official installer, a source checkout, systemd, Docker, or another existing setup) and it's serving the gateway at http://<host>:8642, you don't need to reinstall anything — just point the workspace at it.

git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
pnpm install
cp .env.example .env

# Point at your existing Hermes Agent services.
echo 'HERMES_API_URL=http://127.0.0.1:8642' >> .env
# Zero-fork installs also need the separate dashboard API for config/sessions/skills/jobs.
echo 'HERMES_DASHBOARD_URL=http://127.0.0.1:9119' >> .env

# If your gateway was started with API_SERVER_KEY (auth enabled), set the same value:
# echo 'HERMES_API_TOKEN=***' >> .env

pnpm dev                            # http://localhost:3000 (override with PORT=4000 pnpm dev)

Requirements on the agent side:

• Gateway bound to an address the workspace can reach (typically API_SERVER_HOST=0.0.0.0 + the port exposed).
• API_SERVER_ENABLED=true in ~/.hermes/.env (or the agent's env) so the gateway serves core APIs on :8642.
• hermes dashboard running (default http://127.0.0.1:9119) for zero-fork installs. The dashboard provides config, sessions, skills, and jobs APIs.
• If API_SERVER_KEY is set, the workspace must pass the same value via HERMES_API_TOKEN — otherwise leave both unset.

Verify both services before opening the workspace:

• curl http://127.0.0.1:8642/health should return ok.
• curl http://127.0.0.1:9119/api/status should return dashboard metadata.
• curl http://127.0.0.1:3000/api/sessions (after the workspace boots) should return a sessions payload or an empty list.

If /api/sessions is already returning data, do not start another gateway just because the UI still says Offline — refresh or reprobe the Workspace UI first.

If your default model is gpt-5.4 / openai-codex, make sure Codex CLI auth is live before testing chat