prox

command module

v0.2.0 Latest Latest Go to latest Published: Dec 26, 2025 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/craigderington/prox

Links

Open Source Insights

README ¶

⚡ prox

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

prox

✨ Features

🚀 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

📦 Installation

Option 1: Install via go install (Recommended)

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.

Option 2: Build from Source

# 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/

🚀 Quick Start

Launch Interactive TUI (Default Mode)

prox

The TUI provides three main views:

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

CLI Commands

# 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

📋 Configuration File (prox.yml)

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

🎮 Keyboard Shortcuts

Dashboard View

Key	Action
`↑/k`	Move selection up
`↓/j`	Move selection down
`n`	Start a new process (interactive input)
`Enter`	Open monitor view for selected process
`l`	Open logs view for selected process
`r`	Restart selected process
`s`	Stop selected process
`d`	Delete selected process
`R`	Refresh process list
`q`	Quit

Monitor View (4-Panel Detailed View)

Key	Action
`↑/k`	Move selection up in process list
`↓/j`	Move selection down in process list
`tab`	Switch between panels (Processes → Metrics → Metadata → Logs)
`f`	Toggle follow mode in logs panel
`w`	Write logs to file (when logs panel focused)
`r`	Restart selected process
`s`	Stop selected process
`d`	Delete selected process
`Esc/q`	Return to dashboard

Logs View

Key	Action
`↑/k`	Scroll up one line
`↓/j`	Scroll down one line
`u`	Scroll up half page
`d`	Scroll down half page
`g`	Go to top
`G`	Go to bottom
`f`	Toggle follow mode (auto-scroll)
`w`	Toggle continuous writing - Turns GOLD when actively writing logs to file
`r`	Refresh logs
`Esc/q`	Return to dashboard

✨ Continuous Log Writing

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"

🔧 Auto-detected Interpreters

prox automatically detects the interpreter based on file extension:

Extension	Interpreter
`.js`, `.mjs`, `.cjs`	`node`
`.ts`	`ts-node`
`.py`	`python`
`.rb`	`ruby`
`.sh`	`bash`
`.pl`	`perl`
`.php`	`php`

Or specify manually:

prox start script.py --interpreter python3

📁 Data Storage

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

🔧 Configuration Validation

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

Validation Rules

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

Example Valid Configuration

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

🚨 Troubleshooting

Common Issues

Process Won't Start

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

High CPU Usage

Symptoms: prox process uses excessive CPU Solutions:

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

Logs Not Appearing

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

Port Conflicts

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

Permission Denied

Symptoms: "permission denied" when starting processes Solutions:

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

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

Performance Tuning

Metrics Collection

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)

Process Limits

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

Log Management

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

Getting Help

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

🏗️ Architecture

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

Key Features

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

🎯 Use Cases

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

🔍 Example Workflow

# 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

🛠️ Development

Build & Test

# 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