PMDaemon - Advanced Process Manager

A high-performance, cross-platform process manager built in Rust

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 detailed ecosystem configuration documentation.

Process Configuration

pmdaemon start app.js \
  --name "my-app" \
  --instances 4 \
  --port 3000-3003 \
  --max-memory 512M \
  --env NODE_ENV=production \
  --cwd /path/to/app \
  --log-file /var/log/app.log \
  --health-check-url http://localhost:9615/health \
  --wait-ready

Port Management Options

Option	Description	Example
--port 3000	Single port assignment	Assigns port 3000
--port 3000-3005	Port range for clusters	Distributes 3000-3005
--port auto:4000-4100	Auto-find available port	First available in range

Health Check Options

Option	Description	Example
--health-check-url <url>	HTTP endpoint for health checks	http://localhost:9615/health
--health-check-script <path>	Script to run for health validation	./scripts/health-check.sh
--health-check-timeout <time>	Timeout for individual health checks	5s, 30s, 1m
--health-check-interval <time>	Interval between health checks	10s, 30s, 1m
--health-check-retries <num>	Number of retries before failure	3, 5, 10
--wait-ready	Block start until health checks pass	Boolean flag
--wait-timeout <time>	Timeout for blocking start	30s, 1m, 5m

Delete Options

Option	Description	Example
delete <name>	Delete single process by name/ID	pmdaemon delete myapp
delete all	Delete all processes	pmdaemon delete all
delete <status> --status	Delete processes by status	pmdaemon delete stopped --status
--force / -f	Skip confirmation prompts	pmdaemon delete all --force

Valid statuses for --status flag: - starting - Processes currently starting up - online - Running processes - stopping - Processes currently shutting down - stopped - Processes that have exited - errored - Processes that crashed or failed - restarting - Processes currently restarting

Safety Features: - All delete operations automatically stop running processes before deletion - Interactive confirmation prompts for bulk operations (unless --force is used) - Graceful process shutdown with proper cleanup of files and ports - Clear feedback showing how many processes were stopped vs. deleted

🌐 Web API

PMDaemon provides a comprehensive REST API with optional authentication:

Security Features

• API Key Authentication - Secure your API with keys
• Process Management Only - Cannot create new processes for security
• Production Ready - Built with security best practices

Endpoints

Method	Endpoint	Description	Auth Required
GET	/api/processes	List all processes	✅
POST	/api/processes/:id/start	Start existing process	✅
DELETE	/api/processes/:id	Stop/delete a process	✅
GET	/api/system	Syste