Hermes: the orchestrator
Hermes is Mastery HQ’s built-in orchestrator — the persona behind the Ninja pane. Where a normal agent writes code, Hermes manages: it interprets plain-language requests, drives the workspace (open, arrange, theme, status), dispatches tasks to your named agents, and reports outcomes back to you. Talk to it when you’d rather state intent (“get the tests fixed”) than direct each agent yourself.
Opening and talking to Hermes
Section titled “Opening and talking to Hermes”- Say/type open hermes (or
Ctrl+Shift+H) — a violet Ninja window appears. - Address it from anywhere: hey hermes, minimize all agents and open the sprint board.
- It runs the same command engine as the command bar, so anything you can command, Hermes can too — plus free-form requests that it reasons about with its configured brain.
Do you need a server? Almost certainly not
Section titled “Do you need a server? Almost certainly not”Two different things get called “Hermes”, and only one of them needs any setup at all:
| What you want | What it needs |
|---|---|
| The Hermes pane — plans, answers, drives your workspace, dispatches to agents | A brain. Nothing else: no server, no Node, no token. |
| Driving your desktop from your phone — WhatsApp/Telegram → Hermes → your PC | A relay, plus a device token. |
If you only want the first — and most people do — you can stop reading here. Open Hermes and talk to it.
The brain
Section titled “The brain”Hermes thinks with a configurable backend (Settings → Agents → Hermes). The default is Automatic, which picks per question: a connected Hermes link if you have one, otherwise your xAI (Grok) key. If neither is set up, Hermes tells you what your options are rather than failing with an error.
Claude is never chosen automatically. Hermes uses Claude only if you select it and provide an Anthropic API key — an API key sitting in your settings for something else is not treated as permission to spend it here.
Running a relay (only for phone control)
Section titled “Running a relay (only for phone control)”Three routes, easiest first:
- This computer (one click) — Settings → Agents → Hermes → Relay setup. Press Set up on this computer. Mastery HQ copies the relay in, uses its own bundled Node, and starts it on
127.0.0.1only. Nothing is installed system-wide, nothing is exposed to your network, and it stops when Mastery HQ does. Best for trying phone control out. - Tailscale — run the relay on any machine on your tailnet. No domain or TLS needed; Tailscale already encrypts the link.
- VPS — reachable from anywhere over
wss://. One paste-block sets up the service, with your token already filled in. Choose this when you want your desktop reachable while it’s the only thing awake — a laptop that’s asleep can’t answer, a rented box can.
If your relay sits behind Cloudflare Access (for example, exposed at wss://hermes.yourdomain.com through a Cloudflare Tunnel and gated by a service token), fill in the connection’s Access Client ID and Access Client Secret in that same tab. Mastery HQ sends them as CF-Access-Client-Id / CF-Access-Client-Secret headers on the WebSocket handshake, so the edge lets the connection through; your device token still authenticates you to the relay underneath. Leave both blank for a plain Tailscale or ws:// relay.
What Hermes knows
Section titled “What Hermes knows”Hermes can see the workspace state (who’s open, who’s running) and each agent’s persistent profile — the categories of work they’ve done, skills, and history. That’s the basis for routing: send the testing task to the agent who’s done the testing.
A taste
Section titled “A taste”You: hey hermes, who’s working? Hermes: 2 working: Alex (fix login bug), Maya (write API docs). You: have Alex work on the signup card when he’s done. Hermes: Queued — assigning “signup flow” to Alex.
Hermes actions are confirmed in-app when they’re consequential, and everything lands in the Audit Log.
Frequently asked questions
What's the difference between Hermes and a regular agent?
A regular agent runs a coding CLI and works on your code. Hermes is management: it understands your workspace, can open and arrange windows, send tasks to the right agent, and relay results — the layer you talk to when you'd rather state intent than direct each agent.
Do I need a server or a VPS to use Hermes?
No. The Hermes pane needs only a brain — a Grok or Anthropic API key, or a relay if you already have one — and works with no server at all. A relay is required only if you want to drive your desktop from your phone, and even then you can run one on this computer with a single click.
Why doesn't Hermes use Claude automatically when I have an Anthropic key?
Because a key in your settings may be there for something else, and using it would spend your money without being asked. Hermes uses Claude only when you explicitly select the Claude brain.