The version 8 core product is workspace messaging. The local broker is optional: use it when this machine should run managed CLI agents, expose a local dashboard, or attach to PTY/headless sessions.
Broker commands live under agent-relay local.
Start The Broker
agent-relay local upUseful flags:
| Flag | Description |
|---|---|
--no-dashboard | Start the broker without the web dashboard. |
--port <port> | Dashboard port. The broker API uses the next available port. |
--spawn | Force auto-spawn from local team config. |
--no-spawn | Start only the broker. |
--background | Detach and leave the broker running. |
--foreground | Keep a no-dashboard broker attached to this terminal. |
--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. |
--verbose | Enable verbose startup logging. |
For local agent work, the common shape is:
agent-relay local up --background --workspace-key "$RELAY_WORKSPACE_KEY"Check Status
agent-relay local status
agent-relay local status --wait-for 10
agent-relay statuslocal status only checks the local broker daemon. The top-level status command reports project path, local broker state, and cloud login state.
Metrics
agent-relay local metrics
agent-relay local metrics --agent reviewerMetrics show local broker and agent resource usage.
Stop The Broker
agent-relay local down
agent-relay local down --timeout 10000
agent-relay local down --forceUse --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 local up --state-dir .agentworkforce/relay-staging
agent-relay local agent attach reviewer --state-dir .agentworkforce/relay-staging
agent-relay local 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.