🚀 Runara - Node.js Process Manager

Runara is a modern and lightweight process manager for Node.js applications that allows you to manage, monitor, and maintain running processes in a simple and efficient way.

📋 Table of Contents

• Features
• Installation
• Quick Start
• Commands
• Usage Examples
• Architecture
• Configuration
• Logs
• Monitoring
• Supported Platforms
• Development
• License

✨ Features

🎯 Core Functionality

• Daemon Management: Background service that keeps processes alive
• Web Dashboard: Modern React-based interface for visual process management
• Intuitive CLI: Easy-to-use command line interface
• Auto Restart: Processes restart automatically if they fail
• Persistence: Processes persist across system reboots
• Integrated Logging: Automatic capture of stdout/stderr with timestamps
• Real-time Monitoring: CPU, memory and process status monitoring
• Cross-platform: Works on Windows, macOS and Linux

🛡️ Advanced Features

• Restart Limits: Configure maximum number of restarts
• Minimum Runtime: Prevents restart loops for processes that fail quickly
• Process Tree Management: Properly terminates child processes
• IPC Communication: Efficient communication between CLI and daemon via sockets

📦 Installation

Global Installation (Recommended)

npm install -g runara

Local Installation

npm install runara
npx runara --help

From Source Code

git clone https://github.com/adriangrana/runara.git
cd runara
npm install
npm link  # For global usage

🚀 Quick Start

1. Start the Daemon

runara daemon start

2. Run Your First Application

runara run "node app.js" --name my-api

3. Check Your Processes Status

runara list

4. Monitor Processes in Real-time

runara monit all

5. Open Web Dashboard

runara dashboard start
# Open http://127.0.0.1:43522 in your browser

📖 Commands

General

runara --version, -v      # Show version
runara --help, -h         # Show help

Daemon Management

runara daemon start    # Start the daemon
runara daemon stop     # Stop the daemon
runara daemon restart  # Restart the daemon
runara daemon status   # Check daemon status
runara daemon autostart status   # Check daemon OS autostart
runara daemon autostart enable   # Enable daemon auto-start on login
runara daemon autostart disable  # Disable daemon auto-start on login

Dashboard Management

runara dashboard start    # Start the web dashboard
runara dashboard stop     # Stop the web dashboard
runara dashboard status   # Check dashboard status

Process Management

runara run <command> [options]        # Execute a new process
runara start <name|all>               # Start saved process(es)
runara stop <name|all>                # Stop process(es)
runara restart <name|all>             # Restart process(es)
runara remove <name|all>              # Remove process(es) from registry
runara set <name> [options]           # Modify process configuration

run command options

--name <name>             # Process name
--cwd <directory>         # Working directory
--max-restarts <N>        # Maximum number of restarts
--restart-delay <MS>      # Delay between restarts in milliseconds
--min-uptime <MS>         # Minimum runtime in milliseconds
--no-autorestart         # Disable automatic restart
--stopped                # Register without starting
--autostart              # Start automatically (default)

set command options

--command <command>       # Change process command
--cwd <directory>         # Change working directory
--max-restarts <N>        # Change maximum number of restarts
--restart-delay <MS>      # Change delay between restarts
--min-uptime <MS>         # Change minimum runtime
--no-autorestart         # Disable automatic restart
--autorestart            # Enable automatic restart
--stopped                # Mark as stopped
--autostart              # Mark for automatic start

Information and Monitoring

runara list                          # List all processes
runara info <name>                   # Detailed information about a process
runara logs <name> [--err] [--lines N]  # View process logs
runara monit <name|all>              # Real-time monitoring
runara save                          # Save current configuration
runara set <name> [options]          # Modify process configuration

💡 Usage Examples

Run a REST API

runara run "node server.js" --name api-backend
runara run "npm start" --name frontend

Run with Specific Configuration

runara run "node app.js --port 3000" --name my-app
runara run "npm run dev" --name frontend --cwd /path/to/frontend
runara run "python worker.py" --name worker --max-restarts 5 --restart-delay 5000

Modify Existing Process Configuration

# Change process command
runara set my-app --command "node app.js --port 4000"

# Change working directory
runara set my-app --cwd /new/directory

