Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
docs: rewrite the README for first-time visitors
rcourtman9a4456e33615
diff --git a/README.md b/README.mdindex b28c1f7860..58b202348c 100644--- a/README.md+++ b/README.md@@ -12,57 +12,55 @@[Live demo](https://demo.pulserelay.pro) · [Documentation](docs/README.md) · [Releases](https://github.com/rcourtman/Pulse/releases) · [Discussions](https://github.com/rcourtman/Pulse/discussions)</div>-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 |+Pulse is a self-hosted dashboard and alerting tool for your homelab or+infrastructure. Point it at Proxmox, Docker, Kubernetes, TrueNAS, vSphere or+your own Linux, Windows and macOS machines, and it shows their health in one+place, keeps the history, and tells you when something needs attention: a+failed backup, a filling disk, an unhealthy container, a node that dropped+offline.++++Want to look around first? The [live demo](https://demo.pulserelay.pro) runs on+sample data and signs you in automatically.++## What Pulse does++- **Gives each platform its own page.** Proxmox, Docker, Kubernetes, TrueNAS,+ vSphere and machines each get a view that matches how you already think+ about them, with storage and backups beside the systems they belong to.+- **Alerts you when it matters.** Set thresholds for CPU, memory, disk,+ temperature and more, and get notified by email or through Discord, Slack,+ Teams, Telegram, ntfy, Gotify, Pushover, PagerDuty or any webhook.+- **Checks the things that can't run an agent.** Ping, TCP, UDP and HTTP(S)+ availability checks cover routers, printers and web services, with+ certificate-expiry warnings.+- **Keeps history.** Every guest, container and host has charts: seven days in+ Community, ninety in Pro.+- **Optional AI checks.** Connect your own AI provider or a local model and+ Pulse Patrol runs scheduled checks for problems a dashboard only shows if+ someone is looking. An MCP adapter lets clients such as Claude Code and+ OpenCode query Pulse.+- **Stays hands-off by default.** Proxmox is read through a read-only API+ token, credentials are encrypted at rest, and agent commands stay off unless+ you turn them on.++## Supported platforms++| Platform | What Pulse shows ||---|---|-| 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.--+| Proxmox VE, PBS and PMG | Nodes, VMs and containers, storage, backups, replication, Ceph and mail gateways |+| Docker and Podman | Hosts, containers, Compose projects, Swarm services, health, images and updates |+| Kubernetes | Clusters, nodes, workloads, pods, services, storage and events |+| TrueNAS SCALE and CORE | Pools, datasets, disks, snapshots, replication tasks, apps and VMs |+| Linux, Windows and macOS | Host health, filesystems, networking, temperatures, RAID and availability |+| VMware vSphere (early access) | Hosts, clusters, VMs, datastores, networks and snapshots; validate against your own vCenter before relying on it |-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.+## Install-## Quick start--Choose an exact version from the [latest release](https://github.com/rcourtman/Pulse/releases/latest)-and keep that version pinned during installation.+Pulse is one container or service listening on port 7655. Pick an exact+version from the [latest release](https://github.com/rcourtman/Pulse/releases/latest)+and use it in place of `vX.Y.Z` below.### Docker@@ -76,18 +74,13 @@ docker run -d \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 Pulse container does not need the Docker socket. Docker hosts are+monitored by the agent described below.-- [Signed Proxmox LXC and Linux installation](docs/INSTALL.md#quick-start-recommended)-- [Docker Compose](docs/INSTALL.md#docker-compose)-- [Kubernetes and Helm](docs/KUBERNETES.md)+### Proxmox LXC or Linux-The installer is signed. Verify `install.sh` against the pinned-`pulse-installer` key before running it:+The installer is signed. This block downloads it, verifies it against the+pinned `pulse-installer` key, and only then runs it:```bashexport PULSE_VERSION=vX.Y.Z@@ -101,84 +94,102 @@ ssh-keygen -Y verify \bash install.sh --version "${PULSE_VERSION}"```-Paste the whole block: installation stops if either download or signature-verification fails. Do not run the final command separately to bypass a failure.+Paste the whole block. If a download or the signature check fails, it stops;+don't run the last line on its own to get past a failure.++Also available: [Docker Compose](docs/INSTALL.md#docker-compose),+[Kubernetes with Helm](docs/KUBERNETES.md) and the [full install guide](docs/INSTALL.md).++### First run-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**.+Open `http://<your-ip>:7655` and paste the one-time setup token. Get it with+`docker exec pulse /app/pulse bootstrap-token` on Docker, or+`sudo pulse bootstrap-token` on Linux (the LXC installer prints the exact+command). Create your admin account, then add your first system with+**Add infrastructure** under **Settings → Infrastructure**.### Do you need an agent?-Often not. Proxmox VE, PBS, and PMG are monitored through the Proxmox API-with a read-only token, so no Pulse host agent is required. 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.--**API-only does not mean guest-agent-free.** VM filesystem and memory requests through QEMU Guest Agent can share the channel used by freeze-enabled backups.-Read-only permissions do not prove backup safety. Do not add permissions, enable or restart an agent, or send manual guest-agent probes during a backup, freeze or thaw.-Use the existing [backup safety precaution](docs/VM_DISK_MONITORING.md#backup-safety). Stopping Pulse also stops its monitoring and alerts.-An OK backup task does not prove successful thaw.--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](docs/AGENT_SECURITY.md) documents exactly what the-agent can and cannot do at each privilege level.+Often not. Proxmox VE, PBS and PMG are monitored through their API with a+read-only token, so no Pulse host agent is required; the generated setup script+creates a privilege-separated monitoring user. Install the unified agent where+an API can't give Pulse what you want: Docker and Podman hosts, Kubernetes,+standalone machines, or host SMART health and temperatures.++Agents, including v5-to-v6 agent upgrades, are installed with the per-host+command under **Settings → Infrastructure → Install on a host**. The GitHub+installer above is for the Pulse server only. Command execution is off by+default, the agent's local listener binds to localhost, and on Linux+`--least-privilege` runs it as a dedicated non-root user. The+[agent security model](docs/AGENT_SECURITY.md) lists what it can and cannot do+at each privilege level.++> [!WARNING]+> **API-only does not mean guest-agent-free.** VM filesystem and memory+> requests through QEMU Guest Agent can share the channel used by+> freeze-enabled backups. Read-only permissions do not prove backup+> safety. Do not add permissions, enable or restart an agent, or send manual+> guest-agent probes during a backup, freeze or thaw. An OK backup task does+> not prove successful thaw. Stopping Pulse also stops its monitoring and+> alerts. Read the [backup safety precaution](docs/VM_DISK_MONITORING.md#backup-safety)+> before you need it.++## Editions++- **Community** (free, this repository): self-hosted monitoring, seven days+ of metric history, core SSO, update alerts, and Patrol with your own AI+ provider or a local model.+- **Pro**: Community plus Patrol investigation and fixes, ninety days+ of history, centralized agent profiles, RBAC, audit logging and reporting.+- **MSP**: one Pulse Account running isolated workspaces for each client, with+ separate dashboards, alerts, users, audit history and reports. Try it free+ for sixty days with two clients at [Pulse for MSPs](https://pulserelay.pro/msp).++Core self-hosted monitoring is not gated by how many systems or child+resources you monitor. See the [capability reference](docs/PULSE_PRO.md) and+[current plans](https://pulserelay.pro).> [!IMPORTANT]> GitHub release assets and `rcourtman/pulse` images are Community builds.-> Relay, Pro, and eligible legacy customers should use the private image or-> Linux archive provided by the [Pulse download portal](https://pulserelay.pro/download.html).-> Replacing a private Pro runtime with a public Community build removes its-> private runtime hooks.+> Pro, Relay and eligible legacy customers should install the private image or+> Linux archive from the [Pulse download portal](https://pulserelay.pro/download.html).+> Replacing a private Pro runtime with a 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.-- **Pro** — Community 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](https://pulserelay.pro/msp).--Relay is no longer sold. Existing Relay subscribers receive Pro features at their-current price for as long as their subscription continues. Existing paired phones-keep working until **31 March 2027**. Relay connects the app, not the web UI. Use-your own VPN or tunnel for remote web access. For phone alerts, add an-ntfy, Gotify or Pushover destination and open Pulse in your phone's browser.--Core self-hosted monitoring is not gated by monitored-system or child-resource-volume. See the [runtime-aligned capability reference](docs/PULSE_PRO.md) and-[current plans](https://pulserelay.pro) for details.+Relay is no longer sold. Existing subscribers keep Pro features at their+current price for as long as their subscription continues, and paired phones+keep working until **31 March 2027**. Relay connects the app, not the web UI:+use your own VPN or tunnel for remote access, and add an ntfy, Gotify or+Pushover destination for phone alerts.## Documentation-- [Install and deployment](docs/INSTALL.md)-- [Production deployment and security](docs/PRODUCTION_SECURITY.md)-- [Upgrade from Pulse v5](docs/UPGRADE_v6.md)-- [Releases and update channels](docs/RELEASE_PROCESS.md)-- [Configuration](docs/CONFIGURATION.md)-- [Platform and agent guides](docs/README.md#platforms-and-agents)-- [Pulse Intelligence](docs/AI.md)-- [Security](SECURITY.md) and [privacy](docs/PRIVACY.md)-- [Code signing policy](docs/CODE_SIGNING_POLICY.md)-- [Troubleshooting](docs/TROUBLESHOOTING.md)-- [API reference](docs/API.md) and [architecture](ARCHITECTURE.md)--Localized getting started guides:+- [Install](docs/INSTALL.md) · [Production security](docs/PRODUCTION_SECURITY.md) · [Upgrading from v5](docs/UPGRADE_v6.md) · [Configuration](docs/CONFIGURATION.md)+- [Platform and agent guides](docs/README.md#platforms-and-agents) · [Pulse Intelligence](docs/AI.md) · [Releases and update channels](docs/RELEASE_PROCESS.md)+- [Troubleshooting](docs/TROUBLESHOOTING.md) · [API](docs/API.md) · [Architecture](ARCHITECTURE.md) · [Security](SECURITY.md) · [Privacy](docs/PRIVACY.md) · [Code signing](docs/CODE_SIGNING_POLICY.md)++Getting started in other languages:[Deutsch](docs/i18n/de/README.md) · [Español](docs/i18n/es/README.md)+## Community and support++- Questions and ideas: [GitHub Discussions](https://github.com/rcourtman/Pulse/discussions)+- Bugs and unexpected behaviour: [GitHub Issues](https://github.com/rcourtman/Pulse/issues)+- Home Assistant: community-maintained [Pulse add-ons](https://github.com/Kosztyk/homeassistant-addons)+- Support development: [GitHub Sponsors](https://github.com/sponsors/rcourtman) or [Ko-fi](https://ko-fi.com/rcourtman)++Before filing a bug, read the+[safe reporting guidance](docs/TROUBLESHOOTING.md#-getting-help). Your original+evidence is enough. A second reproduction or diagnostics export is not+required, so please don't repeat anything that could interrupt workloads or+send duplicate notifications. GitHub reports and attachments are public:+review them locally and keep credentials and private details out.+## 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`.+Pulse is Go 1.26 with a SolidJS and TypeScript frontend. The managed dev+runtime serves the frontend at `http://127.0.0.1:5173` and proxies API and+WebSocket traffic to the backend on port 7655.```bashnpm ci@@ -186,34 +197,12 @@ npm --prefix frontend-modern cinpm run dev```-Useful checks:--```bash-go test ./...-npm --prefix frontend-modern test-npm --prefix frontend-modern run type-check-python3 scripts/check_public_docs.py-```--See [CONTRIBUTING.md](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](https://github.com/rcourtman/Pulse/discussions).-- Report bugs and unexpected outcomes through [GitHub Issues](https://github.com/rcourtman/Pulse/issues).-- Home Assistant users can use the community-maintained [Pulse add-ons](https://github.com/Kosztyk/homeassistant-addons).-- If Pulse is useful to you, support its development through [GitHub Sponsors](https://github.com/sponsors/rcourtman) or [Ko-fi](https://ko-fi.com/rcourtman).--Read the [safe reporting guidance](docs/TROUBLESHOOTING.md#-getting-help) before sharing original evidence. A second reproduction or diagnostics export is not required; do not repeat an attempt that could interrupt workloads or send duplicate notifications. GitHub reports and attachments are public: review them locally and keep credentials and private details out.+Read [CONTRIBUTING.md](CONTRIBUTING.md) before starting on a change: Pulse+works issue-first and does not normally accept unsolicited pull requests.## License-Everything in this repository is licensed under the [MIT License](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](https://pulserelay.pro). Its use is-governed by the [Terms of Service](TERMS.md), which apply to that product-only, not to anything in this repository.+Everything in this repository is [MIT licensed](LICENSE), with no dual+licensing and no source-available code. Pulse Pro is a separate commercial+product built from private sources, sold through [pulserelay.pro](https://pulserelay.pro)+under [Terms of Service](TERMS.md) that apply to that product only.