hermes-agent-control-room

Hermes Agent Control Room

Skill by ara.so — Hermes Skills collection.

Overview

Hermes Agent Control Room is a governance and documentation framework for running Hermes agents as a managed system instead of disconnected bots. It provides:

• Control plane structure for documenting agents, runbooks, secrets, and backups
• Architecture levels from one agent → specialists → orchestrator → automated team
• Task bus pattern for orchestrator-to-specialist delegation
• Bundled skills for VPS setup, agent management, security audits, and backups
• Templates for agent inventory, Docker configs, env maps, runbooks, and backup plans

The core principle: set up the Control Room first, then plug agents into it.

Architecture Levels

Level 1: Control Room + One Agent

Single Hermes agent with documented setup, runbooks, and secret management.

Level 2: Direct Specialist Agents

Multiple role-specific agents (hermes-seo, hermes-dev, hermes-cmo) that you talk to directly.

Level 3: Orchestrator + Specialists

Add hermes-orchestrator as a front door that routes tasks to specialists via the task bus.

Level 4: Automated Agent Team

Recurring workflows, audits, and automated task routing after manual workflows work.

Installation

Option A: Clone to Existing VPS

ssh root@YOUR_SERVER
git clone https://github.com/shannhk/hermes-agent-control-room.git /root/agent-control-room
cd /root/agent-control-room
cat docs/starter-guide.md

Option B: Bootstrap New Hetzner VPS

Use the bundled create-vps and setup-control-room skills:

# Agent workflow:
# 1. create-vps → creates Hetzner VPS, SSH key, SSH alias
# 2. setup-control-room → installs Node, Claude Code, Codex, Docker, Hermes, clones repo
# 3. SSH in and complete auth

The setup-control-room skill will:

• Install base packages (git, curl, build-essential)
• Install Node.js via nvm
• Install Claude Code, Codex CLI, Hermes Agent
• Clone this repo to /root/agent-control-room
• Link bundled skills to ~/.claude/skills

After bootstrap, complete interactive auth:

ssh <alias>
claude /login
codex
hermes

Folder Structure

agent-control-room/
  README.md                      # This file
  agents/                        # Per-agent folders
    hermes-life/
      inventory.md               # Agent metadata
      docker.md                  # Container notes
      env-map.md                 # Secret map (no raw values)
      runbook.md                 # Start/stop/debug procedures
      backup.md                  # Backup plan
  docs/
    architecture.md              # System design
    levels.md                    # Growth stages
    naming.md                    # Agent naming conventions
    security.md                  # Security model
    task-bus.md                  # Task routing spec
    orchestrator.md              # Orchestrator design
    starter-guide.md             # First steps
  shared/
    api-keys-sop.md              # Secret management SOP
    commands.md                  # Common commands
    security.md                  # Security checklist
  templates/
    agent/                       # Agent doc templates
    docker/                      # Docker compose templates
    task-bus/                    # Task bus templates
  skills/                        # Bundled agent skills
  examples/                      # Example setups per level

Registering Your First Agent

