Pulse for Proxmox VE

A lightweight monitoring application for Proxmox VE that displays real-time status for VMs and containers via a simple web interface.

📸 Screenshots

Click to view more screenshots

Desktop Views:

PBS Tab	Backups Tab

Storage Tab	Line Graph Toggle

Mobile Views:

Mobile Dashboard	Mobile PBS View	Mobile Backups View

🚀 Quick Start

Choose your preferred installation method:

📦 Easiest: Proxmox Community Scripts (Recommended)

One-command installation in a new LXC container:

bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pulse.sh)"

This will create a new LXC container and install Pulse automatically. Visit the Community Scripts page for details.

🐳 Docker Compose (Pre-built Image)

For existing Docker hosts:

mkdir pulse-config && cd pulse-config
# Create docker-compose.yml (see Docker section)
docker compose up -d
# Configure via web interface at http://localhost:7655

🛠️ Manual LXC Installation

For existing LXC containers:

curl -sLO https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install-pulse.sh
chmod +x install-pulse.sh
sudo ./install-pulse.sh

✅ Prerequisites

Before installing Pulse, ensure you have:

For Proxmox VE:

Proxmox VE 7.x or 8.x running
Admin access to create API tokens
Network connectivity between Pulse and Proxmox (ports 8006/8007)

For Pulse Installation:

Community Scripts: Just a Proxmox host (handles everything automatically)
Docker: Docker & Docker Compose installed
Manual LXC: Existing Debian/Ubuntu LXC with internet access

🚀 Deployment Options

Proxmox Community Scripts (Automated LXC)

✨ Easiest method - fully automated LXC creation and setup:

bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pulse.sh)"

This script will:

Create a new LXC container automatically
Install all dependencies (Node.js, npm, etc.)
Download and set up Pulse
Set up systemd service

After installation: Access Pulse at http://<lxc-ip>:7655 and configure via the web interface

Visit the Community Scripts page for more details.

Docker Compose (Recommended for Existing Hosts)

For existing Docker hosts - uses pre-built image:

Prerequisites:

Docker (Install Docker)
Docker Compose (Install Docker Compose)

Steps:

Create a Directory: Make a directory for your Docker configuration files:
```
mkdir pulse-config
cd pulse-config
```

Create docker-compose.yml file: Create a file named docker-compose.yml in this directory with the following content:

# docker-compose.yml
services:
  pulse-server:
    image: rcourtman/pulse:latest # Pulls the latest pre-built image
    container_name: pulse
    restart: unless-stopped
    ports:
      # Map host port 7655 to container port 7655
      # Change the left side (e.g., "8081:7655") if 7655 is busy on your host
      - "7655:7655"
    volumes:
      # Persistent volume for configuration data
      # Configuration persists across container updates
      - pulse_config:/usr/src/app/config

# Define persistent volumes
volumes:
  pulse_config:
    driver: local

Run: Start the container:
```
docker compose up -d
```
Access and Configure: Open your browser to http://<your-docker-host-ip>:7655 and configure through the web interface.

Manual LXC Installation

For existing Debian/Ubuntu LXC containers:

Prerequisites:

A running Proxmox VE host
An existing Debian or Ubuntu LXC container with network access to Proxmox
- Tip: Use Community Scripts to easily create one: bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

Steps:

Access LXC Console: Log in to your LXC container (usually as root).

Download and Run Script:

# Ensure you are in a suitable directory, like /root or /tmp
curl -sLO https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install-pulse.sh
chmod +x install-pulse.sh
./install-pulse.sh

