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 → Platform connections 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, enable discovery in Settings → System → Network and then review discovered servers in Settings → Infrastructure.

How do I change the port?

• Systemd: sudo systemctl edit pulse, add Environment="FRONTEND_PORT=8080", restart.
• Docker: Use -p 8080:7655 in your run command.

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?

If a setting is disabled with an amber warning, it's being overridden by an environment variable (e.g., DISCOVERY_ENABLED). Remove the env var to regain UI control.

---

🔍 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 → Platform connections 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. Go to Alerts → Thresholds and use the On/Off toggle next to any metric while editing, or set the value to -1. You can do this globally or per-resource (VM/Node).

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 → SSO Providers. 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 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?

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.

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.