Skip to content

Sync Hermes Orchestrator — setup

Step-by-step setup for the L4 orchestrator runtime. Estimated time: 10–20 minutes if you already have a personal Hermes working. Skip this entire doc if you're not ready to set up the orchestrator yet — see README.md for when this is worth doing.

Prerequisites: - Personal Hermes installed and working (you have one if you've used the v2 chief-of-staff skill). - An Anthropic direct API key (sk-ant-api03-...). The orchestrator can use the same key as your personal Hermes initially; split later if you want separate billing. - A Pulse API key (sak_...) — orchestrator can use yours for now; future privileged-scope key when team queries come back. - (Optional) A separate Telegram bot via @BotFather, if you want a Telegram surface for the orchestrator.

1. Create the orchestrator config dir

mkdir -p ~/.hermes-sync
mkdir -p ~/.hermes-sync/skills

2. Copy and customize the config template

cp <repo-root>/docs/orchestrator/config-template.yaml ~/.hermes-sync/config.yaml
# Open in your editor
open -a TextEdit ~/.hermes-sync/config.yaml

Review and adjust:

  • Model — defaults to claude-sonnet-4-6. If you want to scaffold cheap, use claude-haiku-4-5-20251001.
  • Personality — defaults to sync_orchestrator (see template). Change if you want a different tone.
  • Telegram — uncommented section if you want a Telegram surface. Leave commented for CLI-only.

3. Create the orchestrator's env file

Create ~/.hermes-sync/.env (note: separate from ~/.hermes/.env):

# Anthropic auth — direct API key required (long-context beta is incompatible
# with OAuth-style tokens; see https://console.anthropic.com)
ANTHROPIC_API_KEY=sk-ant-api03-<your-key>

# Pulse API key — used by the MCP server registration in config.yaml.
# Initially fine to reuse your personal Sync key; replace with a
# privileged-scope key when team-skill work returns from deferral.
PULSE_API_KEY=sak_<your-sync-key>

# (Optional) Telegram bot token if you uncommented the telegram section
# in config.yaml. Get one from @BotFather; create a NEW bot for the
# orchestrator — do not reuse your personal Hermes bot token.
# TELEGRAM_BOT_TOKEN=<your-orchestrator-bot-token>

4. Start the orchestrator runtime

This is the part that depends on Hermes' multi-runtime support. Hermes was originally designed as a single-config runtime; running two runtimes side-by-side may require either:

Option A — separate config flag (preferred if Hermes supports it):

hermes --config ~/.hermes-sync/config.yaml gateway start

Option B — environment variable override:

HERMES_CONFIG_DIR=~/.hermes-sync hermes gateway start

Option C — start Hermes with HOME redirected (last-resort hack):

HOME=~/.hermes-sync-runtime hermes gateway start
# This requires `~/.hermes-sync-runtime/.hermes/` to be a symlink to ~/.hermes-sync/.
# Not recommended unless A and B both fail.

If none of these work in your Hermes version, the multi-runtime support may need explicit work in Hermes itself. Note this as a real blocker and ping the Hermes maintainers — multi-runtime is a known use case in their docs.

5. Verify the orchestrator is separate from personal

# In the orchestrator runtime, ask:
# "What is your role and which skills do you have?"
#
# You should hear back something like:
# "I am the Sync Hermes orchestrator. I currently have no skills
#  installed — F2 skills are deferred per ADR-046."
#
# If you instead get the personal-DTA personality (kawaii or whatever
# you've configured personally), the configs are getting commingled.
# Check that ~/.hermes-sync/config.yaml is being read, not ~/.hermes/.

In a separate terminal, also verify the personal Hermes is still running with its own config — they should be independent processes.

6. (Optional) Verify MCP connectivity

Inside the orchestrator runtime:

> List available MCP tools.

You should see pulse_get_profile, pulse_get_recent_decisions, pulse_submit_feedback from the registered Pulse MCP server. If you don't, check the mcp_servers: block in ~/.hermes-sync/config.yaml and the PULSE_API_KEY in ~/.hermes-sync/.env.

What now?

The orchestrator is alive but functionally a thin shell — it has access to the Pulse MCP server but no F2 skills installed yet. That's by design (ADR-046 deferral). The orchestrator becomes useful when:

  • F2 skills come back from deferral (Skills 5, 6-8, 9) and get installed into ~/.hermes-sync/skills/
  • L5 (A2A endpoint) is built so external agents can call it
  • §6a lock+rollback infrastructure attaches to the first orchestrator-driven skill mutation

For now, the addressability story is what's earned: the orchestrator exists, has a separate identity, and is ready to host F2 work when demand triggers it (per ADR-046's revisit triggers).

Troubleshooting

"Could not find service ai.hermes.gateway" when starting — this is a launchd warning when no instance was previously running. The reload that follows is the actual start. Expected.

Orchestrator picks up personal Hermes' config instead — the multi-runtime mechanism (Option A/B/C in step 4) isn't being honored. Verify with lsof -p <hermes-pid> | grep config to see which file the running gateway opened.

MCP tools don't appear — likely either the PULSE_API_KEY env var isn't visible to the runtime or the MCP server URL is unreachable. Test the URL directly: curl -s -X POST https://sync.beaconinfra.xyz/api/agent/v1/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' — should return three tools.

MCP tools/call fails with 401 — bearer token isn't being sent correctly. The ${PULSE_API_KEY} templating in config.yaml requires the variable to be present in the orchestrator's env at startup. Check cat ~/.hermes-sync/.env | grep PULSE_API_KEY.