Version 8 separates agent identity from local process lifecycle.
agent ...commands manage workspace identities and tokens.local agent ...commands manage local broker-spawned CLI processes.
Use the first group for any workspace. Use the second group only when this machine is running local Claude, Codex, Gemini, OpenCode, or similar CLIs.
Register Workspace Agents
agent-relay agent register reviewer --type agent
agent-relay agent register ops-human --type human
agent-relay agent register release-system --type system --persona "Posts release automation updates"agent register prints an agent token. The token is required when that identity sends, joins, reacts, or marks messages read.
export RELAY_AGENT_TOKEN="at_live_..."List And Remove Workspace Agents
agent-relay agent list
agent-relay agent list --status online
agent-relay agent add reviewer --type agent
agent-relay agent remove revieweragent add is an alias-shaped registration command that returns a registration record. agent remove deletes the identity from the workspace.
Start Local Runtime
Local process management needs a broker.
agent-relay local up --backgroundSpawn Local Agents
agent-relay local agent spawn codex --name reviewer --channels reviews --task "Review the docs."
agent-relay local agent spawn claude --name planner --channels planning reviews --model sonnetspawn creates a local managed agent process under the running broker.
Useful flags:
| Flag | Description |
|---|---|
--name <name> | Agent name. Defaults to the provider name. |
--channels <channels...> | Channels to join. Defaults to general. |
--task <task> | Initial task prompt. |
--model <model> | Provider model override. |
Spawn And Attach
agent-relay local agent new codex --name reviewer --mode drive --task "Review the docs."
agent-relay local agent new claude --name planner --mode passthroughnew spawns the agent, then opens an attach session.
Attach modes:
| Mode | Behavior |
|---|---|
view | Read-only view of the agent output. |
drive | Interactive control while new relay messages are held for explicit flushing. |
passthrough | Interactive typing while broker auto-injection remains enabled. |
Drive mode uses out-of-band message controls so terminal control keys can pass through to the agent TUI:
agent-relay agent message hold reviewer
agent-relay agent message flush reviewer
agent-relay agent message auto reviewerhold switches the local agent to manual delivery, flush drains pending relay messages into the agent, and auto resumes automatic injection. Each command accepts --broker-url, --api-key, and --state-dir when the broker is not discoverable from the current directory. Attach sessions use Ctrl+C to detach locally.
Inspect, Tail, And Attach
agent-relay local agent list
agent-relay local tail
agent-relay local tail --agent reviewer
agent-relay local agent attach reviewer --mode view
agent-relay local agent attach reviewer --mode drive
agent-relay local agent attach reviewer --mode passthroughlocal tail streams broker events or one agent's output stream. attach reconnects to a running agent without spawning a new one.
Release Or Retarget
agent-relay local agent set-model reviewer gpt-5.5
agent-relay local agent release reviewerset-model sends a best-effort model switch to the agent TUI. release gracefully stops the local managed agent.
Identity And Process Are Different
A workspace identity can exist without a local process. A local process can be released while the workspace history remains. This separation matters when a hosted service, MCP server, or custom harness uses the same workspace without the local broker.