Pulse/docs/FAQ.md

❓ Frequently Asked Questions

🛠️ Installation & Setup

What's the easiest way to install?

If you run Proxmox VE, use the signed LXC installer flow in INSTALL.md and replace vX.Y.Z with the exact release tag you want.

If you prefer Docker:

Use a pinned image tag such as rcourtman/pulse:vX.Y.Z instead of :latest.

See INSTALL.md for all options (Docker Compose, Kubernetes, systemd).

How do I add a node?

Go to Settings → Infrastructure → Install on a host for systems that should run the unified agent directly.

• Recommended (agent setup): copy the generated install command and run it on the target host.
• Manual/API-backed platforms: use Settings → Infrastructure (Add infrastructure) for systems such as Proxmox, PBS, PMG, or TrueNAS that connect over an API instead of running the agent locally.

If you want Pulse to find servers automatically, open Settings → Infrastructure, select Configure discovery (it reads Settings once discovery is on), turn on Automatic scanning in the Discovery settings dialog, and then review discovered servers in the same section.

How do I change the port?

Distinguish Pulse's web listener from a container's published host port. FRONTEND_PORT controls the listener (default 7655); the separate PULSE_AGENT_INGEST_PORT is not the web UI port.

• Systemd / Proxmox LXC: change the active Pulse service's managed port setting. For LXC, work inside the Pulse container, not on the Proxmox host. A unit or drop-in change needs a service-manager reload and a restart of that service during a suitable maintenance window.
• Docker / Compose: with the default listener, 8080:7655 publishes the UI on host port 8080; it does not require changing FRONTEND_PORT. The repository's Compose file uses PULSE_PORT for this host-side mapping. Apply the change through your existing container manager's recreate/redeploy operation, preserving the same image, data mount and other settings. docker restart does not apply a new port mapping. Do not delete a data volume or replace your existing deployment with a fresh docker run command.

Update the reverse proxy's upstream port separately if needed; do not expose Pulse directly or broadly open the firewall to bypass it. Follow the deployment-specific port checks and keep full service environments and container inspections private.

Does updating the Pulse server update every agent immediately?

No. The server and agent have separate update lifecycles. Eligible v6 agents check for and apply the server's target version asynchronously. v5 agents, PVE host agents, agents with auto-update disabled, and agents with failed or missing update prerequisites need a manual command.

Open an outdated-agent notice or /settings/infrastructure?agentDoctor=1 to open Agent Doctor and copy the correct per-host command. The surface does not remotely execute the update. Use Settings → Infrastructure → Install on a host for first installs and v5-to-v6 upgrades. See Unified Agent.

Why can't I change settings in the UI?

A warning that names an environment variable means that deployment setting manages the value, rather than the UI. If it is intentional, keep it and ask the deployment administrator to change that setting; do not remove unrelated authentication or security overrides.

To hand that particular setting back to the UI, remove only its override from the active deployment source. Apply through the same deployment: environment changes for Docker require recreation/redeployment, not docker restart; a systemd unit or drop-in change needs a service-manager reload and restart. Preserve the image, data mount, credentials and other settings. Merely editing a file does not change the running process's environment.

Re-open Settings afterwards and check both the warning and effective value. Removing an override does not necessarily erase the saved value underneath it or turn the setting off. For example, a saved CORS allowlist can remain after ALLOWED_ORIGINS is removed. See environment precedence and CORS checks. If no environment warning is shown, retain the displayed error rather than assuming an override is the cause. Do not post full environment, Compose or configuration dumps; they can contain passwords and tokens.

---

🔍 Monitoring & Metrics

What do Pro and Cloud unlock?

Pro and Cloud unlock hands-on Patrol modes, issue investigation, governed fixes, verified outcomes, and 90-day history along with the broader operations feature set. Existing legacy Pro+ holders keep their current continuity, but self-hosted pricing no longer sells more monitoring volume. Pulse Patrol is available to everyone on Community with BYOK and provides scheduled, cross-system analysis that correlates real-time state, recent metrics history, and diagnostics to surface actionable findings.

Example output includes trend-based capacity warnings, backup regressions, Kubernetes cluster analysis, and correlated container failures that simple threshold alerts miss. See Pulse Intelligence, Plans and entitlements, and https://pulserelay.pro.

What happens to Pulse Mobile and Relay?

Pulse Mobile and Relay retire on 31 March 2027. Existing paired phones keep working until then. Relay is no longer sold; existing Relay subscribers receive Pro features at their current price for as long as their subscription continues. Those Pro features do not end with the app's retirement.

