mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-10-23 20:25:56 +00:00
pulse-triage[bot]
f3c92a242e
## Current combined outcome Keep PBS History attached only to its corroborated host and active range; make startup health checks work with bounded IPv4/IPv6 fallback; restore supported TrueNAS SCALE reporting queries; honor configured alert storm thresholds; and make troubleshooting and server update guidance safe to follow. Snapshot/metadata maintenance also reduces allocations without trusting identity hints, addressing the performance evidence in #2199 and contributor PR #2342. The prior proposal head `5cc1f2f7b06b6b6d98f08ed177e8326beea407e1` cannot land independently: completed Build and Test run `36672563104` fails its frontend dependency audit on high-severity brace-expansion advisories. This is not a retryable outage. Current reviewed source already additively incorporates published #2349 (`8d5969fb3b27422f7d9e5ef55fd4ce09af5b25a6`), including brace-expansion 1.1.21/5.0.12 and DOMPurify 3.4.16. Updating the blocked proposal once with this coherent reviewed range repairs that source defect; this is not repeated advancement of a healthy checking head. ## Current source range and newly included candidates Complete unpublished main range `8d5969fb3b27422f7d9e5ef55fd4ce09af5b25a6..66ec68c813cacf6c1a0f98cfb5f6da494584c9ac`. The already proposed PBS/guidance range below remains included unchanged. Newly included reviewed candidates: - `ffc44a0f8c02`: honor configured flapping thresholds above ten, retaining expiry/cooldown semantics. - `173290127a3a`, `6ef79688a5d1`, `18f519e3496b`: bounded captured audit diagnostics and fail-closed positive-advisory precedence, with release-asset guard reconciliation. These diagnostic changes alone do not fix advisories. - `9bc6f6ed647b`, `45b2fae8dbb5`: safe deployment-specific port diagnostics and credential-file API examples, with matching shipped guides. - `901274ee927d`: safe allocation-bounded snapshot/metadata maintenance; retains contributor credit and full identity decoding. - `21a35494aecb335755de773dd099e1364e65b3e0`: supported TrueNAS reporting summaries for #2346, preserving raw samples, windows and error boundaries. - `9d77f09b4f6b`: reject unscoped updater examples in authored release bodies. - `4ba830bfd31c0d2df71b4ed426b7b9ad31c8b4ed`: isolate drawer History across target/range changes and cancel obsolete reads; fixes reproduced former-host cache contamination in the #1723 investigation. - `fffaa64e57ef` and additive test repair `b0a4d2f3928f080dc093b561ba855b84f1443b41`: dual-stack bounded service-health probes and one bounded background retry; genuine API/UI/asset failures remain visible. - `66ec68c813cacf6c1a0f98cfb5f6da494584c9ac`: reviewed additive incorporation of full upstream #2349. The dependency manifests/security-floor tests exactly match current published main. Every accepted commit identity, original author and ancestor is preserved. No release, tag or deployment is changed by this proposal. ## Combined validation judgment Sufficient component evidence is reused rather than rerunning it solely for batching: - Existing original-range source/race/browser evidence is retained below. - TrueNAS: `source-j4j1btoe` / `source-lxeal7q5` affected/full race and modeled red/green evidence; final `source-8ouijs8p` vet/recovery proof. Same source tree across the message correction. - Drawer isolation: `source-z1ldgp56`, offline install/type-check/lint, 21,541 tests, embed build and bundle budgets; `source-2caj4cbp` / `source-z9xqxyun` formatting/header/duplication checks; real-renderer mock-backed desktop/phone browser proof, ten recorded inspected screenshots. - Health: final `source-txxwlqa3` complete server/telemetry race suites, 40 telemetry-report tests and vet; real frontend embed build/docs evidence `source-k2aprplj`. - Published #2349 exact proposal CI: run `36767849067` passed the complete dependency audit with zero reported vulnerabilities and 21,504 frontend tests (three skipped); its functional/E2E/security checks passed. The containing main range does not change its manifests or security-floor tests. This turn also passed 17 executable audit-wrapper fixtures and all 40 release-body renderer tests under `pulse-maintainer-proof`. The API-auth documentation tests reached three denied socket operations in that native fixture environment; those failures are execution-context evidence, not successful tests. An optional guest-local recheck through the supported source-proof executor is queued behind occupied proof slots, not a pass. It is not needed to repeat the existing candidate evidence; its outcome remains separate from exact-head CI. Publication provenance, complete-range whitespace and aggregate parent-bound browser coverage pass. All 22 unpublished non-merge commits pass canonical-completion checks using only their recorded, accurate Contract-Neutral reasons where applicable. An unqualified range-wide canonical invocation reported two cross-scope requirements; the required per-commit checks and parent/content-bound browser range check pass, not a blanket exemption. The current exact frontend snapshot is unavailable locally (`0bd5f30a…`); no final combined offline npm build/audit is claimed. The independently tested upstream graph and reviewed component proofs support proposing this composition, not merging without its fresh exact-head checks. Actual local VM Go remains 1.26.7 rather than the declared 1.26.8 floor. Fresh exact-head CI and independent review must resolve the complete proposal before landing. Prior failed checks remain evidence, not green checks or release qualification. These source/mock proofs do not establish installed PBS/VirtualBox/disk/network/I/O recovery, TrueNAS appliance acceptance, Tailscale Serve upgrade/rollback, or release readiness. Eligible patch placement remains separate; this main batch does not replace a published RC or expand v6.4.6 scope. <details> <summary>Retained earlier proposal scope and validation history</summary> ## What changed and why PBS host History and SMART ownership now require corroborated machine identity: reject stale Agent observations and host-local addresses, preserve IPv6 endpoints, and withdraw retained History when the backend link disappears. The frontend also rejects editable labels and endpoint-token guesses, permits fresh exact reported machine names or explicit backend Agent links, and isolates row snapshots so reconciliation cannot corrupt later withdrawal. This addresses wrong-host risks found investigating #1723; it does not claim installed relief for every PBS History symptom or the reporter's VirtualBox topology. Troubleshooting now explains browser-bound recovery and bounded sanitized incident reporting rather than ineffective credential-copying or risky repeats. Clone guidance follows saved Agent identities and persistent overrides instead of deleting the operating system's machine ID. Source and in-app guides match. ## Reviewed source included Complete main range `fa1d9eb36d4c2f55e648f10cfe7400983551b877..5cc1f2f7b06b6b6d98f08ed177e8326beea407e1`: - Retained-History withdrawal `62fb6cdb12dd3db90d2be598df1efc0210be37f1`, integrated by `7a646013062d667f7c053def80aab405c488d3e8`. - Recovery/reporting guidance `d707df9577ddbf9b4b7ba7c1c055131318bd66e1`, harness correction `5fe29c558d146664320ff8beda49f4a36613737b`, integrated by `78434304f1afbac5b58b17ce885424be17b4dff7`. - Backend identity safety `a0081d676b450f58d8f3593918334152df0de4d3`, composed at `3ea52c25b565d614304b23350012ce942f828e6b`. - Clone guidance `25a2e56d5ef62b2674a4deba655a121ecb7c8761`, integrated by `6e81f06e095a009233067a539ef7cc47502583d5`. - Frontend identity boundaries: regression fixtures `6ade01cbd4d02cd25b691f9ff5919206cceae764`, repair/browser receipt `3df86570396a3e7f600abf8a3c7c8d3ea957106c`, retained-fixture correction `be18333570be6ba428c690942d7b4def64d4a678`, integrated by `105e59bffb9b476ee3c9606cde95e3412e1664ac`. - Additive formatting-only correction `17f2d7a45d93ebd53347096edf46e44c8a0ef6fc`. The earlier #2341 head failed Frontend formatting in completed run 36658394047 on docsLinks.test.ts. A retry would not fix it; this correction preserves assertions and every accepted commit. The newer reviewed PBS range is included with the necessary repair rather than advancing an otherwise independently landable checking head. ## Validation and limits Recorded source evidence reused: - `source-3a9ej4nh`: offline frontend install, 21,506 tests, lint, type-check/build; mock-backed desktop/phone retained-History proof and inspected screenshots. - `source-sksnquh_`: full unifiedresources/pkg/pbs race suites and three polling regressions, exit 0. Final Go source is identical to that candidate. VM Go 1.26.7 differs from declared 1.26.8, so configured CI remains necessary. - Recovery/reporting: 20 documentation tests and 15 real-document desktop/phone checks. Clone guidance: `source-j3xvikj1` passed 47 documentation tests; `source-8hmpoki1` passed agent configuration/persistence tests; 21 browser assertions and four inspected screenshots. - Final reviewed PBS frontend candidate: `source-_pyutny3` passed 21,530 tests, lint/type-check/build; 24 desktop/phone target/layout checks with six inspected screenshots. Earlier red fixtures, snapshot-mutation failure and obsolete positive-fixture failures were retained and repaired. At prior proposal head `17f2d7a45d93ebd53347096edf46e44c8a0ef6fc`: `source-2kpt0am7` passed offline install, full locked formatting check and 21 docs tests; `source-hcai5s0y` passed both PBS table/drawer files, 48 tests. Provenance, whitespace and aggregate parent-bound browser coverage passed. Per-commit canonical checks used the reviewed Contract-Neutral reasons for bounded behavior-only frontend repairs; backend contracts were updated. Direct host attempts to run existing browser scripts stopped at denied loopback listeners, produced no visual proof and are not passes; the recorded confined browser evidence above remains separate. Exact-head functional/security CI and independent review govern landing; advisory results remain evidence, not release approval. These are source/mock proofs, not installed acceptance or release shipment. The frozen v6.4.5 RC.5 is not expanded by this main batch. ## Additive integration correction and current CI evidence The proposal's completed Core E2E run 36660586289 failed all six desktop/phone PBS History cases in shards 3, 6 and 8. The fixture supplied only presentation labels and a non-contract `pbs.hostname`, whereas the reviewed identity repair deliberately requires a reported `pbs.nodeName` or explicit backend Agent link. Commit `5cc1f2f7b06b6b6d98f08ed177e8326beea407e1` supplies the reported node name, retaining the expected guest/standalone History targets and wrong-target rejection. Runtime source is unchanged. No-content merge `80e654381b94e1a61ef6727cbc69b54d0fa7eb10` preserves Delivery's reviewed race-proof candidate. Every original reviewed identity and ancestry is retained. Recorded confined Chromium/WebKit desktop/phone fixture proof reproduces the old wrong targets and passes the corrected fixture. The separate Build and Test run 36660586299 failed only `TestConfigWatcher_WatchForChanges_Live` in rest-1, with expected mock setting `2` but an empty value. Config source is unchanged in this batch. Containing-head offline race proof `source-0ou4e1ru` passed 20 repetitions; this neither clears failed CI nor proves the cause. That failed run has been handed to Delivery for independent assessment. Fresh exact-head CI and independent review are required for this correction. Provenance, whitespace, accepted ancestry and aggregate browser-receipt coverage pass; existing full source proofs were reused where final source is identical. The old head cannot land independently because of its deterministic E2E fixture defect, so updating it with the already-committed correction is appropriate rather than repeatedly advancing a healthy checking proposal. No release, OTA, installed acceptance or complete reporter resolution is claimed. [How Pulse handles triage](https://github.com/rcourtman/Pulse/blob/main/docs/AI_TRANSPARENCY.md) [How Pulse handles triage](https://github.com/rcourtman/Pulse/blob/main/docs/AI_TRANSPARENCY.md) </details> [How Pulse handles triage](https://github.com/rcourtman/Pulse/blob/main/docs/AI_TRANSPARENCY.md)
Pulse
Real-time Proxmox, Docker and Kubernetes monitoring that finds what needs attention.
Pulse is a self-hosted monitoring workspace for Proxmox, Docker, Kubernetes, TrueNAS, physical and virtual machines, and early-access VMware vSphere environments. It combines live infrastructure state, history, alerts, recovery visibility, and scheduled health checks without requiring a conventional enterprise monitoring stack.
Why Pulse
- It watches between visits. Alerts and Pulse Patrol find failed backups, capacity pressure, restart loops, unhealthy containers, clock drift, and other problems that dashboards cannot surface when nobody is looking.
- It keeps each platform familiar. Proxmox, Docker, Kubernetes, TrueNAS, vSphere, and machines have dedicated views, backed by one shared resource model for search, alerts, history, and investigation.
- It stays operator-controlled. Credentials are encrypted at rest, API tokens are scoped, agent commands are disabled by default, and governed fixes require the configured policy and approval path.
Platform coverage
| Platform | Coverage |
|---|---|
| Proxmox VE, PBS, and PMG | Nodes, guests, storage, backups, replication, Ceph, mail gateways, and alerts |
| Docker and Podman | Hosts, containers, Compose projects, Swarm services, health, images, and updates |
| Kubernetes | Clusters, nodes, workloads, pods, services, storage, and events through the unified agent |
| TrueNAS SCALE and CORE | Pools, datasets, disks, snapshots, replication tasks, apps, VMs, and alerts |
| Linux, Windows, and macOS machines | Host health, filesystems, networking, temperatures, RAID, and availability through the unified agent |
| VMware vSphere | Early-access inventory, hosts, clusters, VMs, datastores, networks, snapshots, and recovery context; validate against your own vCenter before production use |
Platform pages keep storage and recovery information beside the infrastructure it belongs to. Alerts, Actions, and Patrol remain cross-platform views.
Patrol: monitoring that does rounds
Pulse Patrol runs scheduled checks across the current state and recent history of your infrastructure. Community installations can use a local model or their own AI provider for watch-only analysis. Pulse Pro adds investigation and policy-bound fixes with approval, verification, and an audit trail.
Pulse also includes an interactive Assistant and an MCP adapter for external clients such as Claude Code and OpenCode. Both sit on top of the same scoped inventory, metrics, alert, storage, and governed-action contracts.
Quick start
Choose an exact version from the latest release and keep that version pinned during installation.
Docker
docker run -d \
--name pulse \
-p 7655:7655 \
-v pulse_data:/data \
-e PULSE_DEPLOYMENT_METHOD=docker_run \
--restart unless-stopped \
rcourtman/pulse:vX.Y.Z
Open http://<your-ip>:7655 and follow the bootstrap-token setup. Docker host
monitoring is provided by the unified agent; the Pulse server container does
not need the Docker socket.
Proxmox LXC, Linux, and Kubernetes
The installer is signed. Verify install.sh against the pinned
pulse-installer key before running it:
export PULSE_VERSION=vX.Y.Z
curl -fsSLO "https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}/install.sh"
curl -fsSLO "https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}/install.sh.sshsig"
ssh-keygen -Y verify \
-f <(printf '%s\n' 'pulse-installer namespaces="pulse-install" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMZd/DaH+BldzOkq1A8KVTcFk73nAyrE8aJOyf7i00jm pulse-installer') \
-I pulse-installer \
-n pulse-install \
-s install.sh.sshsig < install.sh
bash install.sh --version "${PULSE_VERSION}"
rm -f install.sh install.sh.sshsig
The GitHub installer installs the Pulse server. Install and upgrade agents (including v5-to-v6 agent upgrades) with the per-host command generated under Settings → Infrastructure → Install on a host.
Do you need an agent?
Often not. Proxmox VE, PBS, and PMG are monitored through the Proxmox API with a read-only token, so nothing runs on the host and the generated setup script creates a privilege-separated monitoring user. Install the unified agent only where you want data the platform API cannot provide, such as host SMART health, temperatures, Docker hosts, or standalone machines.
The agent is operator-controlled by design. Command execution is off by
default, the local listener binds to localhost, and generated systemd units
ship hardened. On Linux, the installer's --least-privilege profile runs the
service as a dedicated non-root user, with optional scoped sudo grants for
the few collectors that need elevation. The
agent security model documents exactly what the
agent can and cannot do at each privilege level.
Important
GitHub release assets and
rcourtman/pulseimages are Community builds. Relay, Pro, and eligible legacy customers should use the private image or Linux archive provided by the Pulse download portal. Replacing a private Pro runtime with a public Community build removes its private runtime hooks.
Editions
- Community — self-hosted monitoring, seven days of metric history, core SSO, update alerts, and Patrol with your own provider or local model.
- Relay — Community plus secure remote web access, Pulse Mobile pairing, push notifications, and fourteen days of history.
- Pro — Relay plus Patrol investigation, governed fixes, ninety days of history, centralized agent profiles, RBAC, audit logging, and reporting.
- MSP — for managed service providers: one Pulse Account running many client workspaces, each with an isolated Pulse runtime — separate dashboards, alerts, users, audit history, and reports. Free sixty-day two-client evaluation at Pulse for MSPs.
Core self-hosted monitoring is not gated by monitored-system or child-resource volume. See the runtime-aligned capability reference and current plans for details.
Documentation
- Install and deployment
- Production deployment and security
- Upgrade from Pulse v5
- Releases and update channels
- Configuration
- Platform and agent guides
- Pulse Intelligence
- Security and privacy
- Code signing policy
- Troubleshooting
- API reference and architecture
Localized getting started guides: Deutsch · Español
Development
Pulse uses Go 1.26 and a SolidJS/TypeScript frontend. The managed development
runtime starts the frontend at http://127.0.0.1:5173 and proxies API and
WebSocket traffic to the backend on port 7655.
npm ci
npm --prefix frontend-modern ci
npm run dev
Useful checks:
go test ./...
npm --prefix frontend-modern test
npm --prefix frontend-modern run type-check
python3 scripts/check_public_docs.py
See CONTRIBUTING.md before investing in a code change. Pulse uses an issue-first contribution process and does not normally accept unsolicited pull requests.
Community and support
- Ask questions in GitHub Discussions.
- Report reproducible bugs through GitHub Issues.
- Home Assistant users can use the community-maintained Pulse add-ons.
- If Pulse is useful to you, support its development through GitHub Sponsors or Ko-fi.
License
Everything in this repository is licensed under the MIT License. There is no dual licensing and no commercial or source-available code here.
Pulse Pro is a separate commercial product, built from private sources and distributed through pulserelay.pro. Its use is governed by the Terms of Service, which apply to that product only, not to anything in this repository.