Skip to content

Configuration Reference

The hub’s Settings page is the primary configuration surface — email, alerts, webhooks, AI diagnosis, retention, and the status page are all editable there, hot-reloadable, and persisted to the hub’s SQLite database. Most users never need to touch an environment variable after the initial docker-compose.yml in the Quick Start.

The variables listed below are equivalent defaults for users who prefer declarative deployments (Docker Compose, Kubernetes, Ansible). For keys that appear both here and in the UI, the DB value wins.

VariableDefaultDescription
INSIGHTD_SMTP_HOST(none)SMTP server hostname
INSIGHTD_SMTP_PORT587SMTP port (587 for TLS, 465 for SSL)
INSIGHTD_SMTP_USER(none)SMTP username
INSIGHTD_SMTP_PASS(none)SMTP password or app password
INSIGHTD_SMTP_FROM(from user)From address for emails
VariableDefaultDescription
INSIGHTD_DIGEST_TO(none)Recipient email for weekly digest
INSIGHTD_DIGEST_CRON0 8 * * 1Digest schedule (Monday 8am)
TZUTCTimezone for cron schedules
VariableDefaultDescription
INSIGHTD_ALERTS_ENABLEDfalseEnable real-time alerts
INSIGHTD_ALERTS_TO(digest recipient)Alert email recipient
INSIGHTD_ALERT_COOLDOWN60Minutes between the first reminders for a persistent alert. With backoff on, this is the base — each subsequent reminder doubles the gap.
INSIGHTD_ALERT_REMINDER_BACKOFFtrueSlow down reminders for long-lived alerts. Each reminder doubles the previous gap (60m → 2h → 4h → 8h → …) until the cap. Prevents the inbox from filling with the same alert.
INSIGHTD_ALERT_REMINDER_MAX1440Upper bound on the gap between reminders, in minutes. Default 1440 = once per day.
INSIGHTD_ALERT_DOWNtrueAlert on container down
INSIGHTD_ALERT_CPU90Container CPU threshold (%)
INSIGHTD_ALERT_MEMORY0Container memory threshold (MB, 0=disabled)
INSIGHTD_ALERT_RESTART3Restart count in 30min window
INSIGHTD_ALERT_UNHEALTHYtrueAlert on unhealthy containers
INSIGHTD_ALERT_HOST_CPU90Host CPU threshold (%)
INSIGHTD_ALERT_HOST_MEMORY0Host low memory threshold (MB, 0=disabled)
INSIGHTD_ALERT_LOAD0Host load threshold (0=disabled)
INSIGHTD_ALERT_DISK90Disk usage threshold (%)
INSIGHTD_ALERT_EXCLUDE(none)Exclude containers from alerts (comma-separated globs, e.g. dev-*,test-*)
INSIGHTD_ALERT_ENDPOINT_DOWNtrueAlert when HTTP endpoints go down
INSIGHTD_ALERT_ENDPOINT_FAILURES3Consecutive failures before alerting
VariableDefaultDescription
INSIGHTD_WEB_ENABLEDtrueEnable the web UI
INSIGHTD_WEB_PORT3000Web UI port
INSIGHTD_WEB_HOST0.0.0.0Bind address
INSIGHTD_ADMIN_PASSWORD(none)Admin password for settings/webhooks
INSIGHTD_EXTERNAL_HOST(auto)Hostname shown in agent setup commands
INSIGHTD_WEB_BASE_URL(none)Public hub URL used in email links (e.g. https://insightd.example.com). Also editable from Settings → Web. Emails render fine unset; the “Open dashboard” buttons just disappear.
INSIGHTD_STATUS_PAGEfalseEnable public status page at /status (no auth)
VariableDefaultDescription
INSIGHTD_MQTT_URL(none)MQTT broker URL (enables hub mode)
INSIGHTD_MQTT_USER(none)MQTT username
INSIGHTD_MQTT_PASS(none)MQTT password
INSIGHTD_HOST_IDlocalHost identifier (falls back to NODE_NAME in k8s mode)
VariableDefaultDescription
INSIGHTD_RUNTIMEautoContainer runtime: auto, docker, kubernetes, or proxmox
INSIGHTD_ALLOW_ACTIONSfalseEnable container start/stop/restart from UI (Docker + Proxmox VE; no-op on Kubernetes)
INSIGHTD_ALLOW_UPDATESfalseEnable remote agent self-updates (Docker only)
VariableDefaultDescription
INSIGHTD_HOST_GROUP(none)Optional logical group label (e.g. production-cluster, basement). Surfaces as collapsible sections on the Hosts page. The agent reports its group; a manual override on the Hosts page detail (PUT /api/hosts/:id/group) always wins over the env var.

The container detail page has a “Diagnose with AI” button that sends the diagnosis context (metrics, baselines, restart history, log signals) to Google Gemini and persists the response. Disabled by default — set the API key to enable it. All settings are also available on Settings → AI Diagnosis in the web UI.

VariableDefaultDescription
GEMINI_API_KEY(none)Google Gemini API key. Free tier is sufficient. Get one at aistudio.google.com/apikey.
GEMINI_MODELgemini-2.5-flashModel name. Default is the free, fast model. gemini-2.0-flash is also free but returns limit: 0 on new AI Studio projects.
GEMINI_TIMEOUT_MS20000Abort the Gemini request after this many milliseconds.

Cache hits via sha256(context) + 24h TTL avoid duplicate requests. Rate limit responses (429) surface in the UI with a live cooldown countdown.

VariableDefaultDescription
NODE_NAME(none)Required — node name (set via downward API in DaemonSet)
NODE_IP(none)Node IP, used to build kubelet URL (set via downward API)
INSIGHTD_KUBELET_URLhttps://${NODE_IP}:10250Override the kubelet endpoint URL

When INSIGHTD_PVE_API_URL is set, the Proxmox runtime talks to PVE over HTTPS instead of shelling local pvesh. See the Proxmox VE setup guide for the full walkthrough.

VariableDefaultDescription
INSIGHTD_PVE_API_URL(none)https://hostname:8006. Presence selects REST mode.
INSIGHTD_PVE_TOKEN_ID(none)Token id, format user@realm!tokenid.
INSIGHTD_PVE_TOKEN_SECRET(none)Token secret PVE shows once on creation.
INSIGHTD_PVE_NODE(none)PVE node this agent monitors. Required in REST mode (one process per node).
INSIGHTD_PVE_VERIFY_TLSfalseDefault off — most PVE installs use the auto-generated self-signed cert.
INSIGHTD_PVE_CA_BUNDLE(none)Path to PEM CA bundle, only consulted when INSIGHTD_PVE_VERIFY_TLS=true.

Identity bridge (in-guest agent → hypervisor view)

Section titled “Identity bridge (in-guest agent → hypervisor view)”

Set on an in-guest agent (NOT on the agent talking to PVE) to cross-link the two views in the UI.

VariableDefaultDescription
INSIGHTD_PROXMOX_NODE(none)The PVE node name this VM lives on. Must be set together with INSIGHTD_PROXMOX_VMID.
INSIGHTD_PROXMOX_VMID(none)The VMID PVE assigned to this VM. Must be set together with INSIGHTD_PROXMOX_NODE.
VariableDefaultDescription
INSIGHTD_ALLOW_ACTIONSfalseEnable start/stop/restart/remove from the UI
INSIGHTD_ALLOW_UPDATESfalseEnable remote agent updates from the hub
VariableDefaultDescription
INSIGHTD_STATUS_PAGEfalseEnable public status page at /status
INSIGHTD_STATUS_PAGE_TITLESystem StatusTitle shown on the public status page
VariableDefaultDescription
INSIGHTD_COLLECT_INTERVAL5Minutes between collection cycles
INSIGHTD_DISK_WARN_THRESHOLD85Disk warning threshold (%)
VariableDefaultDescription
INSIGHTD_RETENTION_RAW_DAYS30Days to keep full-resolution snapshots (min 7). Older raw data is rolled up into hourly aggregates before deletion.
INSIGHTD_RETENTION_ROLLUP_DAYS365Days to keep hourly rollups (min 30). Rollups give you long-term trends without unbounded growth.
VariableDefaultDescription
INSIGHTD_LOG_LINES100Default log lines to fetch
INSIGHTD_LOG_MAX_LINES1000Maximum log lines (agent-side cap)
INSIGHTD_LOG_TIMEOUT15000MQTT log request timeout (ms)
VariableDefaultDescription
INSIGHTD_DATA_DIR/dataDatabase storage directory
INSIGHTD_HOST_ROOT/hostHost filesystem mount point
DOCKER_HOST/var/run/docker.sockDocker socket path
VariableDefaultDescription
INSIGHTD_UPDATE_CHECK_CRON0 3 * * *Daily image update check schedule