Follow Prompts: The script guides you through:
- Installing dependencies (git, curl, nodejs, npm, sudo).
- Setting up Pulse as a systemd service (pulse-monitor.service).
- Optionally enabling automatic updates via cron.
Access and Configure: The script will display the URL (e.g., http://<LXC-IP-ADDRESS>:7655). Open this URL and configure via the web interface.

For update instructions, see the Updating Pulse section.

Development Setup (Docker Compose)

Use this method if you have cloned the repository and want to build and run the application from the local source code.

Get Files: Clone the repository (git clone https://github.com/rcourtman/Pulse.git && cd Pulse)
Run: docker compose up --build -d (The included docker-compose.yml uses the build: context by default).
Access and Configure: Open your browser to http://localhost:7655 (or your host IP if Docker runs remotely) and configure via the web interface.

🛠️ Configuration

Pulse features a comprehensive web-based configuration system accessible through the settings menu. No manual file editing required!

Web Interface Configuration (Recommended)

First-time Setup:

Access Pulse at http://your-host:7655
The settings modal will automatically open for initial configuration
Configure all your Proxmox VE and PBS servers through the intuitive web interface
Test connections with built-in connectivity verification
Save and reload configuration without restarting the application

Ongoing Management:

Click the settings icon (⚙️) in the top-right corner anytime
Add/modify multiple PVE and PBS endpoints
Configure alert thresholds and service intervals
All changes are applied immediately

Environment Variables (Development/Advanced)

Note: Most users should use the web-based configuration interface. Environment variables are primarily for development and advanced deployment scenarios.

For development setups or infrastructure-as-code deployments, Pulse can also be configured using environment variables in a .env file.

Proxmox VE (Primary Environment)

These are the minimum required variables:

PROXMOX_HOST: URL of your Proxmox server (e.g., https://192.168.1.10:8006).
PROXMOX_TOKEN_ID: Your API Token ID (e.g., user@pam!tokenid).
PROXMOX_TOKEN_SECRET: Your API Token Secret.

Optional variables:

PROXMOX_NODE_NAME: A display name for this endpoint in the UI (defaults to PROXMOX_HOST).
PROXMOX_ALLOW_SELF_SIGNED_CERTS: Set to true if your Proxmox server uses self-signed SSL certificates. Defaults to false.
PORT: Port for the Pulse server to listen on. Defaults to 7655.
BACKUP_HISTORY_DAYS: Number of days of backup history to display (defaults to 365 for full year calendar view).
(Username/Password fallback exists but API Token is strongly recommended)

Alert System Configuration (Optional)

Pulse includes a comprehensive alert system that monitors resource usage and system status:

# Alert System Configuration
ALERT_CPU_ENABLED=true
ALERT_MEMORY_ENABLED=true
ALERT_DISK_ENABLED=true
ALERT_DOWN_ENABLED=true

# Alert thresholds (percentages)
ALERT_CPU_THRESHOLD=85
ALERT_MEMORY_THRESHOLD=90
ALERT_DISK_THRESHOLD=95

# Alert durations (milliseconds - how long condition must persist)
ALERT_CPU_DURATION=300000       # 5 minutes
ALERT_MEMORY_DURATION=300000    # 5 minutes  
ALERT_DISK_DURATION=600000      # 10 minutes
ALERT_DOWN_DURATION=60000       # 1 minute

Alert features include:

Real-time notifications with toast messages
Multi-severity alerts (Critical, Warning, Resolved)
Duration-based triggering (alerts only fire after conditions persist)
Automatic resolution when conditions normalize
Alert history tracking
Webhook and email notification support
Alert acknowledgment and escalation

Custom Per-VM/LXC Alert Thresholds (Optional)

For advanced monitoring scenarios, Pulse supports custom alert thresholds on a per-VM/LXC basis through the web interface:

Use Cases:

Storage/NAS VMs: Set higher memory thresholds (e.g., 95%/99%) for VMs that naturally use high memory for disk caching
Application Servers: Set lower CPU thresholds (e.g., 70%/85%) for performance-critical applications
Development VMs: Set custom disk thresholds (e.g., 75%/90%) for early storage warnings

Configuration:

Navigate to Settings → Custom Thresholds tab
Click "Add Custom Threshold"
Select your VM/LXC from the dropdown
Configure custom CPU, Memory, and/or Disk thresholds
Save configuration

Features:

Migration-aware: Thresholds follow VMs when they migrate between cluster nodes
Per-metric control: Configure only the metrics you need (CPU, Memory, Disk)
Visual indicators: VMs with custom thresholds show a blue "T" badge in the dashboard
Fallback behavior: VMs without custom thresholds use global settings

Note: For a Proxmox cluster, you only need to provide connection details for one node. Pulse automatically discovers other cluster members.

Webhook Notifications (Optional)

Pulse supports webhook notifications for alerts, compatible with Discord, Slack, and Microsoft Teams:

Configuration via Web Interface:

Navigate to Settings → Alerts tab
Enable "Webhook Notifications"
Enter your webhook URL
Click "Test Webhook" to verify connectivity
Save configuration

Webhook URL Examples:

Discord: https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
Slack: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
Teams: https://outlook.office.com/webhook/YOUR-WEBHOOK-URL

Features:

Rich embed formatting with color-coded severity levels
Automatic retry on failure
Dual payload format supporting multiple platforms
Real-time alert notifications for:
- Resource threshold violations (CPU, Memory, Disk)
- VM/Container availability changes
- Alert escalations
- Alert resolutions

Email Notifications (Optional)

Configure SMTP email notifications for alerts:

Configuration via Web Interface:

Navigate to Settings → Alerts tab
Enable "Email Notifications"
Configure SMTP settings:
- SMTP Host: Your email server (e.g., smtp.gmail.com)
- SMTP Port: Usually 587 for TLS, 465 for SSL, 25 for unencrypted
- Username: Your email address or username
- Password: Your email password (use App Password for Gmail)
- From Address: Sender email address
- To Addresses: Recipient(s), comma-separated for multiple
- Use SSL: Enable for SSL/TLS encryption
Click "Test Email" to verify configuration
Save settings

Gmail Configuration Example:

Enable 2-factor authentication on your Google account
Generate an App Password: Google Account → Security → App passwords
Use settings:
- Host: smtp.gmail.com
- Port: 587
- Username: Your Gmail address
- Password: Your App Password (not regular password)
- Use SSL: Enabled

Multiple Proxmox Environments (Optional)

To monitor separate Proxmox environments (e.g., different clusters, sites) in one Pulse instance, add numbered variables:

PROXMOX_HOST_2, PROXMOX_TOKEN_ID_2, PROXMOX_TOKEN_SECRET_2
PROXMOX_HOST_3, PROXMOX_TOKEN_ID_3, PROXMOX_TOKEN_SECRET_3
...and so on.

Optional numbered variables also exist (e.g., PROXMOX_ALLOW_SELF_SIGNED_CERTS_2, PROXMOX_NODE_NAME_2).

Advanced Configuration Options

For performance tuning and specialized deployments:

# Performance & Retention
BACKUP_HISTORY_DAYS=365          # Backup history retention (default: 365 days)

# Update System Configuration
UPDATE_CHANNEL_PREFERENCE=stable  # Force specific update channel (stable/rc)
UPDATE_TEST_MODE=false            # Enable test mode for update system

# Development Variables
NODE_ENV=development              # Enable development mode features
DEBUG=pulse:*                     # Enable debug logging for specific modules

# Docker Detection (automatically set)
DOCKER_DEPLOYMENT=true            # Automatically detected in Docker environments

Performance Notes:

BACKUP_HISTORY_DAYS affects calendar heatmap visualization and memory usage
Lower values improve performance for environments with extensive backup histories
Debug logging should only be enabled for troubleshooting as it increases log verbosity

Proxmox Backup Server (PBS) (Optional)

To monitor PBS instances:

Primary PBS Instance:

PBS_HOST: URL of your PBS server (e.g., https://192.168.1.11:8007).
PBS_TOKEN_ID: Your PBS API Token ID (e.g., user@pbs!tokenid). See Creating a Proxmox Backup Server API Token.
PBS_TOKEN_SECRET: Your PBS API Token Secret.
PBS_NODE_NAME: Important! The internal hostname of your PBS server (e.g., pbs-server-01). This is usually required for API token auth because the token might lack permission to auto-discover the node name. See details below.
PBS_ALLOW_SELF_SIGNED_CERTS: Set to true for self-signed certificates. Defaults to false.
PBS_PORT: PBS API port. Defaults to 8007.

Additional PBS Instances:

To monitor multiple PBS instances, add numbered variables, starting with _2:

PBS_HOST_2, PBS_TOKEN_ID_2, PBS_TOKEN_SECRET_2
PBS_HOST_3, PBS_TOKEN_ID_3, PBS_TOKEN_SECRET_3
...and so on.

Optional numbered variables also exist for additional PBS instances (e.g., PBS_NODE_NAME_2, PBS_ALLOW_SELF_SIGNED_CERTS_2, PBS_PORT_2). Each PBS instance, whether primary or additional, requires its respective PBS_NODE_NAME or PBS_NODE_NAME_n to be set if API token authentication is used and the token cannot automatically discover the node name.

Why PBS_NODE_NAME (or PBS_NODE_NAME_n) is Required (Click to Expand)

Pulse needs to query task lists specific to the PBS node (e.g., /api2/json/nodes/{nodeName}/tasks). It attempts to discover this node name automatically by querying /api2/json/nodes. However, this endpoint is often restricted for API tokens (returning a 403 Forbidden error), even for tokens with high privileges, unless the Sys.Audit permission is granted on the root path (/).

Therefore, setting PBS_NODE_NAME in your .env file is the standard and recommended way to ensure Pulse can correctly query task endpoints when using API token authentication. If it's not set and automatic discovery fails due to permissions, Pulse will be unable to fetch task data (backups, verifications, etc.).

How to find your PBS Node Name:

SSH: Log into your PBS server via SSH and run hostname.
UI: Log into the PBS web interface. The hostname is typically displayed on the Dashboard under Server Status.

Example: If your PBS connects via https://minipc-pbs.lan:8007 but its internal hostname is proxmox-backup-server, set:

PBS_HOST=https://minipc-pbs.lan:8007
PBS_NODE_NAME=proxmox-backup-server

Creating a Proxmox API Token

Using an API token is the recommended authentication method.

Steps to Create a PVE API Token (Click to Expand)

Log in to the Proxmox VE web interface.
Create a dedicated user (optional but recommended):
- Go to Datacenter → Permissions → Users.
- Click Add. Enter a User name (e.g., "pulse-monitor"), set Realm to Proxmox VE authentication server (pam), set a password, ensure Enabled. Click Add.
Create an API token:
- Go to Datacenter → Permissions → API Tokens.
- Click Add.
- Select the User (e.g., "pulse-monitor@pam") or root@pam.
- Enter a Token ID (e.g., "pulse").
- Leave Privilege Separation checked. Click Add.
- Important: Copy the Secret value immediately. It's shown only once.
Assign permissions (to User and Token):
- Go to Datacenter → Permissions.
- Add User Permission: Click Add → User Permission. Path: /, User: pulse-monitor@pam, Role: PVEAuditor, check Propagate. Click Add.
- Add Token Permission: Click Add → API Token Permission. Path: /, API Token: pulse-monitor@pam!pulse, Role: PVEAuditor, check Propagate. Click Add.
- Note: The PVEAuditor role at the root path (/) with Propagate is crucial.
Update .env: Set PROXMOX_TOKEN_ID (e.g., pulse-monitor@pam!pulse) and PROXMOX_TOKEN_SECRET (the secret you copied).

Creating a Proxmox Backup Server API Token

If monitoring PBS, create a token within the PBS interface.

Steps to Create a PBS API Token (Click to Expand)

Log in to the Proxmox Backup Server web interface.
Create a dedicated user (optional but recommended):
- Go to Configuration → Access Control → User Management.
- Click Add. Enter User ID (e.g., "pulse-monitor@pbs"), set Realm (likely pbs), add password. Click Add.
Create an API token:
- Go to Configuration → Access Control → API Token.
- Click Add.
- Select User (e.g., "pulse-monitor@pbs") or root@pam.
- Enter Token Name (e.g., "pulse").
- Leave Privilege Separation checked. Click Add.
- Important: Copy the Secret value immediately.
Assign permissions (to User and Token):
- Go to Configuration → Access Control → Permissions.
- Add User Permission: Click Add → User Permission. Path: /, User: pulse-monitor@pbs, Role: Audit, check Propagate. Click Add.
- Add API Token Permission: Click Add → API Token Permission. Path: /, API Token: pulse-monitor@pbs!pulse, Role: Audit, check Propagate. Click Add.
- Note: The Audit role at root path (/) with Propagate is crucial for both user and token.
Update .env: Set PBS_TOKEN_ID (e.g., pulse-monitor@pbs!pulse) and PBS_TOKEN_SECRET.

Required Permissions

Proxmox VE:
- Basic monitoring: The PVEAuditor role assigned at path / with Propagate enabled.
- To view PVE backup files: Additionally requires PVEDatastoreAdmin role on /storage (or specific storage paths).
Important: Storage Content Visibility (Click to Expand)

Due to Proxmox API limitations, viewing backup files in storage requires elevated permissions:
- PVEAuditor alone is NOT sufficient to list storage contents via API
- You must grant PVEDatastoreAdmin role which includes Datastore.Allocate permission
- This applies even for read-only access to backup listings
To fix empty PVE backup listings:
```
# Grant storage admin permissions to your API token
pveum acl modify /storage --tokens user@realm!tokenname --roles PVEDatastoreAdmin
```
Permissions included in PVEAuditor (Click to Expand)
- `Datastore.Audit` - `Permissions.Read` (implicitly included) - `Pool.Audit` - `Sys.Audit` - `VM.Audit`
Proxmox Backup Server: The Audit role assigned at path / with Propagate enabled is recommended.

Running from Release Tarball

For users who prefer not to use Docker or the LXC script, pre-packaged release tarballs are available.

Prerequisites:

Node.js (Version 18.x or later recommended)
npm (comes with Node.js)
tar command (standard on Linux/macOS, available via tools like 7-Zip or WSL on Windows)

Steps:

Download: Go to the Pulse GitHub Releases page. Download the pulse-vX.Y.Z.tar.gz file for the desired release.

Extract: Create a directory and extract the tarball:

mkdir pulse-app
cd pulse-app
tar -xzf /path/to/downloaded/pulse-vX.Y.Z.tar.gz
# This creates a directory like pulse-vX.Y.Z/
cd pulse-vX.Y.Z

Run: Start the application using npm:
```
npm start
```
(Note: The tarball includes pre-installed production dependencies, so npm install is not typically required unless you encounter issues.)
Access and Configure: Open your browser to http://<your-server-ip>:7655 and configure via the web interface.

️ Running the Application (Node.js - Development)

For development purposes or running directly from source, see the DEVELOPMENT.md guide. This involves cloning the repository, installing dependencies using npm install in both the root and server directories, and running npm run dev or npm run start.

✨ Features

Core Monitoring

Lightweight monitoring for Proxmox VE nodes, VMs, and Containers
Real-time status updates via WebSockets
Simple, responsive web interface with dark/light theme support
Multi-environment PVE monitoring support (monitor multiple clusters/sites)
Efficient polling: Stops API polling when no clients are connected

Advanced Alert System

Configurable alert thresholds for CPU, Memory, Disk, and VM/CT availability
Custom per-VM/LXC alert thresholds (perfect for storage VMs, application servers, etc.)
Migration-aware thresholds that follow VMs across cluster nodes
Multi-severity alerts: Info, Warning, Critical, and Resolved states
Duration-based triggering (alerts only fire after conditions persist)
Alert history tracking with comprehensive metrics
Alert acknowledgment and suppression capabilities
Alert escalation for unacknowledged critical alerts

Notification Systems

Webhook notifications for Discord, Slack, and Microsoft Teams
- Rich embed formatting with color-coded severity
- Dual payload format support
- Built-in webhook testing
Email notifications via SMTP
- Multiple recipient support
- SSL/TLS encryption
- Gmail App Password support
- Test email functionality

Enhanced Update System

Smart Version Switching between stable and RC releases with clear commit differences
Consolidated Update Mechanism using proven install script for reliability
Real-time Progress Tracking with detailed commit information and GitHub links
Automatic Backup & Restore of configuration during updates
Context-Aware Updates showing exactly what changes with each version switch
Dual Update Channels with persistent preference management

Update Channels

Stable Channel: Production-ready releases (e.g., v3.27.1)
- Thoroughly tested releases for production environments
- Automatic updates only to stable versions
- Recommended for critical infrastructure monitoring
RC Channel: Release candidates with latest features (e.g., v3.28.0-rc1)
- Early access to new features and improvements
- Automated releases with each development commit
- Perfect for testing and non-critical environments
Channel Persistence: Your update preference is maintained across all updates
Smart Switching: See exact commit differences when switching between channels

Backup Monitoring

Comprehensive backup monitoring:
- Proxmox Backup Server (PBS) snapshots and tasks
- PVE backup files on local and shared storage
- VM/CT snapshot tracking with calendar heatmap visualization
Enhanced backup health card with health score calculation
Recent coverage metrics showing protection status
Backup type filtering with styled badges

Understanding Backup Types in Pulse

Pulse monitors three distinct types of backups:

PBS Backups (Purple indicator ●)
- Backups stored in Proxmox Backup Server
- Accessed via PBS API with deduplication and verification features
- Requires separate PBS API token configuration
PVE Backups (Orange indicator ●)
- Backups stored on any Proxmox VE storage (NFS, CIFS, local, etc.)
- All non-PBS backup storage is considered "PVE storage"
- Accessed via Proxmox VE API
Snapshots (Yellow indicator ●)
- VM/CT point-in-time snapshots (not full backups)
- Stored locally on the Proxmox node

Important: If you have PBS configured as storage in Proxmox VE, those backups are accessed via the PBS API directly, not through PVE storage. This prevents double-counting of PBS backups.

Performance & UI

Virtual scrolling for handling large VM/container lists efficiently
Metrics history with 1-hour retention using circular buffers
Network anomaly detection with automatic baseline learning
Responsive design optimized for desktop and mobile
UI scale adjustment for different screen sizes
Persistent filter states across sessions

Management & Diagnostics

Built-in update manager with web-based updates (non-Docker)
Comprehensive diagnostic tool with API permission testing
Privacy-protected diagnostic exports for troubleshooting
Real-time connectivity testing for all configured endpoints
Automatic configuration validation

Deployment & Integration

Docker support with pre-built images
LXC installation script
Proxmox Community Scripts integration
systemd service management
Automatic update capability via cron

🏗️ Architecture

Technology Stack

Frontend: Vue.js 3 with vanilla JavaScript modules
Backend: Node.js 20+ with Express 5
Styling: Tailwind CSS v3.4.4 with custom scrollbar plugin
Build System: npm scripts with PostCSS and Tailwind compilation
Real-time Communication: WebSocket integration with Socket.IO

Project Structure

pulse/
├── src/public/          # Frontend application
│   ├── js/ui/          # Modular UI components (Vue.js)
│   ├── css/            # Styling and themes
│   └── output.css      # Compiled Tailwind styles
├── server/             # Backend API and services
│   ├── routes/         # Express route handlers
│   ├── services/       # Business logic modules
│   └── *.js           # Core server components
├── scripts/           # Installation and utility scripts
└── config/           # Configuration management

Key Design Principles

Modular Architecture: Clean separation between UI components and server modules
Performance Optimized: Virtual scrolling, circular buffers, and efficient polling
Real-time Updates: WebSocket-based live data streaming
Multi-platform Support: Docker, LXC, and native deployment options
Configuration-driven: Web-based configuration with automatic validation

💻 System Requirements

Node.js: Version 18.x or later (if building/running from source).
NPM: Compatible version with Node.js.
Docker & Docker Compose: Latest stable versions (if using container deployment).
Proxmox VE: Version 7.x or 8.x recommended.
Proxmox Backup Server: Version 2.x or 3.x recommended (if monitored).
Web Browser: Modern evergreen browser.

🔄 Updating Pulse

Web-Based Updates (Non-Docker)

For non-Docker installations, Pulse includes a built-in update mechanism:

Open the Settings modal (gear icon in the top right)
Scroll to the "Software Updates" section
Click "Check for Updates"
If an update is available, review the release notes
Click "Apply Update" to install it automatically

The update process:

Backs up your configuration files
Downloads and applies the update
Preserves your settings
Automatically restarts the application

Community Scripts LXC Installation

If you installed using the Community Scripts method, simply re-run the original installation command:

bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pulse.sh)"

The script will detect the existing installation and update it automatically.

Docker Compose Installation

Docker deployments must be updated by pulling the new image:

cd /path/to/your/pulse-config
docker compose pull
docker compose up -d

This pulls the latest image and recreates the container with the new version.

Note: The web-based update feature will detect Docker deployments and provide these instructions instead of attempting an in-place update.

Manual LXC Installation

If you used the manual installation script, update by re-running it:

# Navigate to where you downloaded the script
cd /path/to/script/directory
./install-pulse.sh

Or run non-interactively (useful for automated updates):

./install-pulse.sh --update

Managing the Service:

Check status: sudo systemctl status pulse-monitor.service
View logs: sudo journalctl -u pulse-monitor.service -f
Restart: sudo systemctl restart pulse-monitor.service

Automatic Updates: If you enabled automatic updates during installation, they run via cron. Check logs in /var/log/pulse_update.log.

Release Tarball Installation

To update a tarball installation:

Download the latest release from GitHub Releases
Stop the current application
Extract the new tarball to a new directory
Start the application: npm start
Your configuration will be preserved automatically

Development/Source Installation

If running from source code:

For stable releases (production):

cd /path/to/pulse
git checkout main
git pull origin main
npm install
npm run build:css
npm run start    # or your preferred restart method

For development/RC versions:

cd /path/to/pulse
git checkout develop
git pull origin develop
npm install
npm run build:css
npm run start    # or your preferred restart method

Note:

The development setup only requires npm install in the root directory, not in a separate server directory.
The develop branch shows dynamic RC versions (e.g., "3.24.0-rc5") that auto-increment with each commit.
The main branch contains stable releases only.

📝 Contributing

Contributions are welcome! Please read our Contributing Guidelines.

Development Workflow

Branch Strategy:

main - Stable releases only (protected)
develop - Daily development work (default working branch)

Release Candidate (RC) Automation:

Every commit to develop automatically creates an RC release
RC versions increment automatically: v3.24.0-rc1, v3.24.0-rc2, etc.
Docker images are built for both amd64 and arm64 architectures
Local development shows dynamic RC versions that update with each commit

Making Contributions:

Fork the repository
Create a feature branch from develop
Make your changes
Test locally (version will show as RC automatically)
Submit a pull request to develop

🔒 Privacy

No Data Collection: Pulse does not collect or transmit any telemetry or user data externally.
Local Communication: Operates entirely between your environment and your Proxmox/PBS APIs.
Credential Handling: Credentials are used only for API authentication and are not logged or sent elsewhere.

🛡️ Security Best Practices

API Token Security

Use dedicated service accounts for API tokens instead of root accounts
Enable privilege separation for all tokens to limit access scope
Regularly rotate API credentials (quarterly or after personnel changes)
Audit token permissions periodically to ensure least-privilege access
Monitor API access logs for unusual activity patterns

Network Security

Configure firewall rules to restrict API access (ports 8006/8007) to necessary hosts only
Use SSL/TLS for all API connections (avoid self-signed certificates in production)
Consider VPN access for external monitoring setups
Implement network segmentation to isolate monitoring traffic from production networks
Enable fail2ban or similar tools on Proxmox hosts to prevent brute force attacks

Deployment Security

Run Pulse with non-root user when possible (LXC and manual installations)
Keep container/system updated with latest security patches
Use configuration management instead of hardcoded credentials
Secure webhook URLs and email credentials with proper access controls
Monitor Pulse logs for authentication failures or connection issues

Proxmox Configuration

Disable unused APIs and services on Proxmox hosts
Enable two-factor authentication for Proxmox web interface access
Use strong passwords for all Proxmox user accounts
Regularly update Proxmox VE and PBS to latest stable versions
Configure proper backup encryption for sensitive VM/CT data

📜 License

This project is licensed under the MIT License - see the LICENSE file.

™️ Trademark Notice

Proxmox® and Proxmox VE® are registered trademarks of Proxmox Server Solutions GmbH. This project is not affiliated with or endorsed by Proxmox Server Solutions GmbH.

❤️ Support

File issues on the GitHub repository.

If you find Pulse useful, consider supporting its development:

❓ Troubleshooting

🔧 Quick Fixes

Can't access Pulse after installation?

# Check if service is running
sudo systemctl status pulse-monitor.service

# Check what's listening on port 7655
sudo netstat -tlnp | grep 7655

# View recent logs
sudo journalctl -u pulse-monitor.service -f

Empty dashboard or "No data" errors?

Check API Token: Verify your PROXMOX_TOKEN_ID and PROXMOX_TOKEN_SECRET are correct
Test connectivity: Can you ping your Proxmox host from where Pulse is running?
Check permissions: Ensure token has PVEAuditor role on path / with Propagate enabled

"Empty Backups Tab" with PBS configured?

Ensure PBS Node Name is configured in the settings modal
Find hostname with: ssh root@your-pbs-ip hostname

Docker container won't start?

# Check container logs
docker logs pulse

# Restart container
docker compose down && docker compose up -d

Diagnostic Tool

Pulse includes a comprehensive built-in diagnostic tool to help troubleshoot configuration and connectivity issues:

Web Interface (Recommended):

The diagnostics icon appears automatically in the header when issues are detected
Click the icon or navigate to http://your-pulse-host:7655/diagnostics.html
The tool will automatically run diagnostics and provide:
- API Token Permission Testing - Tests actual API permissions for VMs, containers, nodes, and datastores
- Configuration Validation - Verifies all connection settings and required parameters
- Real-time Connectivity Tests - Tests live connections to Proxmox VE and PBS instances
- Data Flow Analysis - Shows discovered nodes, VMs, containers, and backup data
- Specific Actionable Recommendations - Detailed guidance for fixing any issues found

Key Features:

Tests use the same API endpoints as the main application for accuracy
Provides exact permission requirements (e.g., VM.Audit on / for Proxmox)
Shows counts of discovered resources (VMs, containers, nodes, backups)
Identifies common misconfigurations like missing PBS_NODE_NAME
Privacy Protected: Automatically sanitizes hostnames, IPs, and sensitive data before export
Export diagnostic reports safe for sharing in GitHub issues or support requests

Command Line:

# If using the source code:
./scripts/diagnostics.sh

# The script will generate a detailed report and save it to a timestamped file

Common Issues

Proxmox Log File Growth / log2ram Issues:

Update (v3.30.0+): Pulse now uses the bulk /cluster/resources endpoint, reducing API calls by up to 95% while maintaining 2-second polling

If you still experience log growth, you can configure Proxmox logging:

Option 1: Use tmpfs for pveproxy logs (Best for log2ram users)

# Add to /etc/fstab on your Proxmox host:
tmpfs /var/log/pveproxy/ tmpfs defaults,uid=33,gid=33,size=1024m 0 0

# Then mount it:
mount /var/log/pveproxy/
systemctl restart pveproxy

Option 2: Disable pveproxy access logging entirely

# On your Proxmox host, symlink to /dev/null:
systemctl stop pveproxy
rm -f /var/log/pveproxy/access.log
ln -s /dev/null /var/log/pveproxy/access.log
systemctl start pveproxy

Option 3: Aggressive logrotate configuration

# Edit /etc/logrotate.d/pve on your Proxmox host:
/var/log/pveproxy/access.log {
    hourly          # Rotate every hour
    rotate 4        # Keep only 4 files
    maxsize 10M     # Force rotate at 10MB
    compress
    delaycompress
    notifempty
    missingok
    create 640 www-data www-data
}

# Force immediate rotation:
logrotate -f /etc/logrotate.d/pve

Option 4: Exclude from log2ram

# Edit /etc/log2ram.conf and add to exclusion:
LOG2RAM_PATH_EXCLUDE="/var/log/pveproxy"

# Then restart log2ram:
systemctl restart log2ram

Note: The pveproxy log path is hard-coded in Proxmox and cannot be changed. Pulse's 2-second polling provides real-time responsiveness - adjusting Proxmox logging is preferable to reducing polling frequency.

Empty Backups Tab:
- PBS backups not showing: Usually caused by missing PBS Node Name in the settings configuration. SSH to your PBS server and run hostname to find the correct value.
- PVE backups not showing: Ensure your API token has PVEDatastoreAdmin role on /storage to view backup files. See the permissions section above.
Pulse Application Logs: Check container logs (docker logs pulse_monitor) or service logs (sudo journalctl -u pulse-monitor.service -f) for errors (401 Unauthorized, 403 Forbidden, connection refused, timeout).
Configuration Issues: Use the settings modal to verify all connection details. Test connections with the built-in connectivity tester before saving. Ensure no placeholder values remain.
Network Connectivity: Can the machine running Pulse reach the PVE/PBS hostnames/IPs and ports (usually 8006 for PVE, 8007 for PBS)? Check firewalls.
API Token Permissions: Ensure the correct roles (PVEAuditor for PVE, Audit for PBS) are assigned at the root path (/) with Propagate enabled in the respective UIs.

Notification Troubleshooting

Webhook notifications not working?

Test the webhook: Use the "Test Webhook" button in settings to verify connectivity
Check the URL format: Ensure you're using the full webhook URL including protocol (https://)
Firewall rules: Verify Pulse can reach Discord/Slack/Teams servers (outbound HTTPS)
Check logs: Look for webhook errors in application logs

Email notifications not sending?

Test configuration: Use the "Test Email" button to verify SMTP settings
Gmail issues:
- Must use App Password, not regular password
- Enable "Less secure app access" or use App Passwords with 2FA
Port issues: Try different ports (587 for TLS, 465 for SSL, 25 for unencrypted)
Firewall: Ensure outbound SMTP traffic is allowed
Authentication: Double-check username/password, some servers require full email address

Name		Name	Last commit message	Last commit date
Latest commit History 1,514 Commits
.github		.github
data		data
docs		docs
scripts		scripts
server		server
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

License

zenkiet/Pulse

Folders and files

Latest commit

History

Repository files navigation

Pulse for Proxmox VE

📸 Screenshots

🚀 Quick Start

📦 Easiest: Proxmox Community Scripts (Recommended)

🐳 Docker Compose (Pre-built Image)

🛠️ Manual LXC Installation

📋 Table of Contents

✅ Prerequisites

🚀 Deployment Options

Proxmox Community Scripts (Automated LXC)

Docker Compose (Recommended for Existing Hosts)

Manual LXC Installation

Development Setup (Docker Compose)

🛠️ Configuration

Web Interface Configuration (Recommended)

Environment Variables (Development/Advanced)

Proxmox VE (Primary Environment)

Alert System Configuration (Optional)

Custom Per-VM/LXC Alert Thresholds (Optional)

Webhook Notifications (Optional)

Email Notifications (Optional)

Multiple Proxmox Environments (Optional)

Advanced Configuration Options

Proxmox Backup Server (PBS) (Optional)

Creating a Proxmox API Token

Creating a Proxmox Backup Server API Token

Required Permissions

Running from Release Tarball

️ Running the Application (Node.js - Development)

✨ Features

Core Monitoring

Advanced Alert System

Notification Systems

Enhanced Update System

Update Channels

Backup Monitoring

Performance & UI

Management & Diagnostics

Deployment & Integration

🏗️ Architecture

Technology Stack

Project Structure

Key Design Principles

💻 System Requirements

🔄 Updating Pulse

Web-Based Updates (Non-Docker)

Community Scripts LXC Installation

Docker Compose Installation

Manual LXC Installation

Release Tarball Installation

Development/Source Installation

📝 Contributing

Development Workflow

🔒 Privacy

🛡️ Security Best Practices

API Token Security

Network Security

Deployment Security

Proxmox Configuration

📜 License

™️ Trademark Notice

❤️ Support

❓ Troubleshooting

🔧 Quick Fixes

Diagnostic Tool

Common Issues

Notification Troubleshooting

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Packages