Pmdaemon

<div style="background-color: #1b252f; color: white; padding: 20px; text-align: center; border-radius: 8px;"> <img src="assets/logo.png" alt="PMDaemon Logo" style="height: 60px; display: block; margin: 0 auto 10px;"> <h1 style="margin: 0; color: white;">PMDaemon - Advanced Process Manager</h1> <p style="margin: 5px 0 0; color: #cccccc;">A high-performance, cross-platform process manager built in Rust</p> </div>

A high-performance, cross-platform process manager built in Rust, inspired by PM2 with innovative features that exceed the original. PMDaemon runs natively on Linux, Windows, and macOS and is designed for modern application deployment with advanced port management, real-time monitoring, and production-ready web APIs.

📑 Table of Contents

• Key Features
• Installation
• Quick Start
• Command Reference
• Configuration Options
• Web API
• Monitoring
• Comparison with PM2
• Library Usage
• Testing
• Roadmap
• Contributing
• License

The CLI

🚀 Key Features

Core Process Management

• Process Lifecycle - Start, stop, restart, reload, and enhanced delete operations
• Enhanced Delete Operations - Bulk deletion, status-based deletion, and safe process shutdown
• Clustering - Run multiple instances with automatic load balancing
• Auto-restart - Automatic restart on crashes with configurable limits
• Signal Handling - Graceful shutdown with SIGTERM/SIGINT and custom signals
• Configuration Persistence - Process configs saved and restored between sessions
• 🆕 Ecosystem Config Files - Manage multiple applications with JSON, YAML, or TOML config files

Advanced Monitoring & Health Checks

• Real-time Monitoring - CPU, memory, uptime tracking with system metrics
• Memory Limit Enforcement - Automatic restart when processes exceed memory limits
• HTTP Health Checks - Monitor process health via HTTP endpoints with configurable timeouts
• Script-based Health Checks - Custom health check scripts for complex validation
• Blocking Start Command - Wait for processes to be healthy before returning from start command
• Log Management - Separate stdout/stderr files with viewing and following

🌟 Innovative Port Management (Beyond PM2)

• Port Range Distribution - Automatically distribute consecutive ports to cluster instances
• Auto-assignment - Find first available port in specified range
• Conflict Detection - Prevent port conflicts at the process manager level
• Runtime Port Overrides - Change ports during restart without modifying saved config
• Port Visibility - Display assigned ports in process listings

Web API & Real-time Updates

• REST API - Full process management via HTTP with PM2-compatible responses
• WebSocket Support - Live process status and system metrics streaming
• Production Web Server - Built on Axum with CORS and security headers

🌍 Cross-Platform Support

• Native Windows Support - Full functionality on Windows with platform-optimized process management
• Native macOS Support - Complete support for both Intel and Apple Silicon Macs
• Native Linux Support - Optimized for Linux servers and development environments
• Unified API - Same commands and features work identically across all platforms
• Platform-Specific Optimizations - Tailored signal handling and process termination for each OS

📦 Installation

From Source (All Platforms)

git clone https://github.com/entrepeneur4lyf/pmdaemon
cd pmdaemon
cargo build --release

Linux/macOS:

sudo cp target/release/pmdaemon /usr/local/bin/

Windows:

copy target\release\pmdaemon.exe C:\Windows\System32\

Using Cargo (All Platforms)

cargo install pmdaemon

Pre-built Binaries

Download platform-specific binaries from GitHub Releases:

• Linux: pmdaemon-linux-x86_64
• Windows: pmdaemon-windows-x86_64.exe
• macOS Intel: pmdaemon-macos-x86_64
• macOS Apple Silicon: pmdaemon-macos-aarch64

🚀 Quick Start

Cross-Platform Note: All commands below work identically on Linux, Windows, and macOS. PMDaemon automatically handles platform-specific differences internally.

Basic Process Management

# Start a process
pmdaemon start app.js --name myapp

