Configuration reference

helmsight reads one TOML file. The first of these is used:

1. --config <path>
2. $HELMSIGHT_CONFIG
3. /etc/helmsight/helmsight.toml
4. ./helmsight.toml

Türkçe sürüm

examples/helmsight.toml is a commented example of every option. Validate a file with helmsight config check; errors show the file, line, column and key:

error: helmsight.toml:23:1: `hosts[1].name`: duplicate host name `web-1`
error: helmsight.toml:41:8: `alerts.rules[0].expr`: unknown operator `=>` (use > >= < <= == !=)

Unknown keys are errors, so typos never pass silently.

Durations are strings such as "500ms", "30s", "5m", "1h30m", "7d", "2w" (ms milliseconds, s seconds, m minutes, h hours, d days, w weeks).

Secrets may be literal strings, but references are preferred:

env: works well with systemd’s EnvironmentFile= or container environment variables, and file: with Docker or Kubernetes secret files (/run/secrets/...).

Changes to the configuration take effect after a restart.

A complete example

# Top-level keys must come before any [section] header.
hosts_file = "hosts.toml"

[server]
listen = "127.0.0.1:8080"
data_dir = "/var/lib/helmsight"
public_url = "https://monitor.example.com"
trusted_proxies = ["127.0.0.1"]

[auth]
require_totp_for_admins = true

[ssh]
user = "monitor"
identity_files = ["/etc/helmsight/id_ed25519"]

[[alerts.rules]]
id = "disk-full"
expr = "disk_used_pct > 90 for 10m"
severity = "critical"

[[notify]]
id = "ops"
type = "slack"
url = "secret:slack-webhook"

[[certs]]
endpoint = "www.example.com:443"

In TOML, every key written after a [section] header belongs to that section. Write top-level keys such as hosts_file at the very top of the file; in the wrong place, config check reports them as unknown keys.

[server]

trusted_proxies matters for identifying clients correctly: sign-in rate limiting works per client address. Behind a proxy without this setting, every user appears to come from the proxy’s address.

[server.tls]

With a Let’s Encrypt certificate, point cert at fullchain.pem and key at privkey.pem, and restart helmsight after renewal (for example with certbot’s --deploy-hook).

[auth]

[auth.oidc]

Register <public_url>/api/v1/auth/oidc/callback as the redirect URI. Roles are updated from the claim at every sign-in, so changing a user’s groups at the identity provider changes their role at their next sign-in.

Example (Keycloak):

[auth.oidc]
issuer = "https://sso.example.com/realms/ops"
client_id = "helmsight"
client_secret = "secret:oidc"
role_claim = "realm_access.roles"
role_map = { "helmsight-admin" = "admin", "sre" = "operator", "dev" = "viewer" }
label = "Sign in with company account"

Keeping a local administrator account for emergencies is recommended; use disable_local_login with care so that you do not lose access to the UI when SSO is down.

[ssh]

[collect]

Failed hosts are retried with backoff: exponential up to 5 minutes when unreachable, 1 to 5 minutes after authentication failures (to avoid triggering intrusion prevention) and every minute for host key problems.

Lowering interval increases chart resolution, but also increases the load on the hosts and the database proportionally. For large fleets, 10 to 15 seconds is a reasonable starting point.

[retention]

Charts pick the finest resolution that covers the requested range. Longer retention grows the database proportionally. Expired data is deleted automatically every hour; rollups are computed every minute.

Hosts

[[hosts]]

hosts_file

A top-level hosts_file = "hosts.toml" loads additional [[hosts]] from another file (relative to the configuration file).

[ssh_config_import]

HostName, User, Port and IdentityFile are honoured, with OpenSSH “first value wins” semantics across matching Host blocks. Explicit [[hosts]] with the same name take precedence. Hosts with ProxyJump are skipped with a warning; Match and Include are not evaluated.

Alerts

[alerts]

Built-in rules: host_unreachable (critical; also for authentication failures), host_key_changed (critical), host_key_unknown (warning), failed_units (warning, one alert per unit), cert_expiry (warning or critical by days left; warning when the check fails).

[[alerts.rules]]

Operators: >, >=, <, <=, ==, !=. Thresholds accept the suffixes K, M, G, T (powers of 1000) and Ki, Mi, Gi, Ti (powers of 1024). Per-instance metrics produce one alert per instance (for example per mount point). While a host is unreachable, its metric alerts keep their state instead of resolving.

Metrics available to rules

[[notify]]

Notifications are sent when an alert fires, when it resolves (if the firing notification was sent) and as reminders. Silenced alerts are recorded but not notified. Failed deliveries are retried three times and listed with the alert. Send a test from the API: POST /api/v1/notify/<id>/test.

Webhook payload:

{
  "version": 1,
  "source": "helmsight",
  "status": "firing",
  "alert": {
    "id": 42,
    "rule": "disk-full",
    "host": "web-1",
    "instance": "/var",
    "severity": "critical",
    "summary": "disk_used_pct on /var is 93.1% (> 90.0%)",
    "value": 93.1,
    "started_at": "2026-09-30T16:56:12Z",
    "resolved_at": null,
    "acknowledged_by": null
  },
  "url": "https://monitor.example.com/alerts?id=42"
}

status is firing, resolved, reminder or test.

[[certs]]

The certificate is read even when it does not validate; trust problems are shown separately from connection failures. Checks run from the helmsight server, so only endpoints that helmsight can reach can be checked.

[[actions]]

[prometheus]

scrape_configs:
  - job_name: helmsight
    scheme: https
    authorization:
      credentials_file: /etc/prometheus/helmsight.token
    static_configs:
      - targets: ["monitor.example.com"]

Exposed metrics are prefixed with helmsight_: host_up, host_alerts_firing, cpu_percent{mode}, memory_*_bytes, load1/5/15, filesystem_{size,used,avail}_bytes{mount}, disk_{read,written}_bytes_per_second{device}, network_{receive,transmit}_bytes_per_second{interface}, tcp_connections{state}, pending_updates, pending_security_updates, reboot_required and more, all labelled with host.

Command line

Global options: --config <path>, --data-dir <dir> (overrides server.data_dir; without a configuration file, commands use the local-mode default ~/.local/share/helmsight, or /var/lib/helmsight for root), --log-format text|json.

When no user exists, serve prints a one-time setup link (/setup#token=...) for creating the first administrator in the browser.

Environment variables

HTTP API

The web UI uses the same versioned JSON API under /api/v1. The OpenAPI document is served at /api/v1/openapi.json. Authenticate with the session cookie from POST /api/v1/auth/login; state-changing requests need the X-CSRF-Token header returned by GET /api/v1/auth/me. Live updates are available as server-sent events at /api/v1/events. Wall displays call /api/v1/display/state with Authorization: Bearer <display token>. /healthz returns ok without authentication.