cd /root/agent-control-room
mkdir -p agents/hermes-life
cp templates/agent/*.md agents/hermes-life/

Fill in the templates:

agents/hermes-life/inventory.md

# hermes-life Agent Inventory

**Agent Name:** hermes-life  
**Role:** Personal assistant  
**Port:** 3000  
**Status:** Active  
**Created:** 2026-05-15  
**Owner:** Your Name

## Purpose
Personal Hermes agent for daily tasks, research, and file management.

## Tools
- Terminal
- File system
- Web research
- Email (via API)

## Secrets Required
- ANTHROPIC_API_KEY
- GMAIL_API_KEY (optional)

agents/hermes-life/env-map.md

# hermes-life Environment Map

**DO NOT COMMIT RAW SECRETS**

## Required Secrets

| Name | Provider | Scope | Location | Rotated |
|------|----------|-------|----------|---------|
| ANTHROPIC_API_KEY | Anthropic | Full API | /srv/hermes-life/data/.env | 2026-05-10 |
| GMAIL_API_KEY | Google | Gmail read/send | /srv/hermes-life/data/.env | Never |

## Storage Location
`/srv/hermes-life/data/.env`

## Backup Location
Encrypted backup in `/root/backups/hermes-life-env.gpg`

agents/hermes-life/runbook.md

# hermes-life Runbook

## Start Agent
```bash
cd /srv/hermes-life
docker-compose up -d

Stop Agent

docker-compose down

View Logs

docker-compose logs -f

Restart After Config Change

docker-compose restart

Emergency Recovery

1. Check logs: docker-compose logs --tail=100
2. Verify .env exists: ls -la /srv/hermes-life/data/.env
3. Restore from backup if needed: gpg -d /root/backups/hermes-life-env.gpg > /srv/hermes-life/data/.env
4. Restart: docker-compose restart

## Runtime Split

Keep control plane separate from runtime state:

```text
/root/agent-control-room/
  Control plane: docs, templates, runbooks, registry
  No raw secrets

/srv/<agent-name>/data/
  Runtime: .env, memory, skills, sessions, crons, logs
  Raw secrets live here

Adding Direct Specialist Agents (Level 2)

# Create specialist agent folders
cd /root/agent-control-room
mkdir -p agents/{hermes-seo,hermes-dev,hermes-cmo,hermes-ops}

# Copy templates
for agent in hermes-seo hermes-dev hermes-cmo hermes-ops; do
  cp templates/agent/*.md agents/$agent/
done

Document each specialist's:

• Role: What it does (SEO audits, code changes, marketing, ops)
• Tools: Specific tool access (Ahrefs API, GitHub, Mailchimp, Docker socket)
• Secrets: Scoped credentials (not full system access)
• Port: Unique port per agent (3001, 3002, 3003, etc.)

Adding an Orchestrator (Level 3)

Create Orchestrator Agent

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

agents/hermes-orchestrator/inventory.md

# hermes-orchestrator Agent Inventory

**Agent Name:** hermes-orchestrator  
**Role:** Front door / task router  
**Port:** 3100  
**Status:** Active

## Purpose
Routes user requests to specialist agents via the task bus.
Synthesizes results from multiple specialists.

## Tools
- File system (task bus access)
- No direct access to specialist credentials
- Read/write to `/srv/agent-bus/{inbox,working,outbox,archive}`

## Does NOT Have
- Database credentials
- API keys for specialist services
- SSH keys to other systems

## Delegation Model
1. Receives user request
2. Writes task to `/srv/agent-bus/inbox/<specialist>/`
3. Specialist picks up task, works on it, writes result to `/srv/agent-bus/outbox/`
4. Orchestrator reads result, synthesizes, responds to user

Set Up Task Bus

# Create task bus directories
mkdir -p /srv/agent-bus/{inbox,working,outbox,archive}
mkdir -p /srv/agent-bus/inbox/{seo,dev,cmo,ops}

# Copy task bus config
cp agent-control-room/templates/task-bus/agents.yaml /srv/agent-bus/

Task Bus Workflow

1. User → Orchestrator: "Audit SEO for example.com"

2. Orchestrator → Task Bus:
   /srv/agent-bus/inbox/seo/task-001.md
   ---
   Task: SEO audit for example.com
   Requested: 2026-05-17T10:00:00Z
   Requestor: User via hermes-orchestrator
   ---

3. hermes-seo → Picks Up Task:
   Moves task-001.md to /srv/agent-bus/working/seo/

4. hermes-seo → Works:
   Runs Ahrefs audit, generates report

5. hermes-seo → Completes:
   /srv/agent-bus/outbox/seo/result-001.md
   Moves task to /srv/agent-bus/archive/seo/

6. Orchestrator → Reads Result:
   Synthesizes and responds to user

Task Bus Example

Task Template (/srv/agent-bus/inbox/dev/task-002.md):

---
task_id: task-002
specialist: dev
created: 2026-05-17T14:30:00Z
requestor: hermes-orchestrator
priority: normal
---

# Task: Add Contact Form to Website

## Requirements
- Add contact form to /contact page
- Fields: name, email, message
- POST to /api/contact endpoint
- Basic validation

## Context
User requested contact form for their business site.

## Expected Deliverables
- Updated HTML/CSS
- Form validation script
- Deployed to staging

Result Template (/srv/agent-bus/outbox/dev/result-002.md):

---
task_id: task-002
specialist: dev
completed: 2026-05-17T15:45:00Z
status: success
---

# Result: Contact Form Added

## What Was Done
- Created /contact.html with form fields
- Added client-side validation in contact.js
- Configured backend endpoint at /api/contact
- Deployed to staging: https://staging.example.com/contact

## Files Changed
- /public/contact.html (new)
- /public/js/contact.js (new)
- /api/contact.js (new)

## Testing
- Tested form submission
- Verified email delivery
- Checked validation for all fields

## Next Steps
User can review at staging URL. Ready for production deploy on approval.

Docker Compose for Orchestrator

templates/docker/docker-compose.orchestrator.yml:

version: '3.8'

services:
  hermes-orchestrator:
    image: hermes-agent:latest
    container_name: hermes-orchestrator
    restart: unless-stopped
    ports:
      - "3100:3000"
    volumes:
      - /srv/hermes-orchestrator/data:/app/data
      - /srv/agent-bus:/srv/agent-bus
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - AGENT_ROLE=orchestrator
      - TASK_BUS_PATH=/srv/agent-bus
    networks:
      - agent-net

networks:
  agent-net:
    driver: bridge

Security Best Practices

Secret Storage

# Store secrets in per-agent .env files
/srv/hermes-life/data/.env
/srv/hermes-seo/data/.env
/srv/hermes-dev/data/.env

# Backup encrypted
gpg -c /srv/hermes-life/data/.env -o /root/backups/hermes-life-env.gpg

# Never commit to git
echo "*.env" >> /root/agent-control-room/.gitignore

Agent Credential Scope

❌ BAD: Orchestrator has all API keys
✅ GOOD: Each specialist has only its scoped keys

hermes-seo:
  - AHREFS_API_KEY
  - GOOGLE_SEARCH_CONSOLE_KEY

hermes-dev:
  - GITHUB_TOKEN
  - DEPLOY_KEY

hermes-orchestrator:
  - ANTHROPIC_API_KEY (for LLM)
  - NO access to specialist service APIs

Port Security

# Check exposed ports
ss -tulpn | grep LISTEN

# Use firewall for non-orchestrator agents
ufw allow 3100/tcp  # orchestrator only
ufw deny 3001/tcp   # hermes-seo (internal only)
ufw deny 3002/tcp   # hermes-dev (internal only)

Bundled Skills

The repo includes agent skills for VPS and control room management:

Skill	Purpose
create-vps	Create Hetzner VPS, SSH key, SSH alias
setup-control-room	Bootstrap VPS with Node, Docker, Hermes, Control Room
agent-control-room	Manage Control Room docs and agent folders
agent-task-router	Route tasks from orchestrator to specialists
agent-registry-manager	Maintain agent registry
agent-backup-manager	Design and audit per-agent backups
agent-security-auditor	Check ports, dashboards, SSH, Docker, secrets
agent-team-cron-planner	Plan recurring multi-agent workflows

After running setup-control-room, skills are linked to ~/.claude/skills/.

Common Commands

Manage Control Room

# Update Control Room repo
cd /root/agent-control-room
git pull

# Register new agent
mkdir -p agents/hermes-newagent
cp templates/agent/*.md agents/hermes-newagent/

# List all agents
ls agents/

# View agent inventory
cat agents/hermes-seo/inventory.md

Manage Agents

# Start agent
cd /srv/hermes-seo
docker-compose up -d

# View logs
docker-compose logs -f

# Restart agent
docker-compose restart

# Stop agent
docker-compose down

Task Bus Operations

# Create task for specialist
cat > /srv/agent-bus/inbox/seo/task-003.md <<EOF
---
task_id: task-003
specialist: seo
created: $(date -Iseconds)
requestor: manual
---
# Task: Run SEO audit for newsite.com
EOF

# Check task status
ls /srv/agent-bus/working/seo/
ls /srv/agent-bus/outbox/seo/

# Archive completed tasks
mv /srv/agent-bus/outbox/seo/* /srv/agent-bus/archive/seo/

Troubleshooting

Agent Won't Start

# Check Docker logs
docker-compose logs --tail=50

# Verify .env exists
ls -la /srv/<agent-name>/data/.env

# Check port conflicts
ss -tulpn | grep <port>

# Restart Docker
systemctl restart docker
docker-compose up -d

Orchestrator Can't Find Specialists

# Verify task bus directories exist
ls -la /srv/agent-bus/inbox/

# Check permissions
chmod -R 755 /srv/agent-bus

# Verify agents.yaml
cat /srv/agent-bus/agents.yaml

Secret Not Found

# Check .env file
cat /srv/<agent-name>/data/.env | grep API_KEY

# Restore from backup
gpg -d /root/backups/<agent-name>-env.gpg > /srv/<agent-name>/data/.env

# Restart agent
cd /srv/<agent-name>
docker-compose restart

Task Not Being Picked Up

# Check task format
cat /srv/agent-bus/inbox/<specialist>/task-*.md

# Verify specialist is running
docker ps | grep hermes-<specialist>

# Check specialist logs
cd /srv/hermes-<specialist>
docker-compose logs --tail=100

Recommended First Milestone

Do not build a full team immediately. Start with:

1. Control Room exists on VPS: /root/agent-control-room
2. One agent documented: agents/hermes-life/
3. No raw secrets in repo
4. Can restart/debug agent using runbook

Then expand to Level 2 (direct specialists), Level 3 (orchestrator), Level 4 (automation).

Environment Variables

Reference environment variables in agent configs:

# docker-compose.yml
environment:
  - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  - GITHUB_TOKEN=${GITHUB_TOKEN}
  - DATABASE_URL=${DATABASE_URL}

Store actual values in /srv/<agent-name>/data/.env:

ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...
DATABASE_URL=postgresql://...

Access Paths

You have multiple ways to interact with agents:

Control Path: Edit Control Room docs directly

vim /root/agent-control-room/agents/hermes-seo/runbook.md

Direct Path: Talk directly to specialist agents

curl http://localhost:3001  # hermes-seo
curl http://localhost:3002  # hermes-dev

Orchestrated Path: Use orchestrator as front door

curl http://localhost:3100 -d "Audit SEO for example.com"
# Orchestrator → Task Bus → Specialist → Result → Orchestrator → You

Resources

• GitHub: https://github.com/shannhk/hermes-agent-control-room
• License: MIT
• Topics: agent-control-room, ai-agents, hermes-agent, multi-agent, vps