Pulse for Proxmox VE

A lightweight, responsive monitoring application for Proxmox VE that displays real-time metrics for CPU, memory, network, and disk usage across multiple nodes.

📑 Table of Contents

• Quick Start with Docker
• Configuration
• Common Docker Commands
• Features
• Troubleshooting
• Advanced Configuration
• Development
  • Development Architecture
  • Developer Documentation
• System Requirements
• Version Information
• Contributing
• Support
• License

🚀 Quick Start with Docker

Option 1: Simple Docker Run

# 1. Download the example environment file
curl -O https://raw.githubusercontent.com/rcourtman/pulse/main/.env.example
mv .env.example .env

# 2. Edit the .env file with your Proxmox details
nano .env  # or use your preferred editor

# 3. Run with Docker
docker run -d \
  -p 7654:7654 \
  --env-file .env \
  --name pulse-app \
  --restart unless-stopped \
  rcourtman/pulse:latest

# 4. Access the application
# Open http://localhost:7654 in your browser
# If running on a remote server, use http://server-ip:7654

Option 2: Docker Compose

# 1. Download the example files
curl -O https://raw.githubusercontent.com/rcourtman/pulse/main/.env.example
curl -O https://raw.githubusercontent.com/rcourtman/pulse/main/docker-compose.yml
mv .env.example .env

# 2. Edit the .env file with your Proxmox details
nano .env  # or use your preferred editor

# 3. Run with Docker Compose
docker compose up -d  # Note: newer Docker versions use 'docker compose' (no hyphen)

# 4. Access the application
# Open http://localhost:7654 in your browser
# If running on a remote server, use http://server-ip:7654

🔧 Configuration

Required Environment Variables

Edit your .env file with at least these settings:

# Required: Proxmox Node Configuration
PROXMOX_NODE_1_NAME=Proxmox Node 1
PROXMOX_NODE_1_HOST=https://proxmox.local:8006
PROXMOX_NODE_1_TOKEN_ID=root@pam!pulse
PROXMOX_NODE_1_TOKEN_SECRET=your-token-secret

Proxmox API Token Requirements

Your Proxmox API token needs these permissions:

• PVEAuditor role or custom role with:
  • Datastore.Audit
  • VM.Audit
  • Sys.Audit
  • Pool.Audit

Creating a Proxmox API Token

Option 1: Quick Command (Convenient but less secure)

You can run this command either by SSH'ing into your Proxmox server or by using the Shell console in the Proxmox web UI (Datacenter → Shell):

# This creates a token named 'pulse' to match the example in the .env file
pveum user token add root@pam pulse --privsep=0 && \
pveum acl modify / -user root@pam -role PVEAuditor && \
pveum user token list root@pam

⚠️ Why this is less secure:

• Uses the root account (best practice is to use a dedicated user)
• Disables privilege separation with --privsep=0 (privilege separation restricts token permissions)
• Grants access to all resources (/)
• Outputs the token secret to the terminal (could be logged)

Option 2: Step-by-Step Guide (More secure)

1. Log in to the Proxmox web interface

2. Create a dedicated user (optional but recommended)

   • Go to Datacenter → Permissions → Users
   • Click "Add"
   • Enter a username (e.g., "pulse-monitor")
   • Set a password and enable the user

3. Create an API token

   • Go to Datacenter → Permissions → API Tokens
   • Click "Add"
   • Select your user (e.g., "pulse-monitor@pam" or "root@pam")
   • Enter a token ID (e.g., "pulse")
   • Leave "Privilege Separation" checked for better security (this restricts the token to only use permissions explicitly granted to it)
   • Click "Add"
   • Important: Save the displayed token value securely - it will only be shown once!

4. Assign permissions

   • Go to Datacenter → Permissions → Add
   • Path: /
   • User: Your user (e.g., "pulse-monitor@pam")
   • Role: PVEAuditor
   • Click "Add"

5. Update your .env file

   # If using root user (matching the quick command example)
   PROXMOX_NODE_1_TOKEN_ID=root@pam!pulse
   PROXMOX_NODE_1_TOKEN_SECRET=your-saved-token-value
   
   # OR if using a dedicated user (recommended for better security)
   PROXMOX_NODE_1_TOKEN_ID=pulse-monitor@pam!pulse
   PROXMOX_NODE_1_TOKEN_SECRET=your-saved-token-value
   

🛠️ Common Docker Commands

# View logs
docker logs pulse-app

# Restart the application
docker restart pulse-app

# Update to latest version
docker pull rcourtman/pulse:latest
docker rm -f pulse-app
docker run -d -p 7654:7654 --env-file .env --name pulse-app --restart unless-stopped rcourtman/pulse:latest

# For Docker Compose users
docker compose pull  # Pull latest image
docker compose up -d  # Restart with new image

✨ Features

• Real-time monitoring of Proxmox nodes, VMs, and containers
• Dashboard with summary cards for nodes, guests, and resources
• Responsive design that works on desktop and mobile
• WebSocket connection for live updates

❓ Frequently Asked Questions

How does Pulse compare to Grafana + InfluxDB monitoring?

Pulse and Grafana serve different monitoring needs. Pulse focuses on real-time monitoring with WebSocket-based instant updates, ideal for active system monitoring and dashboards. It's lightweight (single Docker container) and simple to set up. Grafana+InfluxDB is better suited for historical data analysis, complex visualizations, and monitoring multiple systems. If you need detailed historical metrics or custom dashboards, use Grafana. If you want instant resource updates and a simple setup, use Pulse.

