Pulse Documentation

File: README.md Copy Chapter

Pulse

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 Copy Chapter

• 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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

Choose an exact version from the latest release
and keep that version pinned during installation.

Docker Copy Section

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 Copy Section

• Signed Proxmox LXC and Linux installation
• Docker Compose
• Kubernetes and Helm

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? Copy Section

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/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.
Replacing a private Pro runtime with a public Community build removes its
private runtime hooks.

Editions Copy Chapter

• 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 Copy Chapter

• Install and deployment
• Production deployment and security
• Upgrade from Pulse v5
• 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 Copy Chapter

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 Copy Chapter

• 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 Copy Chapter

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.

File: deploy/helm/pulse/README.md Copy Chapter

pulse

Helm chart for deploying the Pulse hub and optional Docker, Kubernetes, or OpenShift monitoring agent.

Homepage: https://github.com/rcourtman/Pulse

Maintainers Copy Chapter

Source Code Copy Chapter

• https://github.com/rcourtman/Pulse

Values Copy Chapter

Autogenerated from chart metadata using helm-docs v1.14.2

File: docs/api/SCHEDULER_HEALTH.md Copy Chapter

🩺 Scheduler Health API

Endpoint: GET /api/monitoring/scheduler/health
Auth: Required (Authorization: Bearer <token>, X-API-Token, or session cookie)

Returns a real-time snapshot of the adaptive scheduler, including queue state, circuit breakers, and dead-letter tasks.

📦 Response Format Copy Chapter

{
  "updatedAt": "2025-10-20T13:05:42Z",
  "enabled": true,
  "queue": {
    "depth": 7,
    "dueWithinSeconds": 2,
    "perType": { "pve": 4, "pbs": 2 }
  },
  "deadLetter": {
    "count": 1,
    "tasks": [
      {
        "instance": "pbs-main",
        "type": "pbs",
        "nextRun": "2025-10-20T13:06:40Z",
        "lastError": "connection timeout",
        "failures": 5
      }
    ]
  },
  "breakers": [
    {
      "instance": "pve-a",
      "type": "pve",
      "state": "half_open",
      "failures": 3,
      "retryAt": "2025-10-20T13:06:15Z"
    }
  ],
  "staleness": [
    {
      "instance": "pve-a",
      "type": "pve",
      "lastSuccess": "2025-10-20T13:05:10Z",
      "stalenessSeconds": 32,
      "stalenessScore": 0.12
    }
  ],
  "instances": [
    {
      "key": "pve::pve-a",
      "type": "pve",
      "displayName": "Pulse PVE Cluster",
      "instance": "pve-a",
      "connection": "https://pve-a:8006",
      "pollStatus": {
        "lastSuccess": "2025-10-20T13:05:10Z",
        "lastError": {
          "at": "2025-10-20T13:05:40Z",
          "message": "connection timeout",
          "category": "transient"
        },
        "consecutiveFailures": 2,
        "firstFailureAt": "2025-10-20T13:05:20Z"
      },
      "breaker": {
        "state": "half_open", // closed, open, half_open
        "retryAt": "2025-10-20T13:06:15Z",
        "failureCount": 3,
        "since": "2025-10-20T12:58:10Z",
        "lastTransition": "2025-10-20T13:05:40Z"
      },
      "deadLetter": {
        "present": false,
        "reason": "",
        "retryCount": 0
      }
    }
  ]
}

🔍 Key Fields Copy Chapter

Instances (`instances`) Copy Section

The authoritative source for per-instance health.

• pollStatus: lastSuccess timestamp, lastError details, consecutiveFailures count.
• breaker: state (closed/open/half_open), retryAt next retry, since state start, lastTransition timestamp.
• deadLetter: present flag, reason (e.g., permanent_failure), retryCount, nextRetry if scheduled.

Top-Level Queue and DLQ Copy Section

• queue: Snapshot of the active task queue (depth + per-type counts).
• deadLetter: Aggregate DLQ summary plus up to 25 queued tasks.

