Broker lifecycle

The core product is workspace messaging. The local broker is optional: use it when this machine should run managed CLI agents or attach to PTY/headless sessions.

Broker commands live under agent-relay node. (local is a deprecated alias that prints a warning.)

Start The Broker

agent-relay node up

node up starts the broker in the foreground, serves this machine as a fleet node, and — when a teams.json with autoSpawn exists — spawns the configured agents into #general.

Flags:

The --log-* flags govern the fleet node this broker serves; see Nodes → Watch what a node is doing. Without one, the node stays quiet and surfaces only warnings.

For local agent work, the common shape is:

agent-relay node up --background --workspace-key "$RELAY_WORKSPACE_KEY"

The broker listens on a local API port starting from 3888 (override with AGENT_RELAY_BROKER_PORT). If this machine was enrolled as a Cloud-managed node with agent-relay cloud enroll, node up picks up the persisted enrollment automatically and serves under the enrolled node name.

One broker per enrolled node

An enrolled node has one Cloud delivery socket. If two brokers served the same node id, the second registration would evict the first broker's socket and it would silently stop receiving messages. node up prevents this with a machine-local claim in ~/.agentworkforce/relay/node-claims/: the first broker claims its enrolled node id, and a later node up for that node — including one pinned with RELAY_NODE_ID — refuses and names the holding broker's pid and state directory.

If the refusal is wrong, or you want the takeover:

agent-relay node down --state-dir <holder's state dir>   # stop the running broker
agent-relay node up --workspace-key <different key>       # serve a different enrolled node
agent-relay node up --force                               # take the node over anyway

--force evicts the incumbent's delivery socket: the old broker keeps running but stops receiving realtime delivery. A crashed broker's stale claim never blocks a restart, --local-only claims nothing, and node down releases the claim on clean exit.

Check Status

agent-relay node status
agent-relay node status --wait-for 10
agent-relay status

node status only checks the local broker daemon; --wait-for <seconds> polls until the broker is ready or the timeout expires. The top-level status command reports workspace, local broker state, and cloud login state.

Metrics

agent-relay node metrics
agent-relay node metrics --agent reviewer

Metrics show local broker and agent resource usage.

Stop The Broker

agent-relay node down
agent-relay node down --timeout 10000
agent-relay node down --force

--timeout <ms> bounds the graceful shutdown wait (default 5000). Use --force for stale state or stuck processes. Use --all only when intentionally cleaning up every agent-relay process on the machine.

State Directory

By default, local runtime state is written under .agentworkforce/relay/ in the project. That directory stores connection metadata that attach commands use to find the running broker.

Use --state-dir when a project needs isolated runtime files:

agent-relay node up --state-dir .agentworkforce/relay-staging
agent-relay node agent attach reviewer --state-dir .agentworkforce/relay-staging
agent-relay node down --state-dir .agentworkforce/relay-staging

Update And Uninstall

These commands manage the installed CLI, not a workspace:

agent-relay update --check
agent-relay update
agent-relay uninstall --dry-run
agent-relay uninstall --keep-data

uninstall can remove local runtime files, config, and global binaries. Run --dry-run before destructive cleanup.

See Also