How is it different from the built-in Proxmox summary?

While Proxmox's built-in summary is great for management, Pulse offers:

• Real-time WebSocket updates
• All nodes visible on one screen
• Monitoring without logging into Proxmox
• Ability to share monitoring access without admin privileges
• Lightweight resource usage
• Perfect for dedicated monitoring displays

Will Pulse support Proxmox Backup Server (PBS)?

PBS integration is planned. The PBS API provides the metrics needed for backup job status, datastore usage tracking, and verification monitoring. A roadmap of planned features will be published soon.

What about hardware monitoring (temperatures, additional disks)?

Hardware metric expansion is in development, including temperature sensors and additional disk metrics. The focus is on keeping the interface clean and responsive while adding these features.

How resource-intensive is Pulse?

Pulse is designed to be lightweight, requiring minimal resources (256MB RAM, 1 CPU core). It runs as a single Docker container and doesn't store historical data, keeping the resource footprint small.

What's the long-term plan for this project?

Pulse is actively maintained and used daily. I'm committed to keeping it relevant and useful, with a focus on stability and thoughtful feature additions. A public roadmap will be published soon to share planned features and improvements.

Does Pulse collect any telemetry or user data?

No. Pulse only communicates directly with your Proxmox servers using the API token you provide. No data is sent outside your network, and the entire codebase is open source for verification.

❓ Troubleshooting

1. Connection Issues: Verify your Proxmox node details in .env
2. SSL Problems: Add these to your .env file:

   IGNORE_SSL_ERRORS=true
   NODE_TLS_REJECT_UNAUTHORIZED=0
   

3. Port Conflicts: Change the port mapping in your docker run command if port 7654 is already in use
4. API Token Issues: Ensure your token has the correct permissions (PVEAuditor role)
5. Frontend Cannot Connect to Backend: Ensure you're using IPv4 addresses instead of IPv6:

   # Add this to your .env file
   VITE_API_URL=http://127.0.0.1:7654
   

   This is particularly important in Docker environments or when the frontend and backend are running on different hosts.

📋 Advanced Configuration

For multiple Proxmox nodes or advanced settings, add these to your .env:

# Additional nodes
PROXMOX_NODE_2_NAME=Proxmox Node 2
PROXMOX_NODE_2_HOST=https://proxmox2.local:8006
PROXMOX_NODE_2_TOKEN_ID=root@pam!pulse
PROXMOX_NODE_2_TOKEN_SECRET=your-token-secret

# App Configuration
PORT=7654
LOG_LEVEL=info
METRICS_HISTORY_MINUTES=60
NODE_POLLING_INTERVAL_MS=1000
EVENT_POLLING_INTERVAL_MS=1000

🧑‍💻 Development

If you're developing Pulse, you can use the development server:

# Clone the repository
git clone https://github.com/rcourtman/pulse.git
cd pulse

# Install dependencies
npm install
cd frontend && npm install && cd ..

# Start the development server
./start-dev.sh

⚠️ Warning: The start-dev.sh script performs the following actions:

• Stops any running Docker containers with "pulse" in their name
• Kills any running Node.js processes serving the application
• Frees ports 7654 and 3000 by terminating processes using them
• Sets NODE_ENV to development
• Starts both backend and frontend development servers

Development Architecture

Pulse uses a split architecture for development:

• Backend server (port 7654): Node.js Express server that communicates with Proxmox
• Frontend server (port 3000): Vite development server for the React frontend

This separation provides several benefits:

• Hot Module Replacement (HMR): Changes to frontend code are instantly reflected without a full page reload
• Independent development: Backend and frontend can be developed and tested separately
• API isolation: Clear separation between data services and UI components

When you run start-dev.sh, both servers start automatically:

1. The backend server runs on port 7654 and handles all Proxmox API communication
2. The frontend development server runs on port 3000 with hot reloading enabled
3. API requests from the frontend are proxied to the backend

In production, these are combined into a single service running on port 7654.

Developer Documentation

For more detailed information about the codebase structure, key components, and design decisions, please refer to the Developer Documentation.

The development server will be accessible at:

• http://localhost:3000 - from the local machine
• http://your-ip-address:3000 - from other devices on your network

💻 System Requirements

• Docker: Version 20.10.0 or higher
• Memory: Minimum 256MB RAM (512MB recommended)
• CPU: Any modern CPU (1+ cores)
• Disk Space: Approximately 100MB for the Docker image
• Network: Connectivity to your Proxmox server(s)
• Browser: Any modern browser (Chrome, Firefox, Safari, Edge)

🔄 Version Information

Current version: 1.2.1

To check for updates:

# Check for newer image versions
docker pull rcourtman/pulse:latest

# View current running version
docker exec pulse-app cat /app/package.json | grep version

👥 Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add some amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Please make sure to update tests as appropriate and follow the code style of the project.

For more detailed information about contributing, please see our Contributing Guidelines.

Reporting Issues

When reporting issues, please use the appropriate issue template:

• Bug Report - for reporting bugs or unexpected behavior
• Feature Request - for suggesting new features or improvements

📄 License

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

Trademark Notice

Proxmox® and Proxmox VE® are registered trademarks of Proxmox Server Solutions GmbH. Pulse for Proxmox VE is an independent project and is not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.

❤️ Support

If you find Pulse helpful, please consider supporting its development through Ko-fi. Your support helps keep this project maintained and free for everyone!