Relay connects the app, not the web UI. To reach Pulse away from home, use your own VPN or tunnel. For alerts on your phone afterwards, add an ntfy, Gotify or Pushover destination under Alerts and open Pulse in your phone's browser. See Relay / Pulse Mobile for the existing pairing and security details.

Why do VMs show "-" for disk usage?

A dash means filesystem usage is unavailable, not zero. Allocated virtual-disk size is not used space inside the guest. Pulse can read that usage through a supported QEMU Guest Agent, but a failed read does not establish that the agent is absent or stopped. Read the explanation and observation time; use the guest's own filesystem readings rather than treating a retained Pulse value as current.

Do not install, enable or restart an agent solely to clear a disk dash. During a backup, freeze/thaw or an unresponsive-guest incident, defer setup and live probes. Follow Backup safety; an OK backup does not prove thaw. Keep the monitoring-outage precaution until independent checks confirm thaw, fresh writes to every covered filesystem and workload liveness. Restore only services and timers that were previously active.

Outside those conditions, review the existing configuration and supported setup for the guest OS. The Linux package name is not a Windows or Android installation instruction; if no supported agent is available, use guest-local filesystem tools. See Missing-reading and setup guidance.

Does Pulse monitor Ceph?

Yes! If Pulse detects Ceph storage, it automatically queries cluster health, OSD status, and pool usage. No extra config needed.

Does Pulse monitor TrueNAS?

Yes. Pulse includes first-class TrueNAS SCALE/CORE integration. Add your TrueNAS server under Settings → Infrastructure (Add infrastructure) with the URL and API key. Pulse monitors the appliance, native VMs, apps, pools, datasets, disks, ZFS snapshots, replication tasks, and alerts. Those resources appear on the dedicated TrueNAS page.

How is navigation organised in Pulse v6?

Pulse uses platform-shaped top-level pages:

• Proxmox, Docker, Kubernetes, TrueNAS, vSphere, and Machines keep platform-specific inventory and workflows together.
• Storage, snapshots, backups, and replication appear inside the platform page they belong to.
• Alerts, Actions, and Patrol provide cross-platform operational views.

The short-lived unified /workloads, /storage, and /recovery top-level navigation was retired during the v6 prerelease cycle. See the historical migration note if you are comparing an older release candidate.

Can I disable alerts for specific metrics?

Yes, for the controls offered in Alerts → Thresholds. Edit the relevant default or resource row, use its On/Off toggle, save, then reopen the editor to check the saved setting. The available resource overrides differ by platform; not every default has a per-resource control. Use the editor rather than treating -1 as a universal value or hand-editing alerts.json.

Off applies to that alert check, not all monitoring:

• A metric's Off toggle does not hide its readings, stop collection or disable unrelated checks. Memory alerts, connectivity alerts and backup-age alerts are separate controls. Check warning and critical levels separately too.
• Check both the default and any override on the affected resource. A resource's explicit threshold can remain active even when its default is Off.
• Disabling a notification destination is different from disabling alert evaluation. Already queued notifications can reflect earlier settings; a message alone does not prove a new alert was evaluated after the save.
• Patrol findings are separate from threshold alerts. For CPU, memory, guest-disk and storage usage, Patrol currently uses its built-in threshold when the corresponding alert default is Off. Turning these alerts Off does not suppress a Patrol finding. See how Patrol works.

Use the existing alert entry or Patrol finding to identify which path produced the warning. For missing messages, use the ordinary notification checks. Do not induce an alert, send another Test or retry the queue merely to check Off.

How do I monitor temperature?

Check the affected host's active agent version, sensor and observation time before changing its setup. A current Pulse server does not update every agent. Compare the same host and sensor at the same time; CPU/SoC temperature is not physical-disk SMART temperature. A missing reading is unavailable, not zero.

On Linux, the agent reads existing sensors -j output and recognised CPU/SoC thermal sysfs sources. lm-sensors is not required for the CPU/SoC fallback. Start with the bounded, private local reading check on the monitored host, not inside the Pulse container.

Do not run hardware detection, bus scans, load drivers or reboot the host merely to fill a temperature row. Necessary sensor setup belongs in that host's normal maintenance window. During backups, freeze/thaw or an unresponsive-host incident, defer setup and diagnostics.

For a new Proxmox agent installation, follow the verified HTTPS and token-file setup. Recent usable agent temperature data does not also require SSH for that host; do not mount root SSH keys into Pulse or loosen an existing restricted key to repair a missing reading. Other platforms have different providers and limits: see Temperature Monitoring.

---

🔐 Security & Access

Does Pulse need root access on every Proxmox host?

