Skip to content

Agent Management

The Finch service manages agents through a gRPC API backed by a SQLite database. Each agent has a unique RID generated at registration time and stored alongside its configuration.

For API details, see the Finch protocol buffer definition.

Lifecycle

register → [deploy] → [edit] → [config] → deregister

  1. Register - finchctl agent register. Finch validates the request (hostname required, at least one log source required), creates a database record, and returns the agent's configuration.

  2. Deploy - finchctl agent deploy uses the generated config file to install and start Alloy on the agent host via SSH.

  3. Edit - finchctl agent edit. Only log sources, metrics, profiles, and labels can be changed; hostname and node type are immutable.

  4. Config - finchctl agent config. Finch generates and returns a fresh Alloy configuration with a new 365-day JWT. This is used both for initial deployment and for token renewal.

  5. Deregister - finchctl agent deregister. Finch deletes the database record. The agent's JWT is rejected on the next write attempt (RID no longer exists in the database).

Agent record

Each agent stores the following fields in the database:

Field Notes
rid Resource identifier, generated at registration
hostname Set at registration, immutable
node unix or windows, set at registration, immutable
log_sources URIs: journal://, docker://, file://<path>, event://<channel>
metrics Boolean
metrics_targets List of Prometheus scrape URLs
profiles Boolean
labels List of key=value strings
created_at Registration timestamp

Real-time events

The database model publishes agent events (register, update, deregister) to subscribers via an in-process channel. The dashboard WebSocket server subscribes to this channel and pushes live updates to connected browsers whenever the agent list changes.