docs: clarify agent privilege guidance

Refs #1453

README.md

@@ -142,7 +142,7 @@ and Recovery desktop history-table layout are all aligned.
 - **[AI Features](docs/AI.md)**: Pulse Assistant (Chat) and Pulse Patrol documentation.
 - **[Multi-Tenant](docs/MULTI_TENANT.md)**: Enterprise multi-tenant setup and configuration.
 - **[Troubleshooting](docs/TROUBLESHOOTING.md)**: Solutions to common issues.
-- **[Agent Security](docs/AGENT_SECURITY.md)**: Details on checksum-verified updates and verification.
+- **[Agent Security](docs/AGENT_SECURITY.md)**: Agent privilege model, Proxmox API-only choices, and checksum/signature verification.
 - **[Docker Monitoring](docs/DOCKER.md)**: Setup and management of Docker agents.
 - **[Unified Navigation](docs/MIGRATION_UNIFIED_NAV.md)**: Guide to the new task-based navigation.
 

docs/AGENT_SECURITY.md

@@ -6,10 +6,11 @@ Pulse agents incorporate several security mechanisms to ensure that the code run
 
 Pulse's Linux/systemd installer runs the unified agent as `root` by default.
 That is intentional for full host telemetry: disk SMART data, mdadm/RAID state,
-temperature sensors, Docker or Podman socket reads, Proxmox host details, and
-some NAS/platform integrations commonly require root or equivalent local
-privileges. Running the service as a lower-privilege user may work for a narrow
-subset of metrics, but it is not a supported full-telemetry profile today.
+temperature sensors, Docker or Podman socket reads, Proxmox host-local details
+that are not available through the API, and some NAS/platform integrations
+commonly require root or equivalent local privileges. Running the service as a
+lower-privilege user may work for a narrow subset of metrics, but it is not a
+supported full-telemetry profile today.
 
 Treat a host agent like other infrastructure monitoring software with local
 root read access:
@@ -20,6 +21,11 @@ root read access:
   remediation;
 - update from signed release assets rather than arbitrary branch snapshots.
 
+The agent is primarily an outbound reporter to your Pulse server. By default it
+also exposes local health and Prometheus endpoints on `:9191`; set
+`--health-addr 127.0.0.1:9191` to bind that surface to loopback, or
+`--health-addr ""` to disable it when you do not scrape agent-local metrics.
+
 Command execution is disabled by default. It can be enabled with
 `--enable-commands`, `PULSE_ENABLE_COMMANDS=true`, or the centralized agent
 command setting after enrollment. Leave it disabled for read-only monitoring.
@@ -27,6 +33,32 @@ When enabled, commands still flow through Pulse's command policy and approval
 surfaces instead of silently turning every agent into an unrestricted remote
 shell.
 
+## Proxmox Deployment Choices
+
+You do not need a Pulse agent on every Proxmox-related host just to see basic
+cluster inventory and utilization. Start with the least-privilege path that
+answers your monitoring question:
+
+| Goal | Recommended path | Root agent needed? |
+|---|---|---|
+| PVE/PBS/PMG inventory, node status, VM/container status, storage usage, and normal Proxmox API metrics | Add the Proxmox connection with a read-only or narrowly scoped API token | No |
+| VM guest disk and memory details through QEMU Guest Agent | Use Proxmox API permissions such as `VM.GuestAgent.Audit` and `VM.GuestAgent.FileRead` where supported | No host agent for the Proxmox node |
+| Docker/Podman containers inside a VM or LXC | Install the agent inside that VM/LXC with Docker/Podman monitoring enabled | Usually requires root or Docker socket-equivalent access |
+| Host SMART, temperatures, local ZFS/Ceph/mdadm detail, arbitrary mount reads, and full host telemetry | Install the agent on that host | Yes, for the supported full-telemetry profile |
+| Kubernetes node/pod monitoring from a cluster | Use the Kubernetes agent/DaemonSet profile | Depends on whether host metrics are enabled |
+
+If Proxmox API data is enough for your use case, prefer API-only monitoring and
+do not install a host agent just because the installer exists. Install agents
+where you need data that Proxmox cannot provide through its API, or where the
+data lives inside a guest/container rather than at the Proxmox node layer.
+
+Running `pulse-agent` as a custom non-root systemd user is possible by editing
+the service unit, but it is not a supported full-telemetry mode today. Expect
+gaps in SMART, temperature, Docker socket, ZFS/Ceph/mdadm, mount, and platform
+integration data unless you deliberately grant equivalent capabilities or group
+access. If you choose that route, treat it as a local hardening profile and
+verify the exact metrics you care about after the change.
+
 ## Supply-Chain Boundary
 
 The agent self-update path is not just "download the latest binary and run it".
@@ -40,6 +72,12 @@ release-pinned, signature-verified server installer flow documented in
 [README.md](../README.md) and [INSTALL.md](INSTALL.md), then use the agent
 install command generated by your own Pulse server.
 
+For the server installer, avoid `latest` when you want a tighter change-control
+boundary. Download a specific release tag, verify the `install.sh.sshsig`
+signature, and pass that same tag to `bash install.sh --version`. Agent
+self-updates still verify checksum headers, and release builds require
+signatures when a trusted update key is embedded.
+
 ## Self-Update Security
 
 The agent's self-update mechanism is critical for security and stability. To prevent supply chain attacks or compromised update servers from distributing malicious or broken agents, Pulse employs a rigorous verification process.

docs/INSTALL.md

@@ -150,7 +150,13 @@ Pulse is secure by default. On first launch, you must retrieve a **Bootstrap Tok
    - Set your **Admin Username** and **Password** (or let Pulse generate one).
    - Pulse generates an **API token** for agents and automations.
    - Copy the credentials before leaving the page.
