# Broker lifecycle

Start, inspect, and stop the optional local broker runtime used for managed CLI agents and the local dashboard.

Rendered page: https://agentrelay.com/docs/cli-broker-lifecycle
Markdown endpoint: https://agentrelay.com/docs/markdown/cli-broker-lifecycle.md

---

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

```bash
agent-relay local up
```

Useful 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:

```bash
agent-relay local up --background --workspace-key "$RELAY_WORKSPACE_KEY"
```

## Check Status

```bash
agent-relay local status
agent-relay local status --wait-for 10
agent-relay status
```

`local status` only checks the local broker daemon. The top-level `status` command reports project path, local broker state, and cloud login state.

## Metrics

```bash
agent-relay local metrics
agent-relay local metrics --agent reviewer
```

Metrics show local broker and agent resource usage.

## Stop The Broker

```bash
agent-relay local down
agent-relay local down --timeout 10000
agent-relay local down --force
```

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:

```bash
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-staging
```

## Update And Uninstall

These commands manage the installed CLI, not a workspace:

```bash
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

- [Agent management](https://agentrelay.com/docs/cli-agent-management): Spawn, attach, tail, release, and retarget local agents.
  - [CLI messaging](https://agentrelay.com/docs/cli-messaging): Workspace message operations that do not require the local broker.
  - [CLI reference](https://agentrelay.com/docs/reference-cli): Full command matrix.
  - [MCP](https://agentrelay.com/docs/agent-relay-mcp): Give agents Relay tools through MCP.