#pm3

pm3 start ./worker.sh --name worker
pm3 start ./worker.py --interpreter python3 --name py-worker --cwd /srv/app
pm3 list
pm3 logs worker --follow
pm3 stop worker

#Highlights

• Any executable. pm3 supervises an arbitrary command line; the optional --interpreter flag covers scripts that are not directly executable.
• Crash recovery. Automatic restarts with min_uptime / unstable-restart tracking, restart budgets, restart delays, stop_exit_codes and max_memory_restart.
• Built-in, optimized log rotation. No external module, no logrotate cron job. Rotation is an O(1) rename + reopen performed by the daemon that owns the file descriptors — see Log rotation.
• Background gzip. Rotated files are compressed asynchronously, so a multi-gigabyte log never blocks a worker.
• A real daemon. The CLI talks to a detached supervisor over a loopback socket; the daemon owns child stdout/stderr pipes and keeps running after the terminal closes.
• Single static binary. One executable provides both the client and the daemon (pm3 daemon is the internal entry point).

#Install

# npm, pnpm, yarn or bun. The launcher downloads the native binary for this
# platform on first run; nothing is downloaded at install time.
npm install -g @tomasko/pm3

# Install script, no Node.js required.
curl -LsSf https://raw.githubusercontent.com/tomasky/pm3/master/install.sh | bash

# Or build from source, see below.

$ pnpm add @tomasko/pm3
Error: ERR_PNPM_IGNORED_BUILDS
  × adding a new package
  ╰─▶ Ignored build scripts: @tomasko/pm3@0.1.1

#Build

moon build --target native --release
# the binary is at _build/native/release/build/cmd/main/main.exe

moon build --target native
./_build/native/debug/build/cmd/main/main.exe list

#Static Linux build

sudo apt-get install musl-tools
./scripts/build-linux-static.sh dist/pm3-linux-x86_64

moon test --target native

#Releases

git tag v0.1.1 && git push origin v0.1.1

#Quick start

# Start a service. The name defaults to the script's basename ("worker").
pm3 start ./worker.sh

# Run a non-executable script through an interpreter.
pm3 start ./jobs/digest.py --interpreter python3 --name digest

# Pass arguments to the managed process after `--`.
pm3 start ./server --name api -- --port 8080

# Environment variables.
pm3 start ./server --name api -e PORT=8080 -e LOG_LEVEL=info

# Inspect it. Tables are drawn the way PM2 draws them; the footer totals the
# running processes.
pm3 list
# ┌────┬────────┬────────┬───────┬───────┬──────────┬────────┬────────────────────────────────────┐
# │ id │ name   │ status │ cpu   │ mem   │ restarts │ uptime │ command                            │
# ├────┼────────┼────────┼───────┼───────┼──────────┼────────┼────────────────────────────────────┤
# │ 0  │ digest │ online │ 86.9% │ 11.3mb │ 0        │ 6s     │ python3 ./digest.py                │
# │ 1  │ worker │ online │ 0%    │ 2.0mb  │ 0        │ 6s     │ sh -c while true; do sleep 1; done │
# └────┴────────┴────────┴───────┴────────┴──────────┴────────┴────────────────────────────────────┘
#
# 2/2 online   total cpu 86.9%   total mem 13.3mb

pm3 describe api
#  Describing process with id 0 - name digest
# ┌────────────────────┬───────────────────────────────────┐
# │ pm_id              │ 0                                 │
# │ name               │ digest                            │
# │ status             │ online                            │
# │ pid                │ 21557                             │
# │ command            │ python3 ./digest.py               │
# │ cwd                │ <inherited>                       │
# │ out log            │ /root/.pm3/logs/digest-out.log    │
# │ memory             │ 11.3mb                            │
# │ cpu                │ 86.9%                             │
# └────────────────────┴───────────────────────────────────┘

pm3 logs digest --follow

# Stop it, remove it.
pm3 stop api
pm3 delete api

pm3 start                 # reads ./pm3.toml
pm3 config apps           # show what that would start

#Configuration

#Application config

# pm3.toml
[defaults]                    # optional, applied to every app below
max_restarts = 16
max_memory_restart = "200M"

[[app]]
name = "worker"
script = "./worker.py"
interpreter = "python3"
args = ["--verbose"]
env = { PORT = "8080", LOG_LEVEL = "info" }

[[app]]
name = "api"
script = "./bin/server"
max_memory_restart = "1G"        # overrides the default for this app only
stop_exit_codes = [0, 2]

{
  "defaults": { "max_restarts": 16 },
  "app": [
    { "name": "worker", "script": "./worker.py", "interpreter": "python3" }
  ]
}