Optional Summaries Copy Section

• breakers: Only breakers that are not in default closed/zero-failure state.
• staleness: Snapshot of staleness scores (if the tracker is enabled).

🛠️ Common Queries (jq) Copy Chapter

Find Failing Instances:

curl -s http://HOST:7655/api/monitoring/scheduler/health | \
jq '.instances[] | select(.pollStatus.consecutiveFailures > 0) | {key, failures: .pollStatus.consecutiveFailures}'

Check Dead Letter Queue:

curl -s http://HOST:7655/api/monitoring/scheduler/health | \
jq '.instances[] | select(.deadLetter.present) | {key, reason: .deadLetter.reason}'

Find Open Breakers:

curl -s http://HOST:7655/api/monitoring/scheduler/health | \
jq '.instances[] | select(.breaker.state != "closed") | {key, state: .breaker.state}'

File: docs/monitoring/ADAPTIVE_POLLING.md Copy Chapter

📉 Adaptive Polling

Pulse uses an adaptive scheduler to optimize polling based on instance health and activity.

🧠 Architecture Copy Chapter

• Scheduler: Calculates intervals based on health/staleness.
• Priority Queue: Min-heap keyed by NextRun.
• Circuit Breaker: Prevents hot loops on failing instances using success/failure counters.
• Backoff: Exponential retry delays (5s min to 5m max).
• Worker Pool: One worker per configured instance (PVE/PBS/PMG), capped at 10.
• Global Concurrency Cap: At most 2 polling cycles run at once to avoid resource spikes.

🔬 Implementation Details (Developer Info) Copy Chapter

Staleness Scoring Copy Section

The AdaptiveScheduler (internal/monitoring/scheduler.go) relies on the StalenessTracker to compute a StalenessScore (0.0 to 1.0) based on how long it has been since the last successful poll.

• 0.0 = fresh (recent success)
• 1.0 = very stale or never succeeded

The staleness score is normalized against AdaptivePollingMaxInterval (default 5 minutes).

The scheduler applies Exponential Smoothing (alpha 0.6) and a small jitter (5%) to avoid oscillation.

Additional influences:

• Error penalty: retries tighten the interval based on the error count.
• Queue stretch: large queues gently stretch intervals to avoid overload.

Circuit Breaker Recovery Copy Section

The circuitBreaker (internal/monitoring/circuit_breaker.go) follows a standard state machine:

1. Closing the Circuit: One successful poll moves Half-Open → Closed and resets failure count.
2. Backoff Calculation: Retries use exponential backoff starting at 5s (multiplier 2, jitter 0.2) capped at 5m.
3. Transient vs. Permanent:
   • Transient errors (retryable) are retried up to 5 times before moving to the Dead Letter Queue.
   • Permanent errors move directly to the Dead Letter Queue.

Note: When AdaptivePollingMaxInterval is set to 15 seconds or less, the retry backoff is shortened (750ms initial, 4s max) to keep fast feedback loops during tight polling windows.

⚙️ Configuration Copy Chapter

Adaptive polling is disabled by default.

UI Copy Section

There is currently no dedicated UI for adaptive polling. Use environment variables or system.json.

Environment Variables Copy Section

system.json Copy Section

You can also set adaptivePollingEnabled (and related interval fields) in system.json and restart Pulse.

📊 Metrics Copy Chapter

Exposed at :9091/metrics.

⚡ Circuit Breaker Copy Chapter

Dead Letter Queue: After 5 transient or 1 permanent failure, tasks move to DLQ (30m retry).

🩺 Health API Copy Chapter

GET /api/monitoring/scheduler/health (Auth required)

Returns:

• Queue depth & breakdown.
• Dead-letter tasks.
• Circuit breaker states.
• Per-instance staleness.

File: docs/monitoring/METRICS_DATA_FLOW.md Copy Chapter

Metrics Data Flow (Sparklines vs History)

Quick summary Copy Chapter

