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

• Quick Start (Docker Compose)
• Configuration
  • Environment Variables
  • Creating a Proxmox API Token
  • Creating a Proxmox Backup Server API Token
  • Required Permissions
• Deployment
  • Running with Docker Compose
  • Running with LXC Installation Script
  • Running with Node.js (Development)
• Features
• System Requirements
• Contributing
• Privacy
• License
• Trademark Notice
• Support
• Troubleshooting

This is the fastest way to get Pulse running.

1. Get Files: Clone the repository (git clone https://github.com/rcourtman/Pulse.git && cd Pulse) or download docker-compose.yml and .env.example manually.
2. Copy .env: cp .env.example .env
3. Edit .env: Fill in your primary Proxmox API details (PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET). See Creating a Proxmox API Token if you don't have one.
4. Run: docker compose up -d
5. Access: Open your browser to http://<your-host-ip>:7655.

Pulse is configured using environment variables, typically set in a .env file in the project root.

1. Copy Example File: If you haven't already, copy the example file:

   cp .env.example .env

2. Edit .env: Open .env in a text editor and update the values for your environment(s).

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.
• (Username/Password fallback exists but API Token is strongly recommended)

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

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).

To monitor a 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.

Note: Currently, only one PBS instance can be configured.

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

Using an API token is the recommended authentication method.

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

• Proxmox VE: The PVEAuditor role assigned at path / with Propagate enabled is recommended.
  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.

Choose one of the following methods to deploy Pulse.

Using Docker Compose is the recommended way for most users.

Prerequisites:

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

Steps:

1. Configure Environment: Ensure your .env file is created and configured as described in Configuration.
2. Run: In the project root directory, run:

   docker compose up -d

   This downloads the rcourtman/pulse:latest image and starts the container in the background.
3. Access: Open http://<your-host-ip>:7655 (or the host port mapped in docker-compose.yml).

Stopping:

docker compose down

Note: Restart the container (docker compose down && docker compose up -d) if you change .env after starting.

version: '3.8'

services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse_monitor
    restart: unless-stopped
    ports:
      - "7655:7655" # Map container port 7655 to host port 7655
    environment:
      # --- Required Proxmox Connection Details ---
      PROXMOX_HOST: "https://your-proxmox-ip-or-hostname:8006"
      PROXMOX_TOKEN_ID: "your-user@pam!your-token-name"
      PROXMOX_TOKEN_SECRET: "your-api-token-secret-uuid"

      # --- Optional Settings ---
      PROXMOX_ALLOW_SELF_SIGNED_CERTS: "false"
      # PBS_HOST: "https://your-pbs-ip:8007"
      # PBS_TOKEN_ID: "your-pbs-user@pbs!token"
      # PBS_TOKEN_SECRET: "your-pbs-secret"
      # PBS_NODE_NAME: "your-pbs-hostname"

    # Optional: Mount a local directory for potential future config needs
    # volumes:
    #   - ./pulse_config:/config

networks:
  default:
    driver: bridge

An installation script is available for setting up Pulse inside an existing Debian/Ubuntu-based Proxmox VE LXC container.

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:

1. Access LXC Console: Log in to your LXC container (usually as root).
2. 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

3. Follow Prompts: The script guides you through:
   • Installing dependencies (git, curl, nodejs, npm, sudo).
   • Entering your Proxmox Host URL, API Token ID, Secret, and self-signed cert preference.
   • (Optional) Entering PBS connection details if desired.
   • Setting up Pulse as a systemd service (pulse-monitor.service).
   • Optionally enabling automatic updates via cron.
4. Access Pulse: The script will display the URL (e.g., http://<LXC-IP-ADDRESS>:7655).

./install-pulse.sh

./install-pulse.sh --update

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.

• Lightweight monitoring for Proxmox VE nodes, VMs, and Containers.
• Real-time status updates via WebSockets.
• Simple, responsive web interface.
• Efficient polling: Stops API polling when no clients are connected.
• Docker support.
• Multi-environment PVE monitoring support.
• Proxmox Backup Server (PBS) monitoring support.
• LXC installation script.

• 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.

Contributions are welcome! Please read our Contributing Guidelines.

• 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.

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

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.

File issues on the GitHub repository.

If you find Pulse useful, consider supporting its development:

Common connection issues:

• 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).
• .env Configuration: Verify PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET, and PROXMOX_ALLOW_SELF_SIGNED_CERTS. For PBS, also check PBS_HOST, PBS_TOKEN_ID, PBS_TOKEN_SECRET, PBS_ALLOW_SELF_SIGNED_CERTS, and especially PBS_NODE_NAME. 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.