PeaNUT: 12 Powerful Features Transforming UPS Monitoring

Tired of clunky command-line tools for UPS monitoring? Meet PeaNUT—the sleek, Docker-native dashboard that turns Network UPS Tools into a visual powerhouse. This tiny but mighty application delivers real-time insights, RESTful API access, and Prometheus metrics in one elegant package.

If you've ever struggled with NUT's cryptic commands or wished for a modern web interface to track your uninterruptible power supplies, you're not alone. Homelab enthusiasts and sysadmins worldwide face this daily friction. PeaNUT eliminates this pain point entirely. In this deep dive, you'll discover how to deploy PeaNUT in under 60 seconds, leverage its comprehensive API, integrate with your existing monitoring stack, and transform raw UPS data into actionable intelligence. From Docker commands to advanced Prometheus queries, we cover everything you need to master this revolutionary tool.

What Is PeaNUT and Why It's Revolutionizing UPS Management

PeaNUT is a lightweight, open-source dashboard specifically designed for Network UPS Tools (NUT), the industry-standard software for monitoring uninterruptible power supplies. Created by Brandawg93, this modern web application bridges the gap between NUT's powerful but archaic command-line interface and today's demand for intuitive, accessible monitoring solutions.

Unlike traditional NUT monitoring approaches that require manual parsing of upsc commands or configuring complex CGI scripts, PeaNUT provides a real-time, responsive web interface that displays critical UPS metrics at a glance. The project has gained significant traction in the homelab and self-hosted communities due to its Docker-first architecture and extensive integration capabilities.

The name itself is a clever play on words—combining "NUT" with a diminutive "Pea" to emphasize its lightweight nature. But don't let the "tiny" description fool you. PeaNUT packs enterprise-grade features into a containerized package that runs seamlessly on everything from Raspberry Pi 4 devices to high-performance servers. Its trending popularity stems from the perfect storm of increasing power reliability concerns, the homelab boom, and the universal shift toward containerized infrastructure monitoring.

Key Features That Make PeaNUT Essential

Real-Time UPS Statistics: PeaNUT provides live monitoring of voltage, load percentage, battery charge, runtime estimates, and input/output frequencies. The dashboard updates automatically, eliminating the need for manual refreshes. This is crucial for detecting power anomalies before they escalate into failures.

Multi-Device Aggregation: Manage multiple UPS devices across your network from a single pane of glass. Whether you're running separate UPS units for servers, networking gear, and storage arrays, PeaNUT consolidates everything into one unified interface. Each device gets its own detailed view with customizable widget layouts.

Command Execution Engine: Execute NUT commands directly through the web UI. Initiate battery tests, shutdown sequences, or calibration routines without touching the terminal. This feature includes safety confirmations and detailed logging of all executed actions.

Dual Configuration Paradigm: Choose between intuitive UI-based configuration or manual YAML file editing. The /config/settings.yml file supports version control and infrastructure-as-code workflows, while the web interface enables rapid prototyping and on-the-fly adjustments.

Comprehensive API Surface: Exposes 20+ REST endpoints for device information, variables, commands, and descriptions. The API supports Basic Authentication and returns JSON payloads perfect for automation scripts and third-party integrations.

Prometheus Native Metrics: The /api/v1/metrics endpoint exposes UPS data in Prometheus format out of the box. This enables sophisticated alerting rules, Grafana dashboards, and correlation with other infrastructure metrics. No external exporters required.

InfluxDB v2 Integration: Direct integration with InfluxDB v2 allows long-term storage of UPS metrics for trend analysis, capacity planning, and historical reporting. Pair with Grafana for stunning visualizations of power consumption patterns over time.

Homepage Dashboard Widgets: Customizable widgets for the popular Homepage dashboard enable embedding UPS status directly into your primary homelab dashboard. Display battery percentage, load, and status without switching applications.

Platform Optimization: Native support for both linux/amd64 and linux/arm64 architectures ensures optimal performance across diverse hardware. The ARM64 support makes it perfect for Raspberry Pi 4+ deployments in edge locations.

SSL/TLS Termination: Built-in support for SSL certificates enables secure access without requiring a reverse proxy. Mount your certificate and key files via environment variables for encrypted communications.

WebSocket Real-Time Updates: The /api/ws endpoint provides WebSocket access for applications requiring sub-second latency updates. This is ideal for building custom monitoring displays or integrating with real-time alerting systems.