No. Start with a dedicated read-only or narrowly scoped Proxmox API token; that provides normal inventory, status, utilization, guest, and storage monitoring without installing Pulse on the hypervisor. The optional Linux agent runs as root by default when you need host-local telemetry such as SMART, temperatures, mdadm, or full mount details. Agent commands and network discovery are disabled by default. See Production Deployment and Security for the full trust boundary and rollout checklist.

I forgot my password. How do I reset it?

Use the password recovery guide. For the local administrator, update only the password in its active credential source, preserving the username, tokens, configuration and data; deleting .env is not a universal reset. The guide covers Docker, systemd and Proxmox LXC, including deployment overrides, private backups and verification. SSO login, temporary lockouts and a fresh install's missed bootstrap token need different steps; do not reset a working installation to retrieve that token.

How do I enable HTTPS?

Set HTTPS_ENABLED=true and provide TLS_CERT_FILE and TLS_KEY_FILE environment variables. See Configuration.

Can I use Single Sign-On (SSO)?

Yes. Pulse supports OIDC and SAML SSO providers, with multi-provider support (multiple IdPs active simultaneously). Configure in Settings → Security → Single Sign-On. Pulse also supports Proxy Auth (Authentik, Authelia, Cloudflare). See Proxy Auth Guide.

---

⚠️ Troubleshooting

No data showing?

First distinguish what is missing; Pulse monitors more than Proxmox.

Missing item	Check existing evidence first
Whole page or resource	Open its platform page, not just Machines. Follow the current navigation guide for moved pages and bookmarks.
Current readings	Check the affected connection in Settings → Infrastructure: is it enabled, and does its last activity advance during ordinary polling? For an agent, compare Last seen with the particular missing reading.
History only	Check the selected resource and time range. A current value does not prove that samples were stored for that chart; use History troubleshooting.

A green connection badge, recent Last seen or successful Test Connection does not prove that every reading is fresh. Missing or unavailable is not zero. Use the relevant checks for stale TrueNAS data, empty PBS History, missing or stale PVE replication jobs or missing VM disk usage. Check Proxmox effective permissions only when the affected operation reports an access error, not on a missing chart alone.

Keep the original time and displayed error. Do not replace credentials, delete connections or re-enrol agents just to populate a chart. During a backup, freeze/thaw or an unresponsive-host incident, defer setup, live tests and Run Diagnostics; follow safe evidence collection. If logs are needed, use a bounded excerpt from the original incident and review it locally before sharing, as described in Getting Help.

Connection refused?

Distinguish your browser's connection to Pulse from Pulse's connection to a monitored platform. If the browser cannot reach Pulse, check the actual service, listening port and proxy using the connection guide. If Pulse opens but a platform request is refused, preserve that request's redacted error and use its platform guide above; changing Pulse's listening port does not repair the platform connection.

CORS errors?

Keep the default same-origin policy when Pulse and its API use the same public origin, including behind a reverse proxy. If a separate trusted browser app needs cross-origin API access, allow only its exact origin (scheme, host and port); * is not a login or proxy repair. Follow the CORS checks before broadening browser access.

High memory usage?

For a monitored VM, first check guest memory, cache and available memory. A high hypervisor footprint and one application's RSS measure different things; compare existing readings from the same guest and time, not the Proxmox node.

First distinguish container usage from Pulse's resident memory (RSS); a high LXC or Docker chart alone does not establish a leak. Use the read-only memory checks for your deployment while it is responsive.

A higher steady baseline is worth reporting even without continuing growth. A lower reading ten minutes into a new process is not a like-for-like comparison with a week-old run, or proof of recovery. Keep already available readings, versions, uptime and workload context; do not restart to create a comparison.

Do not shorten retention, slow polling, restart Pulse or drop caches just to lower the reading. Shorter retention removes history, and slower polling can delay monitoring; neither establishes the cause. If the container is near its memory limit or the host is unresponsive, stop sampling and prioritise safe recovery.

Can Pulse monitor 50 or more Proxmox hosts?

Pulse has automated API and metrics-store load coverage for a simulated 500-node estate, including 2,500 VMs and concurrent readers and writers. That is regression evidence rather than a universal production certification: retention, polling, storage latency, integrations, and guest count all affect real capacity. Stage a large rollout and measure it using the checklist in Production Deployment and Security.

---

🧑‍💻 The Project

Is Pulse developed with AI?

Yes. Pulse uses coding agents and other automation across development and triage. The maintainer sets product direction, controls releases, and remains responsible for the result. See Development and Automation Transparency for the standing policy.