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 upnode 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:
| Flag | Description |
|---|---|
--spawn | Force auto-spawn from teams.json, regardless of its autoSpawn setting. |
--no-spawn | Start only the broker. |
--background | Detach and leave the broker running. The default is to stay attached to this terminal. |
--config <file> | Node definition file to serve. Defaults to an auto-discovered agent-relay.{ts,tsx,mts,cts,js,mjs,cjs}. |
--workspace-key <key> | Join a pre-existing Relay workspace. |
--state-dir <path> | Write runtime state outside .agentworkforce/relay/. |
--broker-name <name> | Override the broker identity. Defaults to the project directory basename. |
--verbose | Enable verbose startup logging (raises the node log level to debug). |
--log-file <path> | Write structured node logs — each capability registered and every action invoked/completed — to a file. |
--log-level <level> | Node log verbosity: debug | info | warn | error (default info). |
--log-json | Emit node logs as JSON lines instead of text. |
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.
Check Status
agent-relay node status
agent-relay node status --wait-for 10
agent-relay statusnode 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 reviewerMetrics 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-stagingUpdate 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-datauninstall can remove local runtime files, config, and global binaries. Run --dry-run before destructive cleanup.