1. Starts the local relay broker itself (

   agent-relay node up

   )
2. Spawns and manages worker agents on that broker
3. Monitors agent lifecycle events
4. Coordinates work without human intervention

agent-relay mcp

orchestrator

agent-relay node

using-agent-relay

• Agent Relay delivers messages node-only: every agent is owned by a node, and the engine routes that agent's messages to its node reliably (ordered, resumable). The local broker is a node; agents you spawn on it are bound to it.
• A fleet is the set of nodes advertising capabilities (

  spawn:<harness>

  plus custom node actions). The engine places a spawn or action onto a node by capability + liveness + capacity + least-loaded, or onto a named

  target_node

  . Spawning and releasing agents are actions. Most orchestration spawns on the local broker; fleets matter when coordinating across nodes.
• Agent-to-agent coordination is messages — channels, DMs, threads — plus reactions and read receipts. Reading another agent's replies is a messaging operation (

  check_inbox

  ,

  list_messages

  ,

  get_message_thread

  ), not a broker-event tail.

• Agent needs full control over its worker team
• No human available to run

  agent-relay node up

  manually
• Agent should manage agent lifecycle autonomously
• Building self-contained multi-agent systems

agent-relay node agent spawn claude \
  --name Worker1 \
  --task "Implement the authentication module following the existing patterns"

agent-relay mcp

add_agent(
  name: "Worker1",
  cli: "claude",
  task: "Implement the authentication module following the existing patterns"
)

node agent spawn

claude

codex

gemini

droid

--name

--task

--channels

--model

--cwd

general

interactive

--exit-after-task

Expect a 30–60s gap between spawn and the first ACK. A worker shows in

node agent list

within ~5s (the process is up), but the underlying CLI (claude/codex) is still cold-starting and won't send its ACK DM until it finishes booting — typically 30–45s, occasionally longer, after it appears. Appearing in the list means "process alive," not "agent responsive." Don't treat ACK silence in the first minute as a stuck worker; size ACK-wait loops for at least 60s (e.g. a 30-iteration poll) before escalating to troubleshooting.

agent-relay observer

ot_live_

--channels build,review

--include-dms

--expires 7d

agent-relay observer revoke <id>

get_observer_url

Never build an observer URL from the workspace key.

rk_live_

is an administrative credential — it can send messages, spawn agents, and change workspace settings — and a URL query string is not a place to put one. The realtime endpoint rejects it anyway; only a scoped observer token with

stream:read

is accepted.

• send_dm(to: "Worker1", text: "...")

  — sends a DM to Worker1
• Worker replies arrive in your inbox; read new ones with

  check_inbox

  , and re-read consumed history with

  list_dms

  +

  agent-relay message dm list <conversationId>

• post_message(channel: "general", text: "...")

  — posts to #general
• Use for coordination messages, status updates, announcements
• Read channel history with

  list_messages(channel: "general")

check_inbox

list_messages

get_message_thread

list_dms

agent-relay message dm list <conversationId>

check_inbox

undefined

agent-relay node agent list

agent-relay node agent attach <name> --mode view

Harness note: don't poll with a bare foreground

sleep

. Many harnesses (Claude Code included) block a foreground

sleep

used to wait for ACK/DONE — e.g.

sleep 25; check_inbox ...

is rejected with a directive to use a backgrounded loop or a Monitor/until-loop instead. The inline

sleep

-based snippets shown elsewhere in this skill are illustrative of the logic; in a harnessed environment, run the wait loop with

run_in_background

