Pankha (पंखा) Fan Management System

---

Open Source Fan Control System

Pankha is an open-source Distributed fan control system with a Centralized Management Web Interface for monitoring and controlling hardware cooling across multiple machines. Production-ready with real-time hardware monitoring, WebSocket communication, and PostgreSQL database.

Features:

• Real-time Temperature Monitoring - Manage Sensors across multiple hardware types and and Operating System.
• PWM Fan Control - Direct hardware control with RPM feedback, Profiles, and Safety features, historical data visualization.
• Multi-System Support - Monitor and control multiple machines from one dashboard
• Web Dashboard - Modern Web UI Interface with real-time updates
• WebSocket Communication - Bidirectional real-time data transmission to centralize control
• Easy Deployment - Docker based server deployment, with one command setup for agents
• PostgreSQL Database - Production ready data storage.
• Open Source - Pankha is an open source project, Contribute to the project.

Showcase:

Centralized Dashboard:

Agent widget:

Temperature Sensors:

Fan Control:

Profiles:

Fully Customizable:

Why Pankha?

• ✅ Reduced Fan Wear - Fewer speed changes extend fan lifespan
• ✅ Quieter Operation - Smooth transitions eliminate abrupt noise changes
• ✅ Stable UI - No flickering fan speed indicators
• ✅ Better UX - Professional, predictable behavior
• ✅ Energy Efficiency - Smoother transitions reduce power spikes
• ✅ User Control - Tune behavior per system/use case
• ✅ Safety - Emergency override ensures critical temps handled immediately
• ✅ Multi-System Support - Monitor and control multiple machines from one dashboard
• ✅ Open Source - Easy to deploy, manage, and scale
• ✅ Real-time Updates - Instant feedback on temperature and fan speed changes
• ✅ Real-time Profiles - Customizable fan profiles for different workloads
• ✅ Real-time Data - Historical data visualization for better planning

Instructions:

Prerequisites

• Docker and Docker Compose for server deployment
• System with fan control capabilities (for agents)

Server Installation Guide:

Docker Compose Deployment:

1. Download the Docker Compose file:

   wget -O compose.yml https://github.com/Anexgohan/pankha/releases/latest/download/compose.yml

   or,

   curl -fsSLo compose.yml https://github.com/Anexgohan/pankha/releases/latest/download/compose.yml

2. Download the .env file

   wget -O .env https://github.com/Anexgohan/pankha/releases/latest/download/example.env

   or,

   curl -fsSLo .env https://github.com/Anexgohan/pankha/releases/latest/download/example.env

3. Start Docker Compose

   docker pull && docker compose up -d

Clone and Deploy (Alternate Method):

1. Clone the repository
   this creates a pankha directory in your current path

   git clone https://github.com/Anexgohan/pankha.git
   cd pankha

   or, clone to current directory without creating pankha/ folder

   git clone https://github.com/Anexgohan/pankha.git .

   NOTE:
   Edit .env and compose with your configuration, if needed.

2. Start the system

   docker compose pull && docker compose up -d

That's it! The backend is now running with:

• Access the Web Dashboard at http://localhost:3000 or http://[serverIP]:[PANKHA_PORT]
• To stop the system, run:

  docker compose down

Agent Installation Guide:

Windows Agent

Requirements: Windows 10/11, .NET 8 Runtime.

1. Download Installer:
   • Download pankha-agent-windows_x64.msi from Latest Releases.
2. Install:
   • Run the installer. It will install the Background Service and Tray Application.
3. Configure:
   • Launch "Pankha Fan Control" from the Start Menu.
   • Right-click the Tray Icon -> Settings to configure the backend URL.

Linux Agent (Rust)

Performance: Single binary, <10MB RAM, <1% CPU. Zero dependencies.

For x86_64 systems:

• With wget

  wget -O pankha-agent https://github.com/Anexgohan/pankha/releases/latest/download/pankha-agent-linux_x86_64
  chmod +x pankha-agent

• Or, With curl

  curl -fsSLo pankha-agent https://github.com/Anexgohan/pankha/releases/latest/download/pankha-agent-linux_x86_64
  chmod +x pankha-agent

Configure and manage the agent using the following commands:

1. Configure agent (Required for first time)

   ./pankha-agent --setup

2. Manage Service (Auto-start on boot)

   ./pankha-agent --install-service
   ./pankha-agent --uninstall-service

3. Check status & Health

   ./pankha-agent --status
   ./pankha-agent --check

4. Start/Stop daemon

   ./pankha-agent --start
   ./pankha-agent --stop

5. Help, or list all commands and options

   ./pankha-agent --help

For ARM64 systems (Raspberry Pi 5, etc):

• With wget

  wget -O pankha-agent https://github.com/Anexgohan/pankha/releases/latest/download/pankha-agent-linux_arm64
  chmod +x pankha-agent

• Or, With curl

  curl -fsSLo pankha-agent https://github.com/Anexgohan/pankha/releases/latest/download/pankha-agent-linux_arm64
  chmod +x pankha-agent

Configure and manage the agent using the same commands as above:

