⚙️ Configuration Guide

Pulse uses a split-configuration model to ensure security and flexibility.

Guest metadata entries are keyed by the canonical guest ID format instance:node:vmid (for example, pve1:node1:100). Legacy dash-separated keys are migrated automatically.

All files are located in /etc/pulse/ (Systemd) or /data/ (Docker/Kubernetes) by default.

Path overrides:

• PULSE_DATA_DIR sets the base directory for system.json, encrypted files, and the bootstrap token.
• PULSE_METRICS_DB_PATH sets only the metrics SQLite database path. Use this for tmpfs-backed metrics history without moving secrets or config off the persistent data directory.

Multi-tenant layout:

• Default org uses the root data directory for backward compatibility.
• Non-default orgs store data under /orgs/<org-id>/.
• Migration may create /orgs/default/ and symlinks in the root data directory.

🔐 Authentication (.env)

This file controls access to Pulse. It is never exposed to the UI.

# /etc/pulse/.env

# Admin Credentials (bcrypt hashed; plain text auto-hashes on startup)
PULSE_AUTH_USER='admin'
PULSE_AUTH_PASS='\$2a\$12$...' 

# Docker Example
docker run -d \
  -e PULSE_AUTH_USER=admin \
  -e PULSE_AUTH_PASS=secret123 \
  rcourtman/pulse:latest

Note: API_TOKEN / API_TOKENS in .env are legacy and ignored at runtime in v6. Manage API tokens in the UI (api_tokens.json) for supported behavior.

🖥️ System Settings (system.json)

Controls runtime behavior like logging, polling intervals, and UI preferences. Legacy port fields in system.json are ignored; use FRONTEND_PORT instead.

{
  "pvePollingInterval": 10,       // Seconds
  "backendPort": 3000,            // Legacy (unused)
  "frontendPort": 7655,           // Legacy (ignored; use FRONTEND_PORT)
  "logLevel": "info",             // debug, info, warn, error
  "autoUpdateEnabled": false,     // Enable auto-update checks
  "adaptivePollingEnabled": false, // Smart polling for large clusters
  "allowedOrigins": "",           // CORS allowlist (single origin or "*")
  "allowEmbedding": false,        // Allow iframe embedding
  "allowedEmbedOrigins": "",      // Comma-separated origins for iframe embedding
  "webhookAllowedPrivateCIDRs": "" // Allowlist for private webhook targets
}

Supported system.json Keys

Numeric intervals are seconds unless noted otherwise.

discoveryConfig supports:

• environmentOverride, subnetAllowlist, subnetBlocklist
• maxHostsPerScan, maxConcurrent, enableReverseDns, scanGateways
• dialTimeoutMs, httpTimeoutMs

Common Overrides (Environment Variables)

Environment variables take precedence over system.json.

Log Levels

Tip: If your syslog is being flooded with Pulse messages, set LOG_LEVEL=warn to significantly reduce log volume while still capturing important events.

Split-Port Agent Ingest (Network Isolation)

