Dashboard¶
The Finch web dashboard is a real-time HTML interface for monitoring enrolled agents, their configurations and creating additional access tokens.
Opening the dashboard¶
Generate a short-lived access token and open the dashboard URL:
The command prints the token and the login URL. Open the URL in a browser and
paste the token, or use --web to have finchctl open the browser directly:
Session options¶
| Flag | Default | Description |
|---|---|---|
--permission.role |
viewer |
RBAC role: admin, operator, or viewer |
--permission.scope |
(all agents) | Limit visibility to specific agent RIDs or hostnames |
--permission.session-timeout |
1800 |
Session duration in seconds |
RBAC roles¶
| Capability | viewer |
operator |
admin |
|---|---|---|---|
| View agent list and details | ✓ | ✓ | ✓ |
| View agent JWT | ✗ | ✓ | ✓ |
| Download agent config file | ✗ | ✗ | ✓ |
The role is embedded in the dashboard JWT and enforced server-side on every
WebSocket message. For example a viewer cannot escalate by sending a
get_token message, the server checks the dashboard token before responding.
Scope¶
The scope field restricts which agents the session user can see. An empty
scope (the default) grants access to all agents.
# Grant access to two specific agents only
finchctl service dashboard \
--permission.scope rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
--permission.scope web-02 \
finch.example.com
Scope is checked server-side using, agents not matching any scope entry are hidden from the list, stats, and token / config actions.
What the dashboard shows¶
- Stats panel - total agents, agents with metrics enabled, agents with profiles enabled
- Endpoints panel - Grafana, Loki, Mimir, and Pyroscope URLs for the service
- Agent list - paginated (5 per page), searchable by hostname, RID, or label
- Per agent: RID, hostname, log sources, metrics, profiles, labels, registration date
- Actions (subject to role): view token, download config file
Real-time updates¶
The dashboard uses a WebSocket connection for live data. The server pushes updates whenever an agent is registered, edited, or deregistered, no page refresh is needed. The WebSocket is also used for on-demand actions like fetching a token or downloading a config.
The WebSocket validates the session token on a 30-second ticker. If the token expires while the dashboard is open, the connection is closed with a normal closure and the browser is redirected to the login page.