1. Interactive Setup: ./pankha-agent --setup
2. Manage Service: ./pankha-agent --install-service
3. Check Status: ./pankha-agent --status
4. View Logs: ./pankha-agent --log-show

The agent will connect to the backend and start sending hardware data. You can now manage the agent from the dashboard.

Documentation:

Quick Links

Installation Configuration

Linux Windows Settings

API Reference Fan Profiles

Troubleshooting Build from Source

Architecture:

Browser ←HTTP/WS→ Backend (Docker) ←WebSocket→ Agents ←Direct→ Hardware

• Backend: Node.js + Express + WebSocket + PostgreSQL (Dockerized)
• Frontend: React + TypeScript + Vite (served by nginx)
• Agents:
  • Linux: Rust single binary processes (sysfs)
  • Windows: .NET 8 Service (LibreHardwareMonitor)

Extra:

• Verify installation

  # Check services are running
  docker compose ps
  
  # Check backend health
  curl http://localhost:${PANKHA_PORT:-3000}/health
  
  # Access dashboard
  open http://localhost:3000

• Cleanup

  # To stop services
  docker compose down
  
  # To remove volumes (data loss)
  docker compose down -v

Option 2: Manual Build

Build from source:

Clone repository

git clone https://github.com/Anexgohan/pankha.git
cd pankha

Build Docker image

docker compose pull
docker compose build --no-cache

Run with compose

docker compose up -d

Configuration

Backend Configuration

Environment variables in .env:

# Database Configuration
POSTGRES_DB=db_pankha
POSTGRES_USER=pankha_user
POSTGRES_PASSWORD=your_secure_password
DATABASE_URL=postgresql://pankha_user:your_secure_password@pankha-postgres:5432/db_pankha

# Server Configuration
PANKHA_PORT=3000
NODE_ENV=production

Agent Configuration

Generate Agent config with

./pankha-agent --setup

Agent configuration file: config.json (running directory)

{
  "agent": {
    "id": "OS-mysystem-randomhash",
    "name": "hostname-or-custom-name",
    "update_interval": 3.0,
    "log_level": "INFO"
  },
  "backend": {
    "server_url": "ws://192.168.1.100:3000/websocket",
    "reconnect_interval": 30.0,
    "max_reconnect_attempts": -1,
    "connection_timeout": 10.0
  },
  "hardware": {
    "enable_fan_control": true,
    "enable_sensor_monitoring": true,
    "fan_safety_minimum": 30,
    "filter_duplicate_sensors": false,
    "duplicate_sensor_tolerance": 2.0,
    "fan_step_percent": 5,
    "hysteresis_temp": 3.0,
    "emergency_temp": 85.0
  },
  "logging": {
    "enable_file_logging": true,
    "log_file": "/var/log/pankha-agent/agent.log",
    "max_log_size_mb": 10,
    "log_retention_days": 7
  }
}

Troubleshooting

Backend Issues

Issue: Cannot connect to database

# Check PostgreSQL is running
docker compose ps

# Check logs
docker compose logs postgres

# Verify DATABASE_URL in .env
cat .env | grep DATABASE_URL

Issue: Port already in use

# Change port in compose
    ports:
      - "${PANKHA_PORT:-7000}:3000"
# or in .env file
    PANKHA_PORT=7000

# Restart
docker compose down
docker compose up -d

Agent Issues

Issue: Agent cannot connect to backend

# Test backend connectivity
curl http://your-backend:3000/health

# Check agent logs
tail -f /var/log/pankha-agent/agent.log

# Verify config
./pankha-agent --config

Issue: No sensors detected

# Verify lm-sensors
sensors

# Check permissions
ls -la /sys/class/hwmon/

# Run as root
sudo ./pankha-agent --start

Issue: Fan control not working

# Check PWM support
cat /sys/class/hwmon/hwmon*/pwm*

# Test manual control
echo 128 | sudo tee /sys/class/hwmon/hwmon0/pwm1

Contributing

We welcome contributions! Please see our contributing guidelines:

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

System Requirements

Backend (Server)

• CPU: x86_64 or ARM64
• RAM: 256MB minimum
• Disk: 1GB (for database)
• OS: Linux, Windows (Docker supported), Mac support in future

Agent (Client)

• CPU: <1% usage
• RAM: <50MB
• OS: Linux with hwmon support, Windows
• Requirements:
  • PWM-controllable fans

Supported Hardware

Fan Control

• ✅ PWM fans (4-pin, Speed control)
• ✅ DC fans (voltage control, On/Off)
• Hardware monitoring chips (IPMI, Supermicro, Dell iDRAC), coming soon

License

This project is licensed under the AGPL-3.0 License , see the LICENSE file for details.

Links

• GitHub: https://github.com/Anexgohan/pankha
• Docker Hub: https://hub.docker.com/r/anexgohan/pankha
• Issues: https://github.com/Anexgohan/pankha/issues
• Discussions: https://github.com/Anexgohan/pankha/discussions

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Discore coming Soon

Acknowledgments

• Built with Node.js, React, and PostgreSQL
• Inspired by the need for centralized hardware monitoring
• Thanks to the open source community

---

Made with ❤️ for the self-hosting community