Glossary¶

Definitions for abbreviations and technical terms used throughout this documentation.

ACME - Automatic Certificate Management Environment. A protocol for automating TLS certificate issuance and renewal. Finch uses Traefik's built-in ACME client to obtain certificates from Let's Encrypt when --service.letsencrypt is enabled.

API - Application Programming Interface. A defined set of operations that one piece of software exposes for others to call. The Finch service exposes a gRPC API used by finchctl.

CA - Certificate Authority. An entity that issues and signs digital certificates. In Finch, a dedicated CA is generated per deployment during service deploy. Only the CA certificate is uploaded to the server; the CA private key is discarded immediately after signing.

CLI - Command-Line Interface. A text-based tool operated from a terminal. finchctl is the CLI for managing the Finch stack and enrolled agents.

CRL - Certificate Revocation List. A published list of certificates that have been revoked before their expiry date. Finch does not use CRLs - revoking access is handled by deregistering the agent or finchctl client, which removes the corresponding record or CA file immediately.

DNS - Domain Name System. The system that maps hostnames (e.g. finch.example.com) to IP addresses. A valid DNS record pointing to the server is required for Let's Encrypt certificate issuance.

ECDSA - Elliptic Curve Digital Signature Algorithm. A public-key cryptography algorithm. Finch generates ECDSA P-256 key pairs for mTLS client certificates.

gRPC - Google Remote Procedure Call. A high-performance, HTTP/2-based RPC framework using Protocol Buffers for message serialisation. finchctl communicates with the Finch service over gRPC, secured by mTLS.

HMAC - Hash-based Message Authentication Code. A method for verifying message integrity and authenticity using a shared secret and a hash function. Finch signs agent JWT with HMAC-SHA256 using the stack's signing secret.

HTTP / HTTPS - Hypertext Transfer Protocol / Hypertext Transfer Protocol Secure. The protocol used for web traffic. Finch redirects all HTTP (port 80) traffic to HTTPS (port 443). Agent data is pushed over HTTPS; the dashboard is served over HTTPS.

JWT - JSON Web Token. A compact, self-contained token format for transmitting claims between parties, signed to prevent tampering. Finch issues two kinds of JWT: agent tokens (365-day, HMAC-SHA256, used by Alloy to authenticate data writes) and dashboard tokens (short-lived, used for browser access).

mTLS - Mutual Transport Layer Security. A TLS handshake in which both the server and the client present certificates, authenticating each other. finchctl uses mTLS to authenticate to the Finch gRPC service. Standard TLS (one-way) is used for all other connections.

OCSP - Online Certificate Status Protocol. A protocol for checking whether a certificate has been revoked, as an alternative to CRLs. Finch does not use OCSP - see CRL above.

PEM - Privacy Enhanced Mail. A Base64-encoded format for storing cryptographic objects such as certificates and private keys, delimited by -----BEGIN ...----- / -----END ...----- headers. Finch stores mTLS certificates in PEM format in ~/.config/finch.json and in traefik/etc/certs.d/.

RBAC - Role-Based Access Control. A model for restricting system access based on assigned roles. The Finch dashboard supports three roles: viewer, operator, and admin. See Dashboard: RBAC roles.

RID - Resource Identifier. A Finch-specific unique identifier assigned to each registered agent at enrolment time (e.g. rid:abc123). The RID is embedded in the agent's JWT and checked on every data write, enabling immediate token revocation by deregistering the agent.

RPC - Remote Procedure Call. A mechanism for a program to execute a function on a remote server as if it were a local call. The Finch gRPC API exposes RPCs for agent and dashboard management.

SSH - Secure Shell. An encrypted network protocol for remote command execution and file transfer. finchctl uses SSH for all deployment operations (service deploy, service update, service teardown, agent deploy, agent teardown, service rotate-certificate, service rotate-secret). SSH is not used at runtime.

TLS - Transport Layer Security. The cryptographic protocol that secures network connections. Traefik terminates TLS for all incoming connections on port 443. See also mTLS.

URL - Uniform Resource Locator. A reference to a resource on a network, including the scheme, host, and path (e.g. https://finch.example.com/grafana). SSH targets in finchctl are also expressed as URLs (user@host:port).

WAL - Write-Ahead Log. A data durability mechanism in which changes are written to a sequential log before being applied to the main storage. Alloy uses a WAL to buffer telemetry locally during network outages or token invalidation, allowing data to be flushed once the agent reconnects.