# List all processes
pmdaemon list

# Stop a process
pmdaemon stop myapp

# Restart a process
pmdaemon restart myapp

# Delete a process (stops if running)
pmdaemon delete myapp

# Delete all processes
pmdaemon delete all --force

# Delete processes by status
pmdaemon delete stopped --status --force

Clustering with Port Management

# Start 4 instances with port range
pmdaemon start server.js --instances 4 --port 4000-4003

# Auto-assign ports from range
pmdaemon start worker.js --port auto:5000-5100

# Runtime port override (doesn't modify saved config)
pmdaemon restart myapp --port 3001

Ecosystem Configuration Files

# Start all apps from config file (JSON, YAML, or TOML)
pmdaemon --config ecosystem.json start

# Start specific app from config file
pmdaemon --config ecosystem.yaml start --name my-web-app

# Example ecosystem.json
{
  "apps": [
    {
      "name": "web-server",
      "script": "node",
      "args": ["server.js"],
      "instances": 2,
      "port": "3000-3001",
      "env": {
        "NODE_ENV": "production"
      }
    }
  ]
}

Memory Limits and Monitoring

# Set memory limit with auto-restart
pmdaemon start app.js --max-memory 100M

# Real-time monitoring with configurable intervals
pmdaemon monit --interval 2

# View logs
pmdaemon logs myapp

# Follow logs in real-time
pmdaemon logs myapp --follow

Health Checks and Blocking Start

# Start with HTTP health check and wait for ready
pmdaemon start app.js --health-check-url http://localhost:9615/health --wait-ready

# Start with script-based health check
pmdaemon start worker.js --health-check-script ./health-check.sh --wait-ready

# Custom health check timeout
pmdaemon start api.js --health-check-url http://localhost:9615/status --wait-timeout 30s

Web API Server

# Start web API server for remote monitoring (no authentication)
pmdaemon web --port 9615 --host 127.0.0.1

# Start with API key authentication (recommended for production)
pmdaemon web --api-key "your-secret-api-key"

📋 Command Reference

| Command | Description | Example | |-------------|----------------------------|----------------------------------------| | start | Start a new process | pmdaemon start app.js --name myapp | | | Start from config file | pmdaemon --config ecosystem.json start | | stop | Stop a process | pmdaemon stop myapp | | restart | Restart a process | pmdaemon restart myapp | | reload | Graceful restart | pmdaemon reload myapp | | delete | Delete process(es) | pmdaemon delete myapp | | | Delete all processes | pmdaemon delete all --force | | | Delete by status | pmdaemon delete stopped --status | | list | List all processes | pmdaemon list | | monit | Real-time monitoring | pmdaemon monit --interval 2 | | logs | View/follow process logs | pmdaemon logs myapp --follow | | info | Process details | pmdaemon info myapp | | web | Start web API server | pmdaemon web --port 9615 |

🔧 Configuration Options

Ecosystem Configuration Files

PMDaemon supports ecosystem configuration files in JSON, YAML, and TOML formats for managing multiple applications:

# Use ecosystem config file
pmdaemon --config ecosystem.json start

# Start specific app from config
pmdaemon --config ecosystem.yaml start --name web-server

Example ecosystem.json:

{
  "apps": [
    {
      "name": "web-server",
      "script": "node",
      "args": ["server.js"],
      "instances": 2,
      "port": "3000-3001",
      "env": {
        "NODE_ENV": "production"
      },
      "health_check_url": "http://localhost:3000/health"
    },
    {
      "name": "api-service",
      "script": "python",
      "args": ["api.py"],
      "cwd": "/path/to/api",
      "max_memory_restart": "512M"
    }
  ]
}

Supported config formats:

• ecosystem.json - JSON format
• ecosystem.yaml / ecosystem.yml - YAML format
• ecosystem.toml - TOML format

See CONFIG_USAGE.md for de