pm3 start                  # ./pm3.toml, or the global file
pm3 start --config prod.toml
pm3 start pm3.json         # a positional .toml/.json is a config file
pm3 config apps            # show what that would start, and validate the file

pm3 start <script> ... is unchanged: a single script is still started directly, and options after the script are passed to the program, so pm3 start sh -c 'echo hi' works. Use --config when the ambiguity matters.

#Commands

#start options

#How it works

        pm3 <command>                      pm3 daemon
   ┌────────────────────┐            ┌──────────────────────────┐
   │  client package    │  loopback  │  daemon package          │
   │  parse CLI         │ ─────────► │  accept + dispatch       │
   │  connect to daemon │  newline-  │  supervisor (per app)    │
   │  print results     │  delimited │  log sinks + rotation    │
   └────────────────────┘  JSON      │  gzip + prune workers    │
                                     │  resource monitor        │
                                     └────────────┬─────────────┘
                                                  │ pipes
                                        ┌─────────┴──────────┐
                                        │  managed children  │
                                        └────────────────────┘

• The CLI reads the daemon's ephemeral port from ~/.pm3/daemon.port. If the daemon is not running it starts one detached (spawn_orphan + setsid) and waits for the port file.
• Each managed app gets one supervisor coroutine that runs the spawn → wait → maybe restart loop.
• Child stdout/stderr are pipes owned by the daemon, pumped into LogSinks. This is what makes safe rotation possible.
• State lives in ~/.pm3:

~/.pm3/
├── dump.json          # serialized process table
├── config.toml        # configuration (or config.json)
├── daemon.port        # ephemeral TCP port (while running)
├── daemon.pid         # daemon pid (while running)
├── pm3.log            # daemon's own stdout/stderr
└── logs/
    ├── <name>-out.log
    ├── <name>-err.log
    └── <name>-out__<stamp>.log[.gz]

#Log rotation

#Why the rewrite

1. Data loss. Anything a worker writes between the copy finishing and the truncate completing is silently discarded.
2. O(size) work. A multi-gigabyte log has to be copied in full before it can be truncated; the rotation worker stalls, and on a busy service the window above is large.
3. Sparse holes. After truncate, the writer's file offset is still at the old position, so the next write lands far into the file and leaves a NUL-filled gap.

• Rotation is rename(live, live__<stamp>.log) followed by opening a fresh live file. That is O(1), atomic on POSIX, loses nothing (the writer immediately switches to the new descriptor), and never produces holes.
• Rotated files are matched by an exact prefix/suffix test (<base>__<stamp>.log[.gz]), so api-out__backup.log or a file that merely contains the base name is never mistaken for a rotated log.
• Gzip runs on a background worker with a configurable level, instead of blocking the rotation path.
• Retention is computed from modification times, and can additionally cap files by age.
• An optional min_size prevents rotating near-empty logs.
• If two rotations happen within the same timestamp tick, the second one gets a -1, -2, … suffix instead of overwriting its sibling.

#Policy

pm3 logrotate

pm3 set logrotate:max_size 100M
pm3 set logrotate:compress true
pm3 set logrotate:retain 14
pm3 set logrotate:rotate_interval "0 3 * * *"

#Configuration file

# ~/.pm3/config.toml
[logrotate]
max_size = "100M"
retain = 14
compress = true
compression_level = 6
rotate_interval = "0 3 * * *"
tz = "UTC+8"

{
  "logrotate": {
    "max_size": "100M",
    "retain": 14,
    "compress": true
  }
}

#Process lifecycle

• Stop sends kill_signal (default SIGTERM), waits up to kill_timeout milliseconds, then sends SIGKILL.
• Autorestart restarts the process whenever it exits, unless --no-autorestart was given, the exit code is listed in --stop-exit-codes, or the restart budget (--max-restarts) is exhausted.
• A run shorter than --min-uptime increments the unstable restarts counter.
• --max-memory-restart is enforced by a monitor that samples /proc/<pid>/status every two seconds.
• A process that is no longer desired online (stopped by the user, or out of restarts) is left alone by pm3 resurrect.
• After a daemon restart nothing can reattach to a dead child's pipes, so the loaded table starts out stopped; run pm3 resurrect to bring back the processes that were desired online. Any orphan from a hard daemon death is terminated first, so a service is never started twice.

#Environment variables

#Limitations

• Native (--target native) only: it needs POSIX process, signal and file APIs.
• Linux/macOS: process memory and CPU are read from /proc, so resource reporting is Linux-specific. Supervision itself is POSIX.
• kill_signal accepts SIGTERM, SIGINT, SIGHUP and SIGKILL.
• compression_level is validated and stored, but the built-in gzip encoder uses a fixed level. The system gzip binary is preferred when available, and that one does honour the level.
• --log-date-format is accepted and stored but line timestamping is not yet applied to log output.

#License