A modern, powerful process manager with a beautiful Terminal User Interface (TUI). Inspired by pm2, built with Go and Bubbletea.

• 🚀 Universal Process Management - Run applications in any language (Node.js, Python, Go, Rust, Ruby, Bash, etc.)
• 🎨 Beautiful TUI - Three interactive views: Dashboard, Monitor, and Logs
• 📊 Real-time Metrics - CPU, memory, network, and uptime monitoring
• 🔄 Smart Process Control - Graceful shutdown with SIGTERM → SIGKILL fallback
• 💾 State Persistence - Processes survive prox restarts via ~/.prox/state.json
• 📝 Log Management - Live log tailing with continuous file writing
• ⌨️ Vim-like Navigation - Keyboard-first interface (hjkl, arrows)
• 📦 YAML Configuration - Define all your services in prox.yml
• 🔧 Auto-detection - Automatically detects interpreters by file extension
• 🎯 Process Monitoring - 4-panel detailed view (pm2 monit style)
• 📜 Log Viewer - Real-time log streaming with export capabilities

go install github.com/craigderington/prox@latest

This installs the prox binary to $GOPATH/bin (usually ~/go/bin). Make sure this directory is in your PATH.

# Clone the repository
git clone https://github.com/craigderington/prox.git
cd prox

# Build the binary
go build -o prox .

# Optional: Install globally
sudo mv prox /usr/local/bin/

prox

The TUI provides three main views:

1. Dashboard - Overview of all processes with quick actions
2. Monitor - Detailed 4-panel view for selected process (like pm2 monit)
3. Logs - Real-time log viewer with continuous export capability

# Start a process
prox start app.py --name my-worker

# Start with custom interpreter and working directory
prox start server.js --name api --cwd /path/to/app --interpreter node

# Start all services from prox.yml
prox start-all

# List all processes
prox list

# View process logs
prox logs my-worker

# Stop a process
prox stop my-worker

# Restart a process
prox restart my-worker

# Delete a process
prox delete my-worker

# Initialize prox.yml from existing processes
prox init

Create a prox.yml file to define all your services:

services:
  - name: web-server
    script: server.js
    interpreter: node
    cwd: /path/to/app
    args:
      - --port
      - "3000"
    env:
      NODE_ENV: production
      PORT: "3000"

  - name: worker
    script: worker.py
    interpreter: python3
    cwd: /path/to/worker
    env:
      PYTHONUNBUFFERED: "1"

  - name: api
    script: ./api
    cwd: /path/to/api
    env:
      GO_ENV: production

Then start all services at once:

prox start-all

The w key in the logs view now works as a toggle:

• Press w once: Starts continuous writing mode

  • Creates a timestamped file (e.g., myapp_logs_2025-12-25_14-30-00.txt)
  • Writes all current logs
  • Continuously appends new logs as they arrive
  • Indicator turns GOLD showing "w WRITING"

• Press w again: Stops writing and closes the file

  • Indicator returns to normal "w write"

prox automatically detects the interpreter based on file extension:

Or specify manually:

prox start script.py --interpreter python3

All process state and data is stored in ~/.prox/:

~/.prox/
├── state.json          # Process configurations and status
├── logs/               # Process logs (stdout/stderr)
│   ├── myapp-out.log
│   └── myapp-err.log
├── pids/               # PID files
└── processes/          # Process definitions

prox validates your prox.yml configuration to catch common errors:

• Required Fields: Services must have either script or command
• Service Names: Must contain only letters, numbers, dashes, and underscores
• Interpreters: Must be supported (node, python, ruby, perl, php, bash, etc.)
• Restart Policies: Must be "always", "on-failure", or "never"
• Environment Variables: Must follow UPPER_CASE naming conventions
• Dependencies: Cannot have circular dependencies
• Instances: Must be positive integers

services:
  web:
    script: server.js
    interpreter: node
    instances: 2
    restart: on-failure
    env:
      NODE_ENV: production
      PORT: "3000"
    depends_on:
      - database

  database:
    command: redis-server
    restart: always

Symptoms: Process shows "errored" status immediately Causes:

• Invalid interpreter or script path
• Missing dependencies
• Permission issues
• Port conflicts

Solutions:

# Check script exists and is executable
ls -la /path/to/your/script.js

# Test manually
node /path/to/your/script.js

# Check prox logs
prox logs process-name

Symptoms: prox process uses excessive CPU Solutions:

• Increase metrics polling interval in ~/.prox/
• Reduce number of concurrent processes
• Check for runaway processes

Symptoms: prox logs shows no output Causes:

• Process not started with prox
• Log files not created due to permissions
• Process writing to different location

Check:

# Verify log files exist
ls -la ~/.prox/logs/

# Check process status
prox list

Symptoms: "Address already in use" errors Solutions:

• Use different ports in environment variables
• Kill conflicting processes: lsof -i :port
• Configure services to use dynamic ports

Symptoms: "permission denied" when starting processes Solutions:

# Make scripts executable
chmod +x your-script.sh

# Check prox data directory permissions
ls -ld ~/.prox/

• Default: 2-second polling interval
• For low-power systems: Increase to 5-10 seconds
• For real-time monitoring: Decrease to 1 second (increases CPU usage)

• Recommended max: 50-100 processes per prox instance
• Memory usage: ~50MB base + ~2MB per process
• CPU usage: Minimal when polling every 2+ seconds

• Automatic rotation: Based on size limits
• Cleanup: Remove old log files periodically
• External logging: Consider log aggregation for production

1. Check logs: prox logs service-name --lines 100
2. Process status: prox list
3. Configuration validation: prox validates config on startup
4. Verbose output: Use --verbose flags where available

Built with modern Go libraries for reliability and cross-platform support:

• Bubbletea - TUI framework (Elm Architecture)
• Bubbles - TUI components (viewports, text inputs)
• Lipgloss - Terminal styling and layout
• gopsutil - Cross-platform system and process metrics
• Cobra - CLI framework

• Cross-Platform: Runs on Linux, macOS, Windows, and more
• Configuration Validation: Comprehensive YAML validation with helpful error messages
• Resource Management: Proper cleanup of processes, files, and memory
• Performance Optimized: Configurable metrics polling, efficient data structures
• Production Ready: 40%+ test coverage, comprehensive validation, logging, and error handling

• Development: Manage microservices locally
• Production: Simple process orchestration on single servers
• Testing: Run and monitor test suites
• Scripts: Manage background tasks and cron alternatives

# Start your services from YAML
prox start-all

# Launch TUI to monitor everything
prox

# In the TUI:
# - Press 'Enter' on a process to see detailed metrics
# - Press 'l' to view live logs
# - Press 'w' to start continuous log writing
# - Press 'r' to restart a service
# - Press 'q' to quit

# Or use CLI commands
prox logs api --follow
prox restart worker
prox list

# Build
go build -o prox .

# Run tests
go test ./...

# Run with race detection
go test -race ./...

# Run tests with coverage
make test-coverage

# Install locally
go install

• Storage: 57.6% coverage
• Process Management: 40.6% coverage
• Configuration: 48.1% coverage
• Integration Tests: End-to-end process lifecycle testing

All tests pass with comprehensive validation of core functionality.

Contributions are welcome! Please feel free to submit a Pull Request.

MIT License - see LICENSE file for details

• Inspired by pm2
• Built with the amazing Charm libraries
• Community feedback and contributions

Made with ❤️ and Go