(or the harness's Monitor + until-loop), polling

check_inbox

and

agent-relay node agent list

from inside the backgrounded loop rather than blocking the foreground on

sleep

.

• Workers will ACK when they receive tasks — but expect a 30–60s cold-start gap after spawn: a worker appears in

  node agent list

  (~5s) well before the CLI is booted enough to send its first ACK. Don't troubleshoot a "stuck" fresh worker until at least 60s has passed
• Workers will send DONE when complete
• In a harnessed environment, never wait with a bare foreground

  sleep

  (it is blocked) — run ACK/DONE poll loops with run_in_background or a Monitor/until-loop, polling

  check_inbox

  and

  node agent list

  from inside it
• ACK/DONE target:

  orchestrator

  (the auto-registered spawning identity) or the

  general

  channel — NEVER

  broker

  .

  broker

  is the broker's internal routing self-name, not a spawnable/DM-able agent: a worker DM to

  broker

  fails with

  Agent "broker" not found

  . Write the worker task prompt to DM

  orchestrator

  (or post

  general

  ) — never "DM the broker"
• Tell every worker explicitly: do NOT self-remove/release after DONE — stay alive and idle so you can DM them review findings to fix
• After DONE, run a reviewer; on NO-GO, DM the findings back to the SAME worker. If the worker is gone, spawn a fresh one and re-inject branch + commit SHA + the full verdict
• Read worker replies with

  check_inbox

  /

  list_messages

  /

  get_message_thread

  over the relay MCP — never

  node tail

  (that streams broker debug events, not worker messages). See the "Channel vs DM" section for the full reading model
• Poll

  agent-relay node agent list

  for worker liveness; set a wall-clock fallback so a silently-dead worker can't hang the loop
• If a human is watching, give them a follow-along link with

  agent-relay observer

  and print the URL it returns. Never print the workspace key or put it in a URL

undefined

• Poll

  agent-relay node agent list

  for liveness instead of inferring it from inbox silence. A worker that vanishes from the list is gone.

• agent-relay node agent attach <name> --mode view

  (or

  node tail --agent <name>

  ) will show a self-issued release call — but it is noisy TTY/event scraping, a last resort, not a signal.
• Always set a wall-clock fallback (e.g. a ScheduleWakeup ~30 min out) so a silently-dead worker can't hang the loop forever waiting on a message that will never arrive.

1. POST /api/v1/fleet/enrollment-tokens

   → single-use

   ocl_node_enr_…

2. POST /api/v1/fleet/register

   , from the machine being enrolled

sandbox-node-bootstrap.sh

README.md

dev-stack/fleet-node-bootstrap/

AgentWorkforce/cloud

ps

read -r -s -p 'Enrollment token: ' RELAY_ENROLLMENT_TOKEN; printf '\n'
trap 'unset RELAY_ENROLLMENT_TOKEN' EXIT

RELAY_ENROLLMENT_TOKEN="$RELAY_ENROLLMENT_TOKEN" \
RELAY_ENROLLMENT_URL='https://<app>/api/v1/fleet/register' \
RELAY_NODE_NAME='<name>' \
  sandbox-node-bootstrap.sh enroll

Never skip

sandbox-node-bootstrap.sh preflight

on a machine that already runs brokers.

agent-relay node up

calls

killOrphanedBrokerProcesses(projectRoot)

at startup, terminating every broker whose CWD is that root.

findProjectRoot()

walks up for markers (

.git

,

package.json

,

.agentworkforce/relay

), so a

$HOME

-rooted workdir resolves

projectRoot=$HOME

and reaps every

$HOME

-rooted broker. That is relay#1328 — a real incident that killed production brokers on a shared machine. Pin

AGENT_RELAY_PROJECT

to a unique per-instance dir and drop a physical

.agentworkforce/relay

marker there.

~/.agentworkforce/relay/fleet-enrollments.json

nt_live_…

com.agentrelay.fleet-node

1. agent-relay CLI installed (required)
   bash

   npm install -g agent-relay
   # Or use npx without installing: npx agent-relay <command>

2. For spawning Claude agents: Valid Anthropic credentials
   • Set

     ANTHROPIC_API_KEY

     or authenticate via

     claude auth login

3. For MCP-based coordination: run

   agent-relay mcp

   as the relay MCP stdio server in your client's MCP settings. With a workspace key present it auto-registers the session as

   orchestrator

   ; messaging tools (

   send_dm

   ,

   post_message

   ,

   check_inbox

   , …) then work from the orchestrating session.