• Sparklines/trends toggle: client ring buffer + short-term in-memory server history via /api/charts (fast, not durable).
• Guest History tab: persistent SQLite metrics store via /api/metrics-store/history (durable, long-range, downsampled).

Path A: Sparklines ("Trends" toggle) Copy Chapter

1. Server polling writes to in-memory history: monitor.go -> metricsHistory.AddGuestMetric/AddNodeMetric.
2. /api/charts (handleCharts) reads from metricsHistory via monitor.GetGuestMetrics/GetNodeMetrics.
3. Client toggles to sparklines: metricsViewMode.ts -> seedFromBackend() -> ChartsAPI.getCharts() -> ring buffer in metricsHistory.ts.
4. While in sparklines mode, metricsSampler.ts samples websocket state every 30s and appends to the ring buffer; localStorage saves periodically.

Path B: Guest drawer History tab Copy Chapter

1. Server polling writes to SQLite store: monitor.go -> metricsStore.Write(resourceType, ...).
2. /api/metrics-store/history (handleMetricsHistory) queries metrics.Store (Query/QueryAll) with tiered downsampling and license gating.
3. GuestDrawer History charts call ChartsAPI.getMetricsHistory() for CPU/memory/disk and ranges 24h/7d/30d/90d.

Architecture notes Copy Chapter

• In-memory retention is NewMetricsHistory(1000, 24h) (monitor.go). At 10s polling, 1000 points covers ~2.8h of data.
• /api/charts uses a two-tier strategy: ranges ≤ 2h are served from the in-memory buffer; longer ranges (4h, 8h, 24h, 7d, 30d) fall back to the SQLite persistent store with LTTB downsampling to ~500 points per metric.
• Frontend sparkline ring buffer keeps up to 8h locally (metricsHistory.ts).
• Docker resource keys differ: in-memory uses docker:, persistent store uses resourceType=dockerContainer. The GetGuestMetricsForChart method maps between these automatically.
• History charts in the guest drawer use /api/metrics-store/history (SQLite) for ranges 24h/7d/30d/90d.

File: docs/monitoring/PROMETHEUS_METRICS.md Copy Chapter

📊 Prometheus Metrics

Pulse exposes metrics at /metrics (default port 9091).

Example scrape target:

• http://127.0.0.1:9091/metrics

This listener is separate from the main UI/API port (7655) and binds to loopback by default. Use PULSE_METRICS_BIND_ADDRESS only when a scraper must reach Pulse from another host.

When PULSE_METRICS_TOKEN is set, Pulse refuses to serve that bearer token on a non-loopback plaintext listener unless PULSE_METRICS_ALLOW_INSECURE_REMOTE=true is explicitly set. Prefer a local Prometheus agent, SSH tunnel, VPN-private scrape path, or TLS/mTLS reverse proxy for remote scraping.

In Docker and Kubernetes you must expose 9091 explicitly if you want to scrape it from outside the container/pod, and the container/pod should set PULSE_METRICS_BIND_ADDRESS to the intended listener address.

Helm note: the current chart exposes only port 7655, so Prometheus scraping requires an additional Service that targets 9091 (and a matching ServiceMonitor).

🌐 HTTP Ingress Copy Chapter

🔄 Polling & Nodes Copy Chapter

🧠 Scheduler Health Copy Chapter

⚡ Diagnostics Cache Copy Chapter

🚨 Alert Lifecycle Copy Chapter

Operational Trust Copy Chapter

Operational Trust metrics use closed low-cardinality labels. They never label
series with resource, operational-record, evidence, actor, provider-instance,
or notification-destination IDs.

Example rollout alerts:

• increase(pulse_operational_trust_active_count_mismatch_total[15m]) > 0
• increase(pulse_operational_trust_notification_delivery_total{outcome="dead_letter"}[15m]) > 0
• increase(pulse_operational_trust_action_verification_total{outcome=~"contradicted|timed_out"}[30m]) > 0

🚨 Alerting Examples Copy Chapter

