procman

A simple process manager written in Lua. Uses coroutines for scheduling and luaposix fork/exec/waitpid for managing real OS processes.

Features

• Define, start, stop, and monitor shell commands
• Auto-restart with configurable retry limits
• Process definitions stored in a config file (procs.conf)
• CLI for managing processes from the terminal
• Supervised foreground mode with signal handling (Ctrl-C)
• Per-process log files (stdout/stderr)
• Also supports in-process Lua coroutine tasks via the library API

Requirements

• Lua 5.4
• luaposix (lua-posix package)

Install on Arch Linux

sudo pacman -S lua lua-posix

Install via LuaRocks

luarocks install luaposix

Quick Start

# Define some processes
./pm define web 'python3 -m http.server 8080' --restart
./pm define worker 'bash worker.sh' --restart --max-restarts 5
./pm define backup 'rsync -a /data /backup'

# View defined processes
./pm list

# Run the supervisor (foreground, Ctrl-C to stop)
./pm run

CLI Usage

pm define <name> <command> [--restart] [--max-restarts N]
pm undef  <name>
pm start  <name | --all>
pm stop   <name | --all>
pm kill   <name | --all>
pm restart <name | --all>
pm status [name]
pm list
pm run    [--tick N]
pm logs   <name> [--follow | -f]
pm edit

See docs/cli.md for full CLI reference.

Library Usage

local ProcessManager = require("procman")
local pm = ProcessManager.new()

-- Define a shell command process
pm:define("web", "python3 -m http.server 8080", {
    auto_restart = true,
    max_restarts = 10,
})

-- Define a Lua coroutine process
pm:define_lua("heartbeat", function(ctx)
    while not ctx:should_stop() do
        print("alive")
        ctx:yield()
    end
end)

-- Start and run
pm:start("web")
pm:start("heartbeat")
pm:run({ tick_interval = 1 })

See docs/api.md for full library reference.

Project Structure

procman/
  pm              -- CLI entry point (executable)
  procman.lua     -- Core library module
  docs/
    design.md     -- Architecture and implementation details
    api.md        -- Library API reference
    cli.md        -- CLI usage reference
  test.lua        -- Self-contained test suite
  examples/
    demo.lua      -- Demo script (exec + lua processes)
    procs.conf    -- Sample process definition file

Tests

No external dependencies required. Run:

lua test.lua

Documentation

• Design and Architecture -- how fork/exec, coroutines, the scheduler loop, and auto-restart work
• Library API Reference -- all public methods
• CLI Reference -- all commands and options

License

Public domain. Use as you like.