Debug and Logging: Enable comprehensive debug logging with the DEBUG environment variable to troubleshoot NUT communication issues, API calls, or configuration problems.

Real-World Use Cases Where PeaNUT Dominates

Homelab Power Intelligence: Imagine running a Proxmox cluster with separate UPS units for compute nodes, TrueNAS storage, and network switches. PeaNUT consolidates all three devices into one dashboard, showing total power draw, remaining runtime, and individual battery health. When utility power fails, you get instant visual feedback on which devices are critical and how long you have before graceful shutdowns must begin.

Small Business Server Room Monitoring: For MSPs managing multiple client sites, PeaNUT's API enables centralized monitoring across all locations. A single Prometheus instance can scrape metrics from PeaNUT dashboards running at each client site. Set up alerts for battery replacement warnings, overload conditions, or frequent power events that might indicate electrical issues requiring professional attention.

Remote Edge Deployment Management: Deploy PeaNUT on Raspberry Pi 4 devices at remote edge locations. The lightweight container (under 100MB) runs efficiently on limited hardware while providing full monitoring capabilities. Technicians can check UPS status via the web UI before traveling to site, ensuring they bring the right replacement batteries or parts.

Data Center Rack-Level Monitoring: In colocation facilities where each rack has dedicated UPS units, PeaNUT provides tenants with visibility into their power infrastructure without granting shell access. The multi-tenancy support through authentication and base path configuration allows hosting providers to offer PeaNUT as a value-added service.

Integration with Existing Monitoring Stacks: For organizations already using Grafana, Prometheus, and Alertmanager, PeaNUT slots in seamlessly. Create unified dashboards showing server metrics, network performance, and UPS status side-by-side. Correlate power events with application performance issues to identify infrastructure dependencies.

Automated Disaster Recovery Testing: Schedule monthly battery tests across all UPS devices using PeaNUT's API. Write scripts that trigger tests, monitor voltage stability under load, and generate compliance reports. The API's command execution capabilities enable full automation of maintenance procedures.

Step-by-Step Installation and Setup Guide

Prerequisites

Before installing PeaNUT, ensure you have:

• A running NUT server with at least one configured UPS device
• Docker and Docker Compose installed (or Node.js 18+ for source compilation)
• Network connectivity between PeaNUT and your NUT server
• 512MB RAM and 100MB disk space available

Method 1: Quick Docker Deployment

The fastest way to get PeaNUT running is using the official Docker image:

docker run -d \
  --name peanut \
  -v ${PWD}/config:/config \
  -p 8080:8080 \
  --restart unless-stopped \
  --env WEB_PORT=8080 \
  brandawg93/peanut:latest

Command Breakdown:

• -d: Runs container in detached mode
• --name peanut: Assigns a memorable container name
• -v ${PWD}/config:/config: Persists configuration data to host directory
• -p 8080:8080: Maps container port to host
• --restart unless-stopped: Ensures auto-restart after reboots
• --env WEB_PORT=8080: Sets web server port (must match container port)

Method 2: Docker Compose for Production

Create a docker-compose.yml file for easier management:

version: '3.8'
services:
  peanut:
    image: brandawg93/peanut:latest
    container_name: PeaNUT
    restart: unless-stopped
    volumes:
      - ./config:/config
    ports:
      - "8080:8080"
    environment:
      - WEB_PORT=8080
      - WEB_HOST=0.0.0.0
      - DEBUG=false
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

Production Enhancements:

• Fixed port binding with quotes for consistency
• Explicit host binding for security
• Custom network isolation
• Environment variables grouped for clarity

Deploy with:

docker-compose up -d

Method 3: Compile from Source

For development or customization:

# Clone the repository
git clone https://github.com/Brandawg93/PeaNUT.git
cd PeaNUT

# Install pnpm package manager if needed
npm i -g pnpm

# Install dependencies
pnpm i

# Build for local development
pnpm run build:local

# Start the application
pnpm run start:local

Source Build Notes:

• Requires Node.js 18+ and pnpm
• build:local compiles TypeScript and bundles assets
• start:local launches both frontend and backend servers
• Development mode includes hot-reloading for UI changes

Initial Configuration

After installation, access PeaNUT at http://your-server:8080. The setup wizard will guide you through:

1. NUT Server Connection: Enter hostname/IP and port (default 3493)
2. Device Discovery: PeaNUT automatically detects available UPS devices
3. Dashboard Customization: Arrange widgets for your specific devices
4. Authentication Setup: Optional but recommended for production

Real Code Examples from the Repository

Docker Run Command with Authentication

The README provides a basic Docker command. Here's an enhanced version with security:

docker run -d \
  --name peanut-secure \
  -v /opt/peanut/config:/config \
  -p 8443:8443 \
  --restart unless-stopped \
  --env WEB_PORT=8443 \
  --env WEB_USERNAME=admin \
  --env WEB_PASSWORD='SecureP@ssw0rd!' \
  --env SSL_CERT_PATH=/config/cert.pem \
  --env SSL_KEY_PATH=/config/key.pem \
  brandawg93/peanut:latest

Explanation: This command adds authentication and SSL termination. The WEB_USERNAME and WEB_PASSWORD variables enable Basic Auth for both UI and API access. SSL certificate paths point to mounted files in the config directory, enabling HTTPS without a reverse proxy.

Complete Docker Compose with All Environment Variables

Based on the README's environment table, here's a production-ready compose file:

services:
  peanut:
    image: brandawg93/peanut:latest
    container_name: PeaNUT-Production
    restart: unless-stopped
    volumes:
      - ./peanut-data:/config
      - ./ssl:/ssl:ro
    ports:
      - "8080:8080"
    environment:
      WEB_HOST: 0.0.0.0
      WEB_PORT: 8080
      WEB_USERNAME: ${PEANUT_USER}
      WEB_PASSWORD: ${PEANUT_PASS}
      BASE_PATH: /ups
      SSL_CERT_PATH: /ssl/cert.pem
      SSL_KEY_PATH: /ssl/key.pem
      DISABLE_CONFIG_FILE: "false"
      DEBUG: "false"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/ping"]
      interval: 30s
      timeout: 10s
      retries: 3

Key Additions:

• Environment variables use Docker Compose's mapping syntax for readability
• SSL certificates mounted read-only for security
• BASE_PATH set for reverse proxy subfolder deployment
• Healthcheck ensures container reliability
• Secrets managed via environment variables (use Docker secrets in Swarm mode)

API Authentication Example

The README specifies API authentication requirements. Here's a practical implementation:

// Node.js example for authenticated API call to PeaNUT
const axios = require('axios');

// Your PeaNUT credentials
const username = 'admin';
const password = 'SecureP@ssw0rd!';

// Create Basic Auth header
const authHeader = 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64');

async function getUPSStatus() {
  try {
    const response = await axios.get('http://peanut-server:8080/api/v1/devices', {
      headers: {
        'Authorization': authHeader
      }
    });
    
    console.log('UPS Devices:', response.data);
    return response.data;
  } catch (error) {
    console.error('API Error:', error.response?.status, error.response?.data);
  }
}

// Execute command on UPS
async function initiateBatteryTest(upsName) {
  const response = await axios.post(
    `http://peanut-server:8080/api/v1/devices/${upsName}/command/test.battery.start`,
    {},
    { headers: { 'Authorization': authHeader } }
  );
  
  console.log('Test initiated:', response.data);
}

Implementation Details: The code demonstrates proper Basic Auth encoding, error handling for API failures, and command execution. The Buffer.from() method creates the required Base64-encoded credentials string that PeaNUT's API expects.

Prometheus Scraping Configuration

Leverage the built-in metrics endpoint for monitoring:

# prometheus.yml scrape configuration
scrape_configs:
  - job_name: 'peanut'
    static_configs:
      - targets: ['peanut-server:8080']
    metrics_path: '/api/v1/metrics'
    scrape_interval: 30s
    basic_auth:
      username: 'admin'
      password: 'SecureP@ssw0rd!'

Prometheus Integration: This configuration scrapes UPS metrics every 30 seconds. The basic_auth section is crucial—without it, Prometheus receives 401 Unauthorized errors. Metrics include battery charge percentage, load watts, input voltage, and UPS status codes.

Advanced Usage and Best Practices

Reverse Proxy Optimization: When running behind Nginx, use these performance-tuned settings:

location /ups/ {
    proxy_pass http://peanut:8080/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_cache_bypass $http_upgrade;
    
    # WebSocket support for real-time updates
    proxy_read_timeout 86400;
}

Security Hardening: Always enable authentication in production. Use Docker secrets for credentials, mount SSL certificates as read-only, and restrict container capabilities with --cap-drop ALL --cap-add CHOWN. Run as non-root user by specifying user: "1000:1000" in Docker Compose.

Performance Tuning: For large deployments monitoring 10+ UPS devices, increase Node.js memory limits: environment: - NODE_OPTIONS=--max-old-space-size=512. Enable Redis caching by mounting a custom config file to reduce NUT server load.

Monitoring the Monitor: Set up a secondary PeaNUT instance that monitors the primary's host UPS. This meta-monitoring ensures you receive alerts even if the main monitoring server experiences power issues.

Backup Strategy: Regularly backup the /config directory containing settings.yml. Use Docker volumes with snapshots or mount to a NAS with built-in versioning. The configuration file includes device aliases, dashboard layouts, and custom thresholds.

PeaNUT vs. Alternative Solutions

Why PeaNUT Wins: Traditional NUT CGI scripts require Apache/Nginx configuration and lack modern features. PeaNUT's containerized deployment eliminates dependency hell, while its API-first design enables true automation. The native Prometheus support alone saves hours of exporter configuration.

Frequently Asked Questions

What is Network UPS Tools (NUT) and do I need it? NUT is the backend that PeaNUT communicates with. You must have a NUT server running and connected to your UPS via USB, serial, or SNMP. PeaNUT is the dashboard; NUT is the driver.

Can I run PeaNUT on Raspberry Pi 3 or older? No. Version 5.17.0 dropped arm/v7 support. Use Raspberry Pi 4 or newer with 64-bit OS. The performance improvement on ARM64 is substantial—dashboard loads 3x faster.

How secure is PeaNUT for internet-facing deployments? Enable WEB_USERNAME and WEB_PASSWORD, use SSL certificates, and always place behind a reverse proxy with rate limiting. The API uses Basic Auth which is secure over HTTPS. Never expose directly to the internet without authentication.

My UPS isn't showing all variables. Why? Some UPS devices only expose basic data via NUT. Check upsc your-ups-name directly on the NUT server. If variables appear there but not in PeaNUT, enable debug mode: DEBUG=true and check logs. The issue is usually NUT permissions, not PeaNUT.

How do I integrate PeaNUT with Grafana? Use the Prometheus endpoint: GET /api/v1/metrics. Add PeaNUT as a Prometheus target, then import dashboard #1860 from Grafana.com ("UPS Monitoring"). Customize panels to show battery trends, load distribution, and power event annotations.

Can PeaNUT trigger shutdown commands on multiple servers? PeaNUT executes commands on the UPS itself (like shutdown.return). For server shutdown orchestration, pair PeaNUT with NUT's built-in shutdown features or use the API to trigger Ansible playbooks when battery levels drop below thresholds.

What's the difference between /api/v1/devices and /api/v1/metrics? /devices returns detailed JSON for each UPS—perfect for custom applications. /metrics returns Prometheus-formatted data optimized for time-series storage and alerting. Use /devices for building UIs, /metrics for monitoring pipelines.

Conclusion: Why PeaNUT Deserves a Place in Your Infrastructure

PeaNUT represents a paradigm shift in UPS monitoring—transforming a traditionally cumbersome process into a sleek, API-driven experience. Its Docker-native design eliminates installation friction, while the comprehensive feature set rivals enterprise solutions costing thousands. The active development by Brandawg93 ensures continuous improvement, with recent additions like InfluxDB v2 support and Homepage widgets showing the project's commitment to ecosystem integration.

For homelabbers, PeaNUT provides professional-grade visibility into power infrastructure. For MSPs, it enables scalable, multi-tenant monitoring. For enterprises, it delivers Prometheus-native metrics without proprietary lock-in. The combination of real-time dashboards, RESTful API, and modern deployment patterns makes it the definitive choice for NUT visualization.

Ready to revolutionize your UPS monitoring? Deploy PeaNUT today with a single Docker command. Star the repository on GitHub to support the project, and join the growing community of users who've made power monitoring effortless. Your future self—debugging a power event at 3 AM—will thank you.

Get started now: github.com/Brandawg93/PeaNUT