• High Error Rate: rate(pulse_http_request_errors_total[5m]) > 0.05
• Stale Node: pulse_monitor_node_poll_staleness_seconds > 300
• Breaker Open: pulse_scheduler_breaker_state == 2

File: docs/operations/ADAPTIVE_POLLING_ROLLOUT.md Copy Chapter

🚀 Adaptive Polling Rollout

Safely enable dynamic scheduling.

📋 Pre-Flight Copy Chapter

1. Snapshot Health:
   bash Copy

   curl -s -H "X-API-Token: $TOKEN" http://localhost:7655/api/monitoring/scheduler/health | jq .

2. Check Metrics: Ensure pulse_monitor_poll_queue_depth is stable.

🟢 Enable Copy Chapter

Choose one method:

• UI: Not currently exposed in the UI (use CLI or env vars).
• CLI:
  • systemd/LXC: jq '.adaptivePollingEnabled=true' /etc/pulse/system.json > /tmp/system.json && sudo mv /tmp/system.json /etc/pulse/system.json
  • Docker/Kubernetes: edit /data/system.json in the volume and restart the container/pod
• Env: ADAPTIVE_POLLING_ENABLED=true (Docker/K8s).

🔍 Monitor (First 15m) Copy Chapter

Watch for stability:

watch -n 5 'curl -s http://localhost:9091/metrics | grep pulse_monitor_poll_queue_depth'

• Success: Queue depth < 50, no permanent errors.
• Failure: High queue depth, open breakers.

↩️ Rollback Copy Chapter

If instability occurs > 10m:

1. Disable: Remove the env var override or set adaptivePollingEnabled=false in system.json.
2. Restart: Required if using Env/CLI overrides.
3. Verify: Confirm queue drains.

File: docs/operations/AUTO_UPDATE.md Copy Chapter

🔄 Automatic Updates

Manage Pulse auto-updates on host-mode installations.

Note: Docker/Kubernetes users should manage updates via their orchestrator.

⚙️ Components Copy Chapter

Release channel note: the systemd timer script tracks GitHub releases/latest (stable). The internal rc channel only affects manual and in-app pre-release selection. stable is the only recommended channel for paid or production environments.

🚀 Enable/Disable Copy Chapter

Via UI (Recommended) Copy Section

Settings → System → Updates.

Via CLI Copy Section

# Enable
sudo jq '.autoUpdateEnabled=true' /etc/pulse/system.json > /tmp/system.json && sudo mv /tmp/system.json /etc/pulse/system.json
sudo systemctl enable --now pulse-update.timer

# Disable
sudo jq '.autoUpdateEnabled=false' /etc/pulse/system.json > /tmp/system.json && sudo mv /tmp/system.json /etc/pulse/system.json
sudo systemctl disable --now pulse-update.timer

🧪 Manual Run Copy Chapter

Test the update process:

sudo systemctl start pulse-update.service
journalctl -u pulse-update -f

🔍 Observability Copy Chapter

• History: in-app updates are tracked via GET /api/updates/history (admin auth required) and stored in update-history.jsonl under /etc/pulse or /data. The systemd timer script does not record update history entries.
• Logs: journalctl -u pulse-update -f or journalctl -t pulse-auto-update -f for timer runs. In-app updates write detailed logs to /var/log/pulse/update-<timestamp>.log.

↩️ Rollback Copy Chapter

If an update fails:

1. Check logs: journalctl -u pulse-update -f or journalctl -t pulse-auto-update -f.
2. The timer script keeps a temporary backup under /tmp/pulse-backup-<timestamp> during the update; failures auto-restore from that backup and then clean it up.
3. If you need to pin a specific version, re-run the installer with a version:
   bash Copy

   sudo /bin/update --version vX.Y.Z

   /bin/update is installed by the supported Pulse server installer. If your host does not have it yet, use the signed server-installer flow in INSTALL.md. Agent updates still use the /install.sh command generated in Settings → Infrastructure → Install on a host.