-4. Open **Settings → Infrastructure → Install on a host** and install the unified agent on each host you want monitored.
+4. Open **Settings → Infrastructure → Install on a host** and install the
+   unified agent only on hosts where you need agent-provided telemetry. For
+   Proxmox, start with API-only monitoring when inventory, node status,
+   VM/container status, and storage metrics are enough; use agents for
+   inside-guest Docker/Podman visibility, host SMART/temperature data, local
+   ZFS/Ceph/mdadm detail, or other telemetry that requires local host access.
+   See [Agent Security](AGENT_SECURITY.md).
 
 > **Note**: If you configure authentication via environment variables (`PULSE_AUTH_USER`/`PULSE_AUTH_PASS`), the bootstrap token is automatically removed and this step is skipped.
 

docs/README.md

@@ -57,7 +57,7 @@ All other documents are supporting references unless explicitly required for evi
 - **[Privacy](PRIVACY.md)** – What leaves your network (and what doesn’t).
 - **[OIDC / SSO](OIDC.md)** – OIDC Single Sign-On configuration (Authentik, Keycloak, Azure AD, etc.).
 - **[Proxy Auth](PROXY_AUTH.md)** – Authentik/Authelia/Cloudflare proxy authentication configuration.
-- **[Agent Security](AGENT_SECURITY.md)** – Agent self-update verification and API security.
+- **[Agent Security](AGENT_SECURITY.md)** – Agent privilege model, Proxmox API-only choices, and self-update verification.
 
 ## 📖 Advanced Topics (Relay / Pro / legacy Pro+ / Cloud)
 

docs/UNIFIED_AGENT.md

@@ -3,6 +3,14 @@
 The unified agent (`pulse-agent`) combines host, Docker, and Kubernetes monitoring into a single binary. It replaces older split-agent installs with one deployment and one service for simpler operations.
 Install it on each host you want Pulse to monitor. This is the primary monitoring path for infrastructure onboarding.
 
+For Proxmox, install the agent only where you need telemetry that the Proxmox
+API cannot provide, such as inside-guest Docker/Podman visibility, host SMART
+and temperature data, local ZFS/Ceph/mdadm detail, or arbitrary mount reads.
+Basic Proxmox inventory and utilization can use a read-only or narrowly scoped
+Proxmox API token instead. See [Agent Security](AGENT_SECURITY.md) for the
+root-service trade-off, restricted-user expectations, and supply-chain
+verification guidance.
+
 > Note: For temperature monitoring, use `pulse-agent --enable-proxmox` (recommended) or SSH-based collection. The legacy sensor proxy has been removed. See `docs/TEMPERATURE_MONITORING.md`.
 
 ## Quick Start
@@ -92,6 +100,9 @@ curl -fsSL http://<pulse-ip>:7655/install.sh | \
 | `--log-level` | `LOG_LEVEL` | Log verbosity (`debug`, `info`, `warn`, `error`) | `info` |
 | `--health-addr` | `PULSE_HEALTH_ADDR` | Health/metrics server address | `:9191` |
 
+Use `--health-addr 127.0.0.1:9191` when only local Prometheus scraping needs
+the health/metrics endpoint, or `--health-addr ""` to disable that listener.
+
 **Token resolution order**: `--token` → `--token-file` → `PULSE_TOKEN` → `/var/lib/pulse-agent/token`.
 
 ### Advanced Flags

docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-agent-security-2026-05-04.md

@@ -0,0 +1,34 @@
+# Documentation Currentness Agent Security Follow-Up
+
+- Date: `2026-05-04`
+- Lane: `L9`
+- Related discussion: `#1453`
+
+## Context
+
+Discussion `#1453` relayed a Proxmox community question about whether Pulse
+agents should run as `root`, whether API-only monitoring is enough for
+read-only Proxmox use cases, and what supply-chain risk exists when running an
+installer as `root`. The existing agent security guide already documented the
+Linux/systemd root default and checksum/signature verification, but it did not
+clearly separate Proxmox API-only monitoring from host/guest agent installs.
+
+## Outcome
+
+The active public docs now make the Proxmox deployment choice explicit:
+
+- start with Proxmox API-only monitoring when inventory, node status,
+  VM/container status, storage usage, and normal API metrics are enough;
+- install agents only where Pulse needs data that Proxmox cannot provide
+  through the API, such as inside-guest Docker/Podman visibility, host SMART
+  and temperature data, local ZFS/Ceph/mdadm detail, arbitrary mount reads, or
+  Kubernetes node/pod reporting;
+- treat custom non-root systemd service users as local hardening profiles, not
+  supported full-telemetry mode;
+- describe the agent-local health/metrics listener and the `--health-addr`
+  options for loopback binding or disabling;
+- keep release-pinned, signature-verified server installer guidance visible
+  alongside agent checksum/signature update verification.
+
+This keeps the project response in durable official guidance rather than a
+social-thread reply.

docs/release-control/v6/internal/status.json

@@ -872,6 +872,11 @@
           "path": "docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-2026-03-13.md",
           "kind": "file"
         },
+        {
+          "repo": "pulse",
+          "path": "docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-agent-security-2026-05-04.md",
+          "kind": "file"
+        },
         {
           "repo": "pulse",
           "path": "docs/release-control/v6/internal/SOURCE_OF_TRUTH.md",
@@ -4322,6 +4327,12 @@
           "kind": "file",
           "evidence_tier": "local-rehearsal"
         },
+        {
+          "repo": "pulse",
+          "path": "docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-agent-security-2026-05-04.md",
+          "kind": "file",
+          "evidence_tier": "local-rehearsal"
+        },
         {
           "repo": "pulse",
           "path": "docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-contribution-policy-2026-05-01.md",