Skip to content
Back to search

hermes-agent-control-room

Control Room-first template for managing Hermes agents from one VPS agent to specialist teams and orchestrated workflows

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shannhk--hermes-agent-control-room/badge.svg)](/listings/shannhk--hermes-agent-control-room)

HTML

<a href="/listings/shannhk--hermes-agent-control-room"><img src="/api/listings/shannhk--hermes-agent-control-room/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

There are three ways to use this repo.

Option A: Point An Agent At This Repo

This repo is designed to be agent-readable.

If your agent can read a GitHub repo or a local clone, point it here and ask:

Read this repo and help me set up an Agent Control Room.
Start with docs/starter-guide.md and the setup-control-room skill.

If the bundled skills are available to the agent, you can be more direct:

Use setup-control-room to bootstrap my VPS.

Or, if you need a new Hetzner server first:

Use create-vps, then chain into setup-control-room.

The intended agent flow is:

create-vps
  -> creates a Hetzner VPS, SSH key, and SSH alias

setup-control-room
  -> installs tooling and clones this repo onto the VPS

agent-control-room
  -> helps register and manage agents inside the Control Room

Important: the repo does not magically run code when opened. It gives your agent the setup instructions, templates, and skills. You still ask the agent to run the setup flow.

Option B: Manual Setup On An Existing VPS

Use this if you already have an Ubuntu/Debian VPS you can SSH into.

SSH in:

ssh root@YOUR_SERVER

Clone the Control Room:

git clone https://github.com/shannhk/hermes-agent-control-room.git /root/agent-control-room
cd /root/agent-control-room

Read the starter guide:

cat docs/starter-guide.md

Register your first agent:

mkdir -p agents/hermes-life
cp templates/agent/*.md agents/hermes-life/

Then fill in:

agents/hermes-life/inventory.md
agents/hermes-life/docker.md
agents/hermes-life/env-map.md
agents/hermes-life/runbook.md
agents/hermes-life/backup.md

Keep raw secrets out of those files.

Option C: Bootstrap With The Setup Skill

Use this if you have an SSH alias already configured locally.

The bundled `setup-control-room` skill is meant to:

- connect to your VPS over SSH - install base packages - install Node.js - install Claude Code - install Codex CLI - install Docker - install Hermes Agent best-effort - clone this repo to `/root/agent-control-room` - link bundled skills into `~/.claude/skills`

After it runs, SSH into the VPS and finish interactive auth:

ssh <alias>
claude /login
codex
hermes

Then start using the Control Room:

cd /root/agent-control-room
cat README.md
ls templates/agent/
ls skills/

Recommended First Milestone

Do not start by building a whole agent team.

First milestone:

1. Control Room exists on the VPS.
2. One agent is documented in agents/<agent-name>/.
3. No raw secrets are in the repo.
4. You can restart/debug/recover that one agent using its runbook.

Then move to Level 2 and add direct specialists.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 401 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Hermes Agent Control Room
  2. ![Hermes Agent Control Room](assets/hermes-agent-control-room.png)
  3. A public template for setting up an **Agent Control Room** first, then scaling from one Hermes agent to direct specialists, orchestrated teams, and automated workflows.
  4. The Agent Control Room is a sidecar repo/folder that documents and governs your Hermes agents. It is **not** an agent itself. It is the system map, operating manual, registry, runbook library, and recovery notebook for the agents you run.
  5. It gives you a clean path from:
  6. ```text
  7. one agent -> direct specialists -> orchestrator -> automated agent team
  8. ```
  9. ## About
  10. Hermes Agent Control Room is a starter kit for people who want to run Hermes agents like an operating system instead of a pile of disconnected bots.
  11. The repo gives you:
  12. - A control-plane folder structure for documenting agents.
  13. - Templates for agent runbooks, Docker notes, secret maps, and backups.
  14. - A level-based architecture for growing from one agent to a specialist team.
  15. - A task bus pattern for orchestrator-to-specialist delegation.
  16. - Bundled setup and operations skills an agent can use to build or manage the system.
  17. The key idea is simple: **set up the Control Room first, then plug agents into it.**
  18. ## Core Idea
  19. ```text
  20. Create a VPS or choose an existing one.
  21. Bootstrap the Agent Control Room.
  22. Register one Hermes agent.
  23. Add direct specialists when roles become clear.
  24. Add an orchestrator when you want one front door.
  25. Automate only after the manual system works.
  26. ```
  27. The Control Room sits on the side as the control plane. You can use it directly, talk directly to any agent, or talk to an orchestrator that delegates to specialists.
  28. ```text
  29. Agent Control Room = side control plane
  30. Orchestrator = optional manager/front-door agent
  31. Specialists = focused Hermes agents with role-specific tools
  32. Task Bus = handoff desk between orchestrator and specialists
  33. You = owner/operator with direct access to everything
  34. ```
  35. ## Full System Shape
  36. ```mermaid
  37. flowchart LR
  38. user["You / Operator"]
  39. control["Agent Control Room<br/><code>/root/agent-control-room</code><br/><br/>side control plane<br/>docs / rules / registry<br/>ports / env maps<br/>runbooks / backups"]
  40. orch["hermes-orchestrator<br/><br/>optional front door<br/>delegation / synthesis"]
  41. bus["Agent Task Bus<br/><code>/srv/agent-bus</code><br/><br/>inbox / working<br/>outbox / archive"]
  42. life["hermes-life<br/>personal agent"]
  43. seo["hermes-seo<br/>SEO specialist"]
  44. dev["hermes-dev<br/>code / site work"]
  45. cmo["hermes-cmo<br/>marketing"]
  46. ops["hermes-ops<br/>VPS / backups / security"]
  47. user -->|"control path<br/>edit docs / rules"| control
  48. user -->|"orchestrated path"| orch
  49. user -->|"direct path"| life
  50. user -->|"direct path"| seo
  51. user -->|"direct path"| dev
  52. user -->|"direct path"| cmo
  53. control -. "defines / documents / governs" .-> orch
  54. control -. "defines / documents / governs" .-> life
  55. control -. "defines / documents / governs" .-> seo
  56. control -. "defines / documents / governs" .-> dev
  57. control -. "defines / documents / governs" .-> cmo
  58. control -. "defines / documents / governs" .-> ops
  59. orch -->|"routes tasks"| bus
  60. bus --> seo
  61. bus --> dev
  62. bus --> cmo
  63. bus --> ops
  64. seo -->|"results"| bus
  65. dev -->|"results"| bus
  66. cmo -->|"results"| bus
  67. ops -->|"results"| bus
  68. bus -->|"summaries / artifacts"| orch
  69. orch -->|"final synthesis"| user
  70. ```
  71. ## Access Paths
  72. You are never locked into one workflow.
  73. ```text
  74. Control path:
  75. You -> Agent Control Room
  76. Direct path:
  77. You -> hermes-seo
  78. You -> hermes-dev
  79. You -> hermes-cmo
  80. Orchestrated path:
  81. You -> hermes-orchestrator -> Agent Task Bus -> Specialists -> You
  82. ```
  83. ## Architecture Levels
  84. ### Level 1: Agent Control Room + One Agent
  85. Set up the Control Room and register one Hermes agent.
  86. Best for:
  87. - One personal Hermes agent
  88. - VPS setup documentation
  89. - Docker migration planning
  90. - Keeping runbooks and secret maps organized
  91. You do not need an orchestrator or task bus yet.
  92. ### Level 2: Direct Specialist Agents
  93. Add multiple role-specific Hermes agents and talk to them directly.
  94. Examples:
  95. - `hermes-life`
  96. - `hermes-seo`
  97. - `hermes-dev`
  98. - `hermes-cmo`
  99. - `hermes-ops`
  100. The Control Room documents all of them. You choose which agent to talk to.
  101. ### Level 3: Orchestrator + Specialists
  102. Add `hermes-orchestrator` as an optional front door. You can still talk directly to specialists, but the orchestrator can route and synthesize work.
  103. The orchestrator follows the Control Room. It should not become a giant agent with every credential.
  104. ### Level 4: Automated Agent Team
  105. Add recurring workflows, audits, backup checks, task routing, and optional direct gateway/API calls.
  106. Only add automation after the manual workflow works.
  107. ## Bundled Skills
  108. This repo includes skills that can be linked into Claude Code or adapted for Hermes.
  109. ```text
  110. create-vps
  111. Create a fresh Hetzner VPS, SSH key, SSH alias, and local provisioning folder.
  112. setup-control-room
  113. Bootstrap an SSH-accessible VPS with Node, Claude Code, Codex, Docker,
  114. Hermes Agent, and this Control Room template.
  115. agent-control-room
  116. Manage the Control Room docs and agent folders.
  117. agent-task-router
  118. Route tasks from an orchestrator to specialists through a task bus.
  119. agent-registry-manager
  120. Maintain the agent registry.
  121. agent-backup-manager
  122. Design and audit per-agent backups without committing secrets.
  123. agent-security-auditor
  124. Check ports, dashboards, SSH, Docker, secret placement, and key scope.
  125. agent-team-cron-planner
  126. Plan recurring multi-agent workflows after manual workflows work.
  127. ```
  128. ## Suggested Folder Structure
  129. ```text
  130. agent-control-room/
  131. README.md
  132. agents/
  133. .gitkeep
  134. docs/
  135. architecture.md
  136. levels.md
  137. naming.md
  138. security.md
  139. task-bus.md
  140. orchestrator.md
  141. starter-guide.md
  142. shared/
  143. api-keys-sop.md
  144. commands.md
  145. security.md
  146. templates/
  147. agent/
  148. inventory.md
  149. docker.md
  150. env-map.md
  151. runbook.md
  152. backup.md
  153. docker/
  154. docker-compose.agent.yml
  155. docker-compose.orchestrator.yml
  156. task-bus/
  157. agents.yaml
  158. task-template.md
  159. result-template.md
  160. skills/
  161. create-vps/
  162. setup-control-room/
  163. agent-control-room/
  164. agent-task-router/
  165. agent-registry-manager/
  166. agent-backup-manager/
  167. agent-security-auditor/
  168. agent-team-cron-planner/
  169. examples/
  170. level-1-control-room-one-agent/
  171. level-2-direct-specialists/
  172. level-3-orchestrator-specialists/
  173. level-4-automated-team/
  174. ```
  175. ## Setup
  176. There are three ways to use this repo.
  177. ### Option A: Point An Agent At This Repo
  178. This repo is designed to be agent-readable.
  179. If your agent can read a GitHub repo or a local clone, point it here and ask:
  180. ```text
  181. Read this repo and help me set up an Agent Control Room.
  182. Start with docs/starter-guide.md and the setup-control-room skill.
  183. ```
  184. If the bundled skills are available to the agent, you can be more direct:
  185. ```text
  186. Use setup-control-room to bootstrap my VPS.
  187. ```
  188. Or, if you need a new Hetzner server first:
  189. ```text
  190. Use create-vps, then chain into setup-control-room.
  191. ```
  192. The intended agent flow is:
  193. ```text
  194. create-vps
  195. -> creates a Hetzner VPS, SSH key, and SSH alias
  196. setup-control-room
  197. -> installs tooling and clones this repo onto the VPS
  198. agent-control-room
  199. -> helps register and manage agents inside the Control Room
  200. ```
  201. Important: the repo does not magically run code when opened. It gives your agent the setup instructions, templates, and skills. You still ask the agent to run the setup flow.
  202. ### Option B: Manual Setup On An Existing VPS
  203. Use this if you already have an Ubuntu/Debian VPS you can SSH into.
  204. SSH in:
  205. ```bash
  206. ssh root@YOUR_SERVER
  207. ```
  208. Clone the Control Room:
  209. ```bash
  210. git clone https://github.com/shannhk/hermes-agent-control-room.git /root/agent-control-room
  211. cd /root/agent-control-room
  212. ```
  213. Read the starter guide:
  214. ```bash
  215. cat docs/starter-guide.md
  216. ```
  217. Register your first agent:
  218. ```bash
  219. mkdir -p agents/hermes-life
  220. cp templates/agent/*.md agents/hermes-life/
  221. ```
  222. Then fill in:
  223. ```text
  224. agents/hermes-life/inventory.md
  225. agents/hermes-life/docker.md
  226. agents/hermes-life/env-map.md
  227. agents/hermes-life/runbook.md
  228. agents/hermes-life/backup.md
  229. ```
  230. Keep raw secrets out of those files.
  231. ### Option C: Bootstrap With The Setup Skill
  232. Use this if you have an SSH alias already configured locally.
  233. The bundled `setup-control-room` skill is meant to:
  234. - connect to your VPS over SSH
  235. - install base packages
  236. - install Node.js
  237. - install Claude Code
  238. - install Codex CLI
  239. - install Docker
  240. - install Hermes Agent best-effort
  241. - clone this repo to `/root/agent-control-room`
  242. - link bundled skills into `~/.claude/skills`
  243. After it runs, SSH into the VPS and finish interactive auth:
  244. ```bash
  245. ssh <alias>
  246. claude /login
  247. codex
  248. hermes
  249. ```
  250. Then start using the Control Room:
  251. ```bash
  252. cd /root/agent-control-room
  253. cat README.md
  254. ls templates/agent/
  255. ls skills/
  256. ```
  257. ### Recommended First Milestone
  258. Do not start by building a whole agent team.
  259. First milestone:
  260. ```text
  261. 1. Control Room exists on the VPS.
  262. 2. One agent is documented in agents/<agent-name>/.
  263. 3. No raw secrets are in the repo.
  264. 4. You can restart/debug/recover that one agent using its runbook.
  265. ```
  266. Then move to Level 2 and add direct specialists.
  267. ## Runtime Split
  268. Keep the control plane separate from live runtime state.
  269. ```text
  270. /root/agent-control-room
  271. docs, templates, runbooks, registry, architecture
  272. no raw secrets
  273. /srv/<agent-name>/data
  274. live Hermes runtime
  275. .env, memory, skills, sessions, crons, logs
  276. ```
  277. ## Security Rule
  278. Never commit raw secrets.
  279. The control room may record:
  280. - secret names
  281. - provider
  282. - scope
  283. - location
  284. - rotation date
  285. It must not record:
  286. - API key values
  287. - OAuth refresh tokens
  288. - passwords
  289. - private keys
  290. ## License
  291. MIT. See `LICENSE`.
skills/setup-control-room/assets/bootstrap.sh · Bundled script · 96 lines · 3 findings marked
  1. #!/usr/bin/env bash
  2. set -euo pipefail
  3. export DEBIAN_FRONTEND=noninteractive
  4. CONTROL_ROOM_PATH="${CONTROL_ROOM_PATH:-/root/agent-control-room}"
  5. CONTROL_ROOM_REPO="${CONTROL_ROOM_REPO:-https://github.com/shannhk/hermes-agent-control-room.git}"
  6. log() {
  7. printf '\n==> %s\n' "$*"
  8. }
  9. log "Installing base packages"
  10. apt-get update -qq
  11. apt-get install -y --no-install-recommends curl ca-certificates git tmux htop
  12. log "Installing Node.js 22 if needed"
  13. NODE_MAJOR=0
  14. if command -v node >/dev/null 2>&1; then
  15. NODE_MAJOR="$(node -v | sed 's/^v\([0-9][0-9]*\).*/\1/')"
  16. fi
  17. if [ "$NODE_MAJOR" -lt 20 ]; then
  18. curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 24 on GitHub
  19. apt-get install -y nodejs
  20. fi
  21. log "Installing Claude Code if needed"
  22. if ! command -v claude >/dev/null 2>&1; then
  23. npm install -g @anthropic-ai/claude-code
  24. fi
  25. log "Installing Codex CLI if needed"
  26. if ! command -v codex >/dev/null 2>&1; then
  27. npm install -g @openai/codex
  28. fi
  29. log "Ensuring npm global bin is on PATH"
  30. NPM_BIN="$(npm config get prefix)/bin"
  31. if ! echo "$PATH" | tr ':' '\n' | grep -qx "$NPM_BIN"; then
  32. if ! grep -Fq "$NPM_BIN" "$HOME/.bashrc" 2>/dev/null; then
  33. printf '\nexport PATH=%s:$PATH\n' "$NPM_BIN" >> "$HOME/.bashrc"
  34. fi
  35. export PATH="$NPM_BIN:$PATH"
  36. fi
  37. log "Installing Docker if needed"
  38. if ! command -v docker >/dev/null 2>&1; then
  39. curl -fsSL https://get.docker.com | sh
  40. systemctl enable --now docker
    • Note: Quoted as data in code: Sets up something that runs again on its own (cron, launchd, systemd, startup entry or shell profile) and fetches from the network
    • Line 50 on GitHub
  41. fi
  42. log "Installing Hermes Agent best-effort if needed"
  43. if ! command -v hermes >/dev/null 2>&1 && [ ! -d /usr/local/lib/hermes-agent ] && [ ! -d "$HOME/.hermes/hermes-agent" ]; then
  44. curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash || true
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 55 on GitHub
  45. fi
  46. log "Cloning or updating Agent Control Room"
  47. if [ ! -d "$CONTROL_ROOM_PATH/.git" ]; then
  48. git clone "$CONTROL_ROOM_REPO" "$CONTROL_ROOM_PATH"
  49. else
  50. git -C "$CONTROL_ROOM_PATH" pull --ff-only
  51. fi
  52. log "Linking bundled skills into Claude skills directory"
  53. mkdir -p "$HOME/.claude/skills"
  54. for skill_dir in "$CONTROL_ROOM_PATH"/skills/*/; do
  55. [ -d "$skill_dir" ] || continue
  56. skill_name="$(basename "$skill_dir")"
  57. target="$HOME/.claude/skills/$skill_name"
  58. [ -e "$target" ] || ln -s "$skill_dir" "$target"
  59. done
  60. log "Installed versions"
  61. printf 'node: %s\n' "$(node --version 2>&1 || true)"
  62. printf 'npm: %s\n' "$(npm --version 2>&1 || true)"
  63. printf 'claude: %s\n' "$(claude --version 2>&1 || echo 'installed; auth may still be needed')"
  64. printf 'codex: %s\n' "$(codex --version 2>&1 || echo 'installed; auth may still be needed')"
  65. printf 'docker: %s\n' "$(docker --version 2>&1 || true)"
  66. printf 'hermes: %s\n' "$(command -v hermes >/dev/null 2>&1 && hermes --version 2>&1 || echo 'install may need interactive completion')"
  67. printf 'repo: %s\n' "$(git -C "$CONTROL_ROOM_PATH" remote get-url origin 2>&1 || true)"
  68. printf 'skills: %s linked\n' "$(find "$HOME/.claude/skills" -maxdepth 1 -mindepth 1 -type l | wc -l)"
  69. log "Next steps"
  70. cat <<'EOF'
  71. Open a real SSH terminal and finish auth:
  72. claude /login
  73. codex
  74. hermes
  75. Then:
  76. cd /root/agent-control-room
  77. cat README.md
  78. EOF

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.