# Modify restart policies
runara set my-app --max-restarts 20 --restart-delay 3000

# Disable automatic restart
runara set my-app --no-autorestart

# Register process without starting it
runara run "node background-job.js" --name job --stopped

Monitor Multiple Services

# Start several services
runara run "node api.js" --name api
runara run "node worker.js" --name worker
runara run "node scheduler.js" --name scheduler

# Monitor all
runara monit all

Log Management

# View last 100 log lines
runara logs api --lines 100

# View error logs
runara logs api --err

# View logs in real-time (use tail on Unix systems)
tail -f ~/.runara/logs/api.log

Batch Management

# Stop all processes
runara stop all

# Restart all processes
runara restart all

# Remove all processes from registry
runara remove all

🏗️ Architecture

Main Components

1. CLI (cli/cli.js)

• Main user interface
• Command and argument parsing
• Communication with daemon via TCP sockets

2. Daemon (daemon/daemon.js)

• Background service (PID: ~/.runara/runara.pid)
• TCP server on port 43521
• Automatic process restoration on startup

3. Process Manager (core/processManager.js)

• Main process management engine
• Spawn and lifecycle management
• Automatic restart with configurable strategies
• Integrated logging

4. Registry (core/registry.js)

• Persistence in ~/.runara/db.json
• CRUD for process configurations
• Data validation and normalization

5. Monitor (core/monitor.js)

• System metrics collection
• CPU and memory usage per process
• Compatible with Windows (PowerShell) and Unix (ps)

6. Logger (core/logger.js)

• Structured logging with timestamps
• stdout/stderr separation
• Files in ~/.runara/logs/

7. Dashboard (dashboard/)

• Modern React-based web interface
• Real-time process monitoring and management
• Configuration management through UI
• Professional branding and responsive design
• HTTP server on port 43522

Workflow

CLI → TCP Socket → Daemon → Process Manager → Child Process
                         ↓
                    Registry (persistence)
                         ↓  
                    Logger (logs) + Monitor (metrics)
                         ↑
                    Dashboard (HTTP API + Web UI)

⚙️ Configuration

Default Configuration

{
    minUptimeMs: 2000,      // Minimum time before considering restart
    restartDelayMs: 2000,   // Delay between restarts (milliseconds)
    maxRestarts: 10,        // Maximum number of restarts
    autorestart: true,      // Auto restart enabled
    desiredState: "started" // Desired state (started/stopped)
}

Custom Configuration

You can customize these values when creating or modifying processes:

# When creating a process
runara run "node app.js" --name api \
  --max-restarts 20 \
  --restart-delay 5000 \
  --min-uptime 10000

# When modifying an existing process
runara set api --max-restarts 50 --no-autorestart

File Locations

• Base Directory: ~/.runara/
• Daemon PID: ~/.runara/runara.pid
• Database: ~/.runara/db.json
• Logs: ~/.runara/logs/
  • Stdout: {name}.log
  • Stderr: {name}.error.log

Environment Variables

• ComSpec (Windows): Default shell
• RUNARA_HOME: Custom base directory (future)

📊 Logs

Log Structure

[2026-03-13T10:30:15.123Z] process message
[2026-03-13T10:30:16.456Z] another message

Log Commands

# View normal logs (stdout)
runara logs my-app

# View error logs (stderr)
runara logs my-app --err

# View last N lines
runara logs my-app --lines 50

Log Rotation

Logs accumulate indefinitely. For manual rotation:

# Clear logs for a process
rm ~/.runara/logs/my-app.*

