Procler

LLM-first process manager for developers. Define processes in YAML, manage them through a JSON-native CLI or a Vue 3 dashboard. Local shells and Docker containers use the same commands. Everything returns structured JSON.

Why Procler?

There’s a gap between docker compose up and a real process manager. Compose is great for containers but can’t manage local shell processes. pm2 is Node-centric. supervisord needs root and XML config files. None of them are designed for AI agents to consume.

Procler fills that gap. One config file, one CLI, one API — for both local processes and Docker containers. Every command returns JSON with a consistent {success, data?, error?, error_code?, suggestion?} shape. An LLM agent can discover all commands via procler capabilities, understand the current config via procler config explain, and operate everything programmatically.

Good fit: dev environment orchestration, multi-service projects where some processes are local and some are containerized, AI-assisted operations, anything where structured output matters more than pretty-printed tables.

Quick Start

pip install procler              # or: uv add procler

# Initialize project config
procler config init

# Define and run a process
procler define --name api --command "uvicorn main:app --reload"
procler start api
procler status api
procler logs api --tail 20

# Or use config-driven groups
procler group start backend

Config lives in .procler/config.yaml — version-controllable, portable, human-readable.

Architecture

YAML Config ──→ ProcessManager ──→ ExecutionContext ──→ Shell / Docker
                     │
          ┌──────────┼──────────┐
          │          │          │
       Groups    Recipes    Health
     (ordered   (multi-    (probes +
      start)     step)     deps)
          │          │          │
          └──────────┼──────────┘
                     │
              ┌──────┴──────┐
              │             │
           CLI (Click)   API (FastAPI)
           JSON stdout   REST + WebSocket
                         Vue 3 Dashboard

The ProcessManager is the single coordinator. CLI and API are thin layers over the same core. ExecutionContext is an abstract interface — LocalContext spawns subprocesses, DockerContext uses the Docker SDK. Switching between them is a one-line config change.

Features

JSON-Native CLI

Every command returns structured JSON. No parsing stdout, no regex on table output:

# Discover all commands (LLM agent entry point)
procler capabilities

# Structured status with Linux kernel state
procler status api
# {"success": true, "data": {"name": "api", "status": "running", "pid": 12345, ...}}

# Plain-language config explanation
procler config explain

Health Probes & Dependencies

Processes can declare health checks and depend on other processes reaching specific states:

processes:
  api:
    command: uvicorn main:app
    healthcheck:
      test: "curl -f http://localhost:8000/health"
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

  worker:
    command: celery worker
    depends_on:
      - name: api
        condition: healthy    # Wait for health check to pass

Group start respects dependency order. procler group start backend starts redis first, waits for it, starts api, waits for healthy, then starts worker.

Groups & Recipes

Groups are ordered process sets. Recipes are multi-step operations:

groups:
  backend:
    processes: [redis, api, worker]
    stop_order: [worker, api, redis]

recipes:
  deploy:
    on_error: stop
    steps:
      - stop: worker
      - stop: api
      - wait: 2s
      - exec: "alembic upgrade head"
      - start: api
      - start: worker

procler recipe run deploy --dry-run    # Preview steps
procler recipe run deploy              # Execute

Replicas & Namespaces

Scale processes horizontally. Namespace to isolate environments:

processes:
  worker:
    command: celery worker
    replicas: 3           # worker-1, worker-2, worker-3
    namespace: staging

Cron Scheduling

Schedule processes with cron expressions:

processes:
  cleanup:
    command: python cleanup.py
    schedule: "0 */6 * * *"    # Every 6 hours

Export & Import

Move configs between machines or share with teammates:

procler config export --output my-stack.json
procler config import my-stack.json
procler config import Procfile    # Import from Heroku Procfile

Dual Context: Local + Docker

Same commands, different execution targets:

processes:
  api:
    command: python main.py
    context: local

  postgres:
    command: postgres
    context: docker
    container: my-postgres

procler start api spawns a subprocess. procler start postgres uses Docker SDK. The status, logs, start, stop commands work identically for both.

Linux Process States

Status output includes kernel-level state from /proc/[pid]/stat:

{
  "linux_state": {
    "state_code": "D",
    "state_name": "disk_sleep",
    "is_killable": false
  },
  "warning": "Process in D state cannot be killed"
}

Web Dashboard

Vue 3 + Naive UI dashboard with Cyberpunk theme:

View	Purpose
Dashboard	Stats, quick actions, recent activity
Processes	CRUD, status indicators, per-action loading
Process Detail	Live logs with search/filter, stream filtering
Groups	Card-based, one-click start/stop all
Recipes	Step preview, dry-run, execution progress
Snippets	Reusable command management
Config	Status, stats, changelog viewer

Keyboard shortcuts (? for help), WebSocket status indicator, toast notifications on status changes, ARIA labels for accessibility.

TUI Mode

Terminal UI via Textual for SSH sessions and headless servers:

pip install procler[tui]
procler tui

Split-pane layout: process list on the left, live logs on the right. Keyboard-driven: arrow keys to navigate, s/x/r to start/stop/restart, F5 to refresh, q to quit.

Real-Time Updates

WebSocket support for live log streaming and status changes:

{"action": "subscribe_logs", "process_id": 1}
{"action": "subscribe_status"}

EventBus architecture — CLI, API, TUI, and dashboard all receive the same events.

Honest Limitations

Single machine — No distributed process management. This manages processes on one host. For multi-machine, use Kubernetes.
No auto-restart — Processes that crash stay crashed. Health probes detect it, but auto-restart policies aren’t implemented yet.
SQLite state — Runtime state is in SQLite. Fast and simple, but means the state file can’t be shared across hosts.
Docker SDK only — Container management uses docker-py, not Podman or containerd. Docker must be installed and running.
TUI is v1 — Start/stop/restart actions, error states, and refresh loop aren’t fully tested. Works for monitoring, rough edges for control.

Getting Started

pip install procler               # or: uv add procler
pip install procler[tui]          # optional TUI mode

Python 3.12+ · Docker optional (only needed for container context).

uv run pytest tests/ -v           # 320 tests
procler capabilities              # Discover all commands
procler config init               # Initialize project