Skip to content

L5 — A2A endpoint + deployment

This doc covers what L5 is, what's needed to ship it, and the decisions that need real Hermes A2A knowledge before any code lands. This is intentionally a research/deployment scaffold, not implementation — the brief flags Hermes A2A wire format as a "learn hands-on first" item (§9 Q1) and the honest move is to not speculate.

What L5 is

L5 = exposing the L4 orchestrator over A2A so external personal DTAs (James's, Cici's, future Beacon team members', or external prospects' agents) can call the orchestrator's skills. Until L5, the orchestrator runs locally and only the operator can talk to it. With L5, "the Sync agent" becomes a thing other agents can address.

This is the GTM-relevant capability for the Raid Guild / MetaClawTel angle: external DAO agents can query "what's user X's coherence score?" or "given this team-decision context, who should we delegate to?" — through A2A — and the orchestrator answers back.

What we know

  • Hermes has A2A built into the runtime. Exposing the agent is something the runtime does natively, not something we implement.
  • Per James's transcript notes (May 7): the public-facing requirement is reachability — the agent's HTTP endpoint needs to be addressable from outside the operator's machine. Two paths:
  • Cloudflare tunnel (recommended for dev) — exposes the local Hermes A2A port to a public URL via Cloudflare's edge.
  • Telegram bot bridge (alternative) — both agents join a Telegram group; A2A messages flow through Telegram. Less ideal: noisier, slower, and chat messages flying through the group.
  • For production, the orchestrator needs always-on availability — meaning the runtime moves off CoachJ's laptop to a server (Vercel / Railway / Fly / Supabase Edge Functions). See §9 Q3.
  • Auth model: the orchestrator's A2A endpoint needs to accept identity from caller agents and scope every query to "what that user is allowed to see." Per brief §6, "personal agent identity passes through" — the caller's identity is forwarded, not the orchestrator's. Mechanism is Hermes-A2A-specific.

What we don't know yet (hands-on learning needed)

These should be resolved before any L5 code ships:

  1. A2A wire format. JSON-RPC like MCP? gRPC? Hermes-specific? The actual on-the-wire shape of an A2A request/response.
  2. A2A auth handshake. How does the caller agent authenticate to the orchestrator? Bearer token? OAuth-like flow? Pre-shared secret in the Hermes config?
  3. Skill discovery. When an external agent connects, how does it learn what skills the orchestrator exposes? Static manifest? Discovery endpoint? Listed in ~/.hermes-sync/skills/?
  4. Skill invocation. How does the calling agent specify which skill to invoke, and what arguments?
  5. Response shape. Synchronous return? Streaming? Long-poll? How does the calling agent handle multi-step skill execution?
  6. Local A2A port. Which port does the Hermes runtime listen on for A2A by default, and is it configurable?

CoachJ should work through these via Hermes docs + hands-on experimentation before this doc gets filled in with concrete instructions.

Cloudflare tunnel setup (when ready)

Concrete enough to write down now since Cloudflare is well-known:

# 1. Install cloudflared if not already
brew install cloudflared

# 2. Authenticate cloudflared with your Cloudflare account
cloudflared tunnel login

# 3. Create a tunnel for the orchestrator
cloudflared tunnel create sync-hermes-orchestrator

# 4. Configure the tunnel — once you know which local port Hermes
#    A2A listens on (open question 6 above), point the tunnel at it.
#    Example assuming port 8080 (replace with actual):
cat > ~/.cloudflared/sync-hermes.yml <<EOF
tunnel: sync-hermes-orchestrator
credentials-file: /Users/$(whoami)/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: sync-hermes.<your-cloudflare-domain>
    service: http://localhost:8080
  - service: http_status:404
EOF

# 5. Run the tunnel in the foreground to test
cloudflared tunnel --config ~/.cloudflared/sync-hermes.yml run

# 6. (Once verified) Install as a service so it persists
sudo cloudflared service install

After this, the orchestrator's A2A endpoint should be reachable at https://sync-hermes.<your-domain> from anywhere. Test with a curl from another machine before bringing in James's DTA.

Security: the orchestrator is now publicly reachable. Lock it down before going wide: - Strong auth on every A2A request (mechanism TBD per open question 2). - Per brief §6, audit log every query: (caller_user_id, skill, target_scope, timestamp). - Rate limiting at the runtime level. - Kill switch per the existing agent_feature_flags pattern.

Production hosting decision (§9 Q3)

When the orchestrator graduates from CoachJ's laptop to always-on, the choice is between:

Platform Cost (rough) Pros Cons
Vercel Free tier covers serverless, but long-lived agents need Pro ($20/mo+) Sync API is already there; same deploy pipeline; familiar Serverless is awkward for long-lived agent runtimes; cold starts hurt A2A latency
Railway $5/mo for 1 service + $5 starter credit Persistent processes (good fit for Hermes runtime), good DX, fast deploys Smaller ecosystem than Vercel; lock-in to their platform
Fly.io $0–$5/mo for small instances Persistent, edge-deployed, generous free tier, good for long-lived processes Steeper config; community support thinner than Railway
Supabase Edge Functions Free tier reasonable Tight integration with the existing Sync DB Same serverless cold-start issue as Vercel

My read (without locking in until you've done hands-on Hermes A2A): Railway or Fly is the right shape because the orchestrator wants to be a long-lived process listening on a port. Serverless platforms (Vercel, Supabase Edge) fight that pattern. Cost difference is marginal at v1 scale.

Don't lock this in until L5 actually ships — the right answer may shift once we know how the runtime wants to be hosted.

Pre-L5 checklist

Before any L5 code/config:

  • [ ] Resolve open questions 1-6 above via hands-on Hermes A2A learning
  • [ ] Decide hosting target (this doc's decision matrix)
  • [ ] Land project_coordination_substrate_security ADR (per brief §8 "Before Layer 5") — Tash's manipulation/capture concern needs an answer before any external-facing surface goes live
  • [ ] Confirm L4 orchestrator runtime works locally (per setup.md §5 verification)
  • [ ] At least one F2 skill installed in the orchestrator that's worth exposing — A2A on a thin shell isn't useful; it just exposes what other agents can do already through the public Pulse MCP server. (When this trigger hits depends on ADR-046 revisit.)

What L5 unlocks (per brief)

  • ZHD GTM framing becomes coherent — orchestrator is addressable, has decision history (when ADR-039 ships), can recommend trust.
  • External agents in DAO ecosystems (Raid Guild, MetaClawTel) can directly query Sync's coherence/reputation surface.
  • The "Sync as company brain" thesis (per James's May 4 framing) becomes operational — other agents' personal DTAs can ask "what does the team usually decide for situations like this?" and get an answer routed through the orchestrator.