Configuration Reference

Configuration Reference

This page lists the important Trove environment variables.

Server variables

Variable	Default	Purpose
TROVE_DB	depends on install	SQLite database path.
TROVE_ADDR	:8080	HTTP listen address.
TROVE_BOOTSTRAP_AGENT	empty	Optional first agent name to seed.
TROVE_BOOTSTRAP_TOKEN	empty	Optional first agent token to seed.
TROVE_EVENT_RETENTION	720h	How long events are kept.
TROVE_REMOVED_RETENTION	24h	How long removed services remain before pruning.

Authentication variables

See Authentication for the full OIDC flow, Authentik setup, logout behaviour, and verification commands.

Variable	Default	Purpose
TROVE_OIDC_ISSUER	empty	OIDC issuer/discovery URL. Enables dashboard/read API auth when set with the other required OIDC values.
TROVE_OIDC_CLIENT_ID	empty	OAuth2/OIDC client ID.
TROVE_OIDC_CLIENT_SECRET	empty	OAuth2/OIDC client secret. Also signs Trove's local session cookie.
TROVE_OIDC_REDIRECT_URL	empty	Callback URL, for example https://trove.example.com/oauth2/callback.
TROVE_API_TOKEN	empty	Optional bearer token for scripts querying read APIs without a browser OIDC session.
TROVE_OIDC_SESSION_MAX_AGE	8h	Dashboard session lifetime. Uses Go duration syntax.

Freshness variables

Variable	Default	Purpose
TROVE_FRESHNESS_ENABLED	true	Enable/disable registry freshness checks.
TROVE_FRESHNESS_INTERVAL	5m	Scan cadence for due images.
TROVE_FRESHNESS_TTL	6h	Recheck interval after successful digest lookup.
TROVE_REGISTRY_AUTHS	empty	JSON map of registry credentials.

Alert variables

Variable	Default	Purpose
TROVE_ALERT_WEBHOOK_URL	empty	Generic JSON webhook.
TROVE_ALERT_WEBHOOK_SECRET	empty	Optional HMAC-SHA256 secret for signing generic webhook requests.
TROVE_ALERT_DISCORD_URL	empty	Discord webhook.
TROVE_ALERT_NTFY_URL	empty	ntfy endpoint/topic URL.
TROVE_ALERT_NTFY_TOKEN	empty	ntfy bearer token.
TROVE_ALERT_EVENTS	all	Comma-separated event kinds to alert on.
TROVE_ALERT_COOLDOWN	5m	Per-incident cooldown.

Digest and SMTP variables

Variable	Default	Purpose
TROVE_SMTP_HOST	empty	SMTP host. Required for digest.
TROVE_SMTP_PORT	587	SMTP port. 465 uses implicit TLS; other ports use STARTTLS.
TROVE_SMTP_USERNAME	empty	SMTP username.
TROVE_SMTP_PASSWORD	empty	SMTP password/app password.
TROVE_SMTP_FROM	empty	From address. Required for digest.
TROVE_SMTP_TO	empty	Recipient list. Required for digest.
TROVE_DIGEST	daily@08:00	Digest schedule such as daily@08:00, weekly@mon:08:00, or off. It only sends when SMTP host/from/to are configured.

Common agent variables

Variable	Default	Purpose
TROVE_SERVER_URL	required	Base URL of Trove server.
TROVE_TOKEN	required	Trove agent token.
TROVE_INTERVAL	30s	Push interval.
TROVE_AGENT_NAME	hostname	Name inside the report envelope. The dashboard agent name comes from agent create; for the local agent this also becomes the reported host name.

Docker agent variables

Variable	Default	Purpose
DOCKER_HOST	unix:///var/run/docker.sock	Docker Engine endpoint.

Proxmox agent variables

Variable	Default	Purpose
TROVE_PROXMOX_URL	required	Proxmox API base URL.
TROVE_PROXMOX_TOKEN	required	Proxmox API token.
TROVE_PROXMOX_INSECURE	false	Skip TLS verification for self-signed Proxmox certs.

Kubernetes agent variables

Variable	Default	Purpose
TROVE_CLUSTER_NAME	kubernetes	Reported host name for the cluster.
TROVE_KUBE_NAMESPACE	all namespaces	Restrict discovery to one namespace.
TROVE_KUBE_APISERVER	in-cluster API	API server URL for out-of-cluster use.
TROVE_KUBE_TOKEN	service-account token	Kubernetes API bearer token for out-of-cluster use.
TROVE_KUBE_CA	service-account CA	CA file for the Kubernetes API.
TROVE_KUBE_INSECURE	false	Skip Kubernetes API TLS verification. Use only for controlled test environments.

Local agent variables

Variable	Default	Purpose
TROVE_LOCAL_UNIT_FILTER	all	Glob for units to include, such as nginx* or docker.service.
TROVE_LOCAL_ALL	false	Include inactive units as well as active, activating, and failed units.

Where variables must go

Set variables on the process that needs them.

Server variables must reach trove-server.

Agent variables must reach the specific agent process.

For Docker Compose, put variables under the service's environment: or in the .env file used by that Compose file.

For systemd, put them in the service's EnvironmentFile and restart the unit.