Agent management

Agent identity and local process lifecycle are separate:

• agent ... commands manage workspace identities and tokens.
• node agent ... commands manage broker-spawned CLI processes on this machine.

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_..."

Agent tokens are identity credentials, not workspace administration keys. See Authentication for the full token model.

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 reviewer

agent 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 node up --background

Spawn Local Agents

agent-relay node agent spawn codex --name reviewer --channels reviews --task "Review the docs."
agent-relay node agent spawn claude --name planner --channels planning reviews --model sonnet

spawn creates a local managed agent process under the running broker.

Spawn And Attach

agent-relay node agent new codex --name reviewer --mode drive --task "Review the docs."
agent-relay node agent new claude --name planner --mode passthrough

new spawns the agent, then opens an attach session (default mode drive).

Attach modes:

Drive mode uses out-of-band message controls so terminal control keys can pass through to the agent TUI:

agent-relay node agent message hold reviewer
agent-relay node agent message flush reviewer
agent-relay node agent message auto reviewer

hold 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 node agent list
agent-relay node tail
agent-relay node tail --agent reviewer
agent-relay node agent attach reviewer --mode view
agent-relay node agent attach reviewer --mode drive
agent-relay node agent attach reviewer --mode passthrough

node tail streams broker events or one agent's output stream. attach reconnects to a running agent without spawning a new one (default mode view).

Release Or Retarget

agent-relay node agent set-model reviewer gpt-5.5
agent-relay node agent release reviewer

set-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.

See Also