# Clear all logs
rm ~/.runara/logs/*

📈 Monitoring

Monitor Command

# Monitor specific process
runara monit my-app

# Monitor all processes
runara monit all

Available Metrics

• PID: Process ID
• Status: running, stopped, failed, restarting
• CPU Usage: Percentage of usage
• Memory: RAM used (automatic formatting: B, KB, MB, GB)
• Runtime: Since last start
• Restarts: Number of automatic restarts

Monitor Output

[my-app] PID: 12345 | CPU: 0.5% | Mem: 45.2 MB | Status: running | Restarts: 0
[worker] PID: 12346 | CPU: 1.2% | Mem: 23.1 MB | Status: running | Restarts: 1

🔧 Supported Platforms

✅ Windows

• Uses cmd.exe for process spawning
• PowerShell for system metrics
• taskkill for process termination

✅ Unix/Linux/macOS

• Uses /bin/sh for process spawning
• ps for system metrics
• SIGTERM for process termination

Implementation Differences

• Windows: ComSpec, taskkill /PID /T /F, PowerShell Get-Process
• Unix: SHELL, kill -TERM, ps -p PID -o pid=,%cpu=,rss=

🛠️ Development

Project Structure

runara/
├── package.json          # Package configuration
├── README.MD             # This file
├── cli/
│   ├── cli.js           # Command line interface
│   └── helpers.js       # CLI helper functions
├── core/
│   ├── logger.js        # Logging system
│   ├── monitor.js       # Process monitoring
│   ├── processManager.js # Process management
│   └── registry.js      # Persistence
├── daemon/
│   └── daemon.js        # Daemon service
└── dashboard/
    ├── server.js        # Dashboard HTTP server
    ├── package.json     # Dashboard dependencies
    ├── src/
    │   ├── App.jsx      # Main React application
    │   └── components/  # React components
    └── dist/           # Built dashboard files

Run in Development

git clone <repo>
cd runara
npm install

# Local testing
node cli/cli.js daemon start
node cli/cli.js run "echo hello" --name test
node cli/cli.js list

Debugging

# View daemon logs
tail -f ~/.runara/logs/runara-daemon.log

# Check daemon PID
cat ~/.runara/runara.pid

# Process status
cat ~/.runara/db.json

Testing

npm test  # Currently: placeholder

🤝 Contribution

Issues and Bugs

1. Review existing issues
2. Create a detailed issue with reproduction steps
3. Include Node.js version and OS

Pull Requests

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

Roadmap

• [x] Web interface (dashboard) - ✅ Completed with React + modern UI
• [ ] File-based configuration (yaml/json)
• [ ] Clusters and load balancing
• [ ] Docker integration
• [ ] Advanced metrics and alerts
• [ ] Plugins and extensions
• [ ] Unit and integration tests

📄 License

ISC License - see LICENSE file for details.

🏷️ Version

v0.1.2 - Latest version with daemon cross-platform autostart

Runara - Keeping your Node.js processes running simple and reliable.

For more information, issues or contributions, visit: GitHub Repository

Estructura del Proyecto

runara/
├── package.json          # Configuración del paquete
├── README.MD             # Este archivo
├── cli/
│   └── cli.js           # Interfaz de línea de comandos
├── core/
│   ├── logger.js        # Sistema de logging
│   ├── monitor.js       # Monitoreo de procesos
│   ├── processManager.js # Gestión de procesos
│   └── registry.js      # Persistencia
└── daemon/
    └── daemon.js        # Servicio daemon

Ejecutar en Desarrollo

git clone <repo>
cd runara
npm install

# Prueba local
node cli/cli.js daemon start
node cli/cli.js run "echo hello" --name test
node cli/cli.js list

Debugging

# Ver logs del daemon
tail -f ~/.runara/logs/runara-daemon.log

# Verificar PID del daemon
cat ~/.runara/runara.pid

# Estado de procesos
cat ~/.runara/db.json

Testing

npm test  # Actualmente: placeholder

🤝 Contribución

Issues y Bugs

1. Revisa los issues existentes
2. Crea un issue detallado con pasos para reproducir
3. Incluye versión de Node.js y OS

Pull Requests

1. Fork el repositorio
2. Crea una rama feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -am 'Agregar nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Crea un Pull Request

Roadmap

• [ ] Interfaz web (dashboard)
• [ ] Configuración por archivo (yaml/json)
• [ ] Clusters y balanceeo de carga
• [ ] Integración con Docker
• [ ] Métricas avanzadas y alertas
• [ ] Plugins y extensiones
• [ ] Tests unitarios e integración

📄 Licencia

ISC License - see LICENSE file for details.

🏷️ Version

v0.1.2 - Latest version with daemon cross-platform autostart

Runara - Keeping your Node.js processes running simple and reliable.

For more information, issues or contributions, visit: GitHub Repository