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](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](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.

- **Agent setup**: use the generated command on the target host, entering the
  token only at its private prompt, never in the command itself. Alternatively,
  follow the [private-file preparation](UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nas).
- **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.

### Why does the copied agent command say no installation was attempted?

That message describes a stopped preparation step, not the health of an agent
already installed. If it follows `stty: command not found`, the private token
prompt cannot prepare the terminal; having an interactive shell does not supply
the missing tool. Do not remove the privacy check, put a token in the command,
generate another token or uninstall the existing agent to get past it.

Use the [agent command failure guide](UNIFIED_AGENT.md#copied-agent-command-fails-before-installation)
to distinguish the prompt, preflight and removal paths. Keep the original error
and existing state; a failed new command does not explain an earlier outage or
automatic-update failure.

### 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](TROUBLESHOOTING.md#port-change-didnt-take-effect)
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](UNIFIED_AGENT.md#auto-update).

### 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](CONFIGURATION.md#common-overrides-environment-variables) and
[CORS checks](TROUBLESHOOTING.md#cors-errors). 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](AI.md), [Plans and entitlements](PULSE_PRO.md), 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](RELAY.md) 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](VM_DISK_MONITORING.md#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](VM_DISK_MONITORING.md#a-missing-reading-is-not-an-installation-diagnosis).

### 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](MIGRATION_UNIFIED_NAV.md) 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](AI.md#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](TROUBLESHOOTING.md#test-succeeds-but-real-alerts-are-missing).
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](TEMPERATURE_MONITORING.md#check-existing-linux-readings-safely)
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](TEMPERATURE_MONITORING.md#recommended-pulse-agent-proxmox).
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](TEMPERATURE_MONITORING.md).

---

## 🔐 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](PRODUCTION_SECURITY.md) for the full
trust boundary and rollout checklist.

### I forgot my password. How do I reset it?
Use the [password recovery guide](TROUBLESHOOTING.md#i-forgot-my-password).
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](CONFIGURATION.md#-https--tls).

### 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](PROXY_AUTH.md).

---

## ⚠️ 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](TROUBLESHOOTING.md#old-bookmarks-dont-work) 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](METRICS_HISTORY.md#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](TRUENAS.md#stale-truenas-data),
[empty PBS History](PBS.md#pbs-is-connected-but-history-stays-empty),
[missing or stale PVE replication jobs](TROUBLESHOOTING.md#replication-jobs-are-pending-stale-or-missing) or
[missing VM disk usage](VM_DISK_MONITORING.md#a-missing-reading-is-not-an-installation-diagnosis). Check Proxmox
[effective permissions](TROUBLESHOOTING.md#check-permissions-proxmox) 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](TROUBLESHOOTING.md#collect-diagnostics-safely).
If logs are needed, use a bounded excerpt from the original incident and review
it locally before sharing, as described in [Getting Help](TROUBLESHOOTING.md#-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](TROUBLESHOOTING.md#connection-refused).
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](TROUBLESHOOTING.md#cors-errors) before broadening browser access.

### High memory usage?
For a monitored VM, first check [guest memory, cache and available memory](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).
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](TROUBLESHOOTING.md#memory-use-keeps-growing) 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](PRODUCTION_SECURITY.md#production-rollout-checklist).

---

## 🧑‍💻 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](AI_TRANSPARENCY.md) for the standing policy.