The dashboard is a web UI compiled into the gc binary for monitoring
convoys, agents, mail, rigs, sessions, and events in real time.
Prerequisites
The dashboard is a separate web server. It needs a GC API server to talk to, but it no longer has to be launched from inside a city directory.
Standalone city mode
If you are using gc start without the machine-wide supervisor, the dashboard
talks to that city's own API server. This [api] config is only consulted in
standalone mode — if the machine-wide supervisor is running, it takes over
(see Supervisor mode below) and this per-city port is ignored. Ensure the
city API is enabled in city.toml:
[api]
port = 9443
Then start the city normally with gc start. The API server starts with the
controller on that port.
Supervisor mode
If you are using the machine-wide supervisor, the dashboard talks to the supervisor API instead. The default supervisor API address is:
http://127.0.0.1:8372
In this mode, per-city [api] ports are ignored. The dashboard detects
supervisor mode automatically via /v0/cities, enables a city selector, and
routes requests through /v0/city/{name}/....
Starting the dashboard
gc dashboard # Auto-discover API server, open dashboard in browser
gc dashboard --no-open # Print the dashboard URL instead of opening a browser
gc dashboard serve # Print where the web dashboard is served
gc dashboard --city /path/to/city # Optional city context for standalone discovery
gc dashboard --api http://127.0.0.1:8372 # Optional override
gc dashboard auto-discovers the right API server in this order:
- Supervisor-managed city: uses the machine supervisor API and defaults the UI to the supervisor view. Pick a city in the UI.
- Standalone city context: uses that city's configured
[api]listener. - No city context: if the machine supervisor is running, uses the supervisor API and shows supervisor-level state.
The --api flag remains available as an override for non-standard setups.
Features
The dashboard provides:
- Convoys — progress tracking, tracked issues, create new convoys
- Crew — named worker status with activity detection
- Polecats — ephemeral worker activity and work status
- Activity timeline — categorized event feed with filters
- Mail — inbox with threading, compose, and all-traffic view
- Merge queue — open PRs with CI and mergeable status
- Escalations — priority-colored escalation list
- Ready work — items available for assignment
- Health — system heartbeat and agent counts
- Issues — backlog with priority, age, labels, assignment
- Command palette (Cmd+K) — execute gc commands from the browser
Real-time updates via SSE (Server-Sent Events) from the API server.