By default Pulse serves the web UI, the REST API, and agent check-in together on FRONTEND_PORT. For deployments that expose Pulse to monitored hosts across an untrusted network (for example, a managed service provider whose clients' Proxmox nodes reach a central Pulse server over the internet), you can move agent check-in onto its own dedicated port and keep the web UI and management API on a separate, firewalled port.

Set PULSE_AGENT_INGEST_PORT to a port other than FRONTEND_PORT:

PULSE_AGENT_INGEST_PORT=7656

When enabled:

• The dedicated port serves only the agent-ingest routes (/api/agents/*). Every other path, including the web UI, login, and the management API, returns 404. A host that can reach the agent port cannot pivot to the management interface.
• The main FRONTEND_PORT listener is unchanged and still serves everything (including agent ingest), so existing single-port installs keep working. The dedicated listener is purely additive.
• The value is validated at startup: it must be between 1 and 65535 and must differ from FRONTEND_PORT and the HTTP redirect port. An invalid value is rejected.

Expose only PULSE_AGENT_INGEST_PORT to your monitored hosts and keep FRONTEND_PORT on a private network or behind your firewall/VPN. Point agents at the dedicated port by setting PULSE_AGENT_CONNECT_URL to that port's public address, so generated agent install commands send check-ins there:

PULSE_AGENT_INGEST_PORT=7656
PULSE_AGENT_CONNECT_URL=https://agents.example.com:7656

Agents then post telemetry to https://agents.example.com:7656/api/agents/agent/report, while the web UI and management API remain reachable only on the private FRONTEND_PORT listener.

Iframe Embedding (system.json)

Embedding is controlled by system.json and the UI (Settings → System → Network):

• allowEmbedding (boolean): enables iframe embedding
• allowedEmbedOrigins (comma-separated): restricts frame-ancestors when embedding is enabled

When allowEmbedding is false, Pulse sends X-Frame-Options: DENY and frame-ancestors 'none'.

Monitoring Overrides

Logging Overrides

Update Settings (system.json)

These are stored in system.json and managed via the UI.

Note: Update settings are stored in system.json. Legacy .env entries (UPDATE_CHANNEL, AUTO_UPDATE_ENABLED, AUTO_UPDATE_CHECK_INTERVAL, AUTO_UPDATE_TIME) are kept in sync for backwards compatibility but are not read at runtime.

stable is the default and recommended production channel. rc is an opt-in preview channel. In v6, unattended systemd auto-updates remain stable-only even when updateChannel is set to rc.

Auto-Import (Bootstrap)

You can auto-import an encrypted backup on first startup. This is useful for automated provisioning and test environments.

Note: PULSE_INIT_CONFIG_URL is only supported by the hidden pulse config auto-import command, not by the server startup auto-import.

Developer/Test Overrides (Environment Variables)

These are primarily for development or test harnesses and should not be used in production.

Metrics Retention (Tiered)

Persistent metrics history uses tiered retention windows. These values are stored in system.json and can be adjusted for storage vs history depth:

• metricsRetentionRawHours
• metricsRetentionMinuteHours
• metricsRetentionHourlyDays
• metricsRetentionDailyDays

See METRICS_HISTORY.md for details.

Prometheus Metrics Endpoint

The /metrics listener is separate from the main UI/API listener and binds to loopback by default.

For remote scraping with PULSE_METRICS_TOKEN, prefer a local scraper, tunnel, VPN-private path, or TLS/mTLS reverse proxy. Pulse refuses non-loopback plaintext token scraping unless PULSE_METRICS_ALLOW_INSECURE_REMOTE=true is set.

🔔 Alerts (alerts.json)

Pulse uses a powerful alerting engine with hysteresis (separate trigger/clear thresholds) to prevent flapping.

Managed via UI: Alerts → Thresholds

{
  "guestDefaults": {
    "cpu": { "trigger": 90, "clear": 80 },
    "memory": { "trigger": 85, "clear": 72.5 }
  },
  "schedule": {
    "quietHours": {
      "enabled": true,
      "start": "22:00",
      "end": "06:00"
    }
  }
}

Availability Checks (availability_targets.enc)

Availability checks are agentless probes for devices and services where Pulse cannot install an agent or does not need full machine telemetry. Use them for simple ping monitoring, TCP service checks, and HTTP/HTTPS status checks.

Managed via UI: Settings -> Monitoring -> Availability checks

Supported protocols:

Saved targets include name, targetKind (machine, service, or device), address, protocol, enabled, polling interval, timeout, failure threshold, and an optional linkedResourceId. ICMP ping is the default probe for new targets. Availability targets publish network-endpoint resources and can raise downtime alerts after the configured failure threshold.

Example API payload for simple ping monitoring:

{
  "name": "Garage temperature sensor",
  "targetKind": "device",
  "address": "garage-sensor.local",
  "protocol": "ping",
  "enabled": true
}

Pulse stores and returns that target as protocol: "icmp" so dashboards, alerts, and resource projections keep one canonical protocol value.

🔒 HTTPS / TLS

Enable HTTPS by providing certificate files via environment variables.

# Systemd
HTTPS_ENABLED=true
TLS_CERT_FILE=/etc/pulse/cert.pem
TLS_KEY_FILE=/etc/pulse/key.pem

# Docker
docker run --init -e HTTPS_ENABLED=true \
  -v /path/to/certs:/certs \
  -e TLS_CERT_FILE=/certs/cert.pem \
  -e TLS_KEY_FILE=/certs/key.pem ...

Important (Docker with HTTPS): Always use --init (or init: true in docker-compose) when enabling HTTPS. The Alpine-based healthcheck uses busybox wget, which spawns ssl_client subprocesses. Without an init process to reap them, these become zombie processes over time.

🛡️ Security Best Practices

1. Permissions: Ensure .env and nodes.enc are 600 (read/write by owner only).
2. Backup hygiene: Back up .env separately from system.json.
3. Tokens: Use scoped API tokens for agents instead of the admin password.

🔑 API Tokens

API tokens provide scoped, revocable access to Pulse. Manage tokens in Settings → Security → API Tokens.

The token shown during first-run setup is the primary automation API token for that Pulse instance. It is separate from your web login password and is meant for agents, scripts, integrations, kiosks, and temporary setup handoffs. Tokens are shown once; later token rows show only identifying hints such as prefix, suffix, label, scopes, and last-used metadata.

Revoking a token is safe for Pulse itself, but it immediately breaks any agent, script, kiosk, or integration still using that token. When a consumer needs to stay online, create and install a replacement token first, then revoke the old one. An agent whose token has been revoked stops authenticating until it is reinstalled or reconfigured with a valid token.

Token Scopes

Presets

The UI offers quick presets for common use cases:

Kiosk Mode

For unattended displays (wall monitors, dashboards), use a kiosk token to avoid cookie persistence issues:

1. Go to Settings → Security → API Tokens
2. Click New token and select the Kiosk / Dashboard preset
3. Copy the generated token
4. Access Pulse via URL with token:

   https://your-pulse-url/?token=YOUR_TOKEN_HERE
   

Kiosk tokens:

• Grant read-only dashboard access (monitoring:read scope)
• Hide the Settings tab automatically
• Work without cookies (token in URL)
• Can be revoked anytime from the UI

Security note: URL tokens appear in browser history and server logs. Use only for read-only dashboard access on trusted networks.

TrueNAS Integration {#truenas}

Pulse v6 supports first-class TrueNAS SCALE and CORE monitoring.

Adding a TrueNAS Instance

1. Go to Settings → TrueNAS.
2. Click Add Connection.
3. Enter the URL (e.g., https://truenas.local) and an API key.
4. Click Test Connection to verify, then Save.

Creating a TrueNAS API Key

On your TrueNAS system:

1. Navigate to the TrueNAS UI → Settings → API Keys.
2. Click Add and create a new read-only key.
3. Copy the key value and paste it into Pulse.

What Gets Monitored

TrueNAS connections are stored encrypted in truenas.enc.

Relay / Mobile Remote Access (Relay and Above) {#relay}

The relay protocol provides end-to-end encrypted remote access foundations for Pulse mobile connectivity.

Supported Pulse Mobile clients pair here using the generated QR code or deep link once relay is enabled for this instance.

Configuration

1. Go to Settings → Relay.
2. Toggle relay On.
3. Use the QR Code or Deep Link to pair a supported Pulse Mobile client.

Environment Overrides

For headless / container deployments that need to bootstrap relay without going through the UI, two environment variables override the persisted relay.enc values at load time:

Precedence: env vars beat the file. If you set PULSE_RELAY_ENABLED=true, saving the relay form in Settings → Relay will then persist the env-effective state to disk, so removing the env var later does not automatically revert relay back to its previous file-stored state — clear relay in the UI as well if you want to fully disable it.

Security

• All data is encrypted end-to-end using ECDH key exchange.
• The relay server never sees plaintext monitoring data.
• Each mobile session has its own encryption channel.
• Requires a valid Relay, Pro, legacy Pro+, or Cloud license (gated by the relay feature key).

Relay config is stored encrypted in relay.enc.