prox

A modern process manager for development with an API-first design.

Features

• Simple by default - Procfile-like experience with minimal configuration
• API-first - Full process control and log access via HTTP
• Interactive TUI - Real-time log viewing with filtering and search
• Health checks - Optional health monitoring for processes

Installation

Homebrew (macOS)

brew install charliek/tap/prox

Linux (apt)

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://apt.stridelabs.ai/pubkey.gpg | \
  sudo tee /etc/apt/keyrings/apt-charliek.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/keyrings/apt-charliek.gpg] https://apt.stridelabs.ai noble main' | \
  sudo tee /etc/apt/sources.list.d/apt-charliek.list
sudo apt update
sudo apt install prox

Tested on Pop!_OS 24.04 and Ubuntu 24.04+. Architectures: amd64, arm64. See apt-charliek for the full repo.

Linux (.deb download, no apt repo)

For one-off installs without configuring the apt repo (CI runners, locked-down hosts, etc.):

ARCH=$(dpkg --print-architecture)        # amd64 or arm64
VERSION=0.1.1                            # check https://github.com/charliek/prox/releases for the latest
curl -fLO "https://github.com/charliek/prox/releases/download/v${VERSION}/prox_${VERSION}_${ARCH}.deb"
sudo apt install -y "./prox_${VERSION}_${ARCH}.deb"

The apt install ./...deb form resolves dependencies; plain dpkg -i would skip that step.

Other Methods

# Install via Go
go install github.com/charliek/prox/cmd/prox@latest

# Or build from source
git clone https://github.com/charliek/prox.git
cd prox
make build

Quick Start

Create a prox.yaml in your project directory:

processes:
  web: npm run dev
  api: go run ./cmd/server
  worker: python worker.py

Start all processes:

prox up

Start with the interactive TUI:

prox up --tui

Configuration

Simple Form

processes:
  web: npm run dev
  api: go run ./cmd/server

Expanded Form

api:
  port: 5555
  host: 127.0.0.1

env_file: .env

processes:
  web: npm run dev

  api:
    cmd: go run ./cmd/server
    env:
      PORT: "8080"
      DEBUG: "true"
    env_file: .env.api
    healthcheck:
      cmd: curl -f http://localhost:8080/health
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

CLI Commands

prox up [processes...]           # Start processes (foreground)
prox up --tui [processes...]     # Start with interactive TUI
prox stop                        # Stop running instance
prox restart <process>           # Restart a process
prox status                      # Show process status
prox logs [process]              # Show recent logs
prox logs -f [process]           # Stream logs

HTTP API

The API runs at http://127.0.0.1:5555/api/v1 by default.

Endpoint	Method	Description
/status	GET	Supervisor status
/processes	GET	List all processes
/processes/{name}	GET	Get process details
/processes/{name}/start	POST	Start a process
/processes/{name}/stop	POST	Stop a process
/processes/{name}/restart	POST	Restart a process
/logs	GET	Retrieve logs
/logs/stream	GET	Stream logs (SSE)
/shutdown	POST	Shutdown supervisor

Security

Configuration files are executed as code (via shell). Only use configuration from trusted sources, similar to Makefiles or Procfiles.

When binding to non-localhost interfaces, authentication is automatically enabled. A bearer token is generated and stored in ~/.config/prox/.

Documentation

Full documentation is available at charliek.github.io/prox.

See docs/spec.md for the complete specification including TUI keybindings, API details, and architecture.

Development

Prerequisites

This project uses mise to manage tool versions. With mise installed, all dependencies are set up automatically:

mise install

This installs the correct versions of Go and golangci-lint as defined in .mise.toml.

Alternatively, install manually:

• Go 1.24+
• golangci-lint v2 (brew install golangci-lint on macOS, or see install docs)

make build    # Build the binary
make test     # Run tests
make lint     # Run linters
make clean    # Remove build artifacts

Documentation Development

The documentation site uses MkDocs with Material theme.

# Install dependencies
uv sync --group docs

# Local preview (http://127.0.0.1:7070)
uv run mkdocs serve

# Build static site
uv run mkdocs build

Documentation is automatically published to GitHub Pages on push to main.

License

MIT