#pm3

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

#Highlights

• Any executable. pm3 supervises an arbitrary command line, and resolves interpreters the way PM2 does — .js through node, .py through python, binaries directly — with --interpreter and --interpreter-args to pin either. See Interpreters.
• Crash recovery. Automatic restarts with min_uptime / unstable-restart tracking, restart budgets, restart delays, stop_exit_codes and max_memory_restart.
• PM2's look. list, describe and logs use PM2's colors, table borders, log prefixes and --help layout, so the two tools read the same — see Terminal colors.
• 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

# From the MoonBit package registry, if the MoonBit toolchain is already
# installed. Builds from source and installs `pm3` to ~/.moon/bin.
moon install kupas/pm3/cmd/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/pm3/pm3.exe

moon build --target native
./_build/native/debug/build/cmd/pm3/pm3.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

# The extension already picks the interpreter (.js -> node); arguments for
# the interpreter itself go before the script, as PM2 places them.
pm3 start ./app.js --interpreter-args "--trace-warnings --max-old-space-size=512"

# 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. The columns are PM2's — id, name, namespace, version, mode, pid,
# uptime, restarts (↺), status, cpu, mem, user, watching — and the footer
# totals the running processes.
pm3 list
# ┌────┬────────┬───────────┬─────────┬──────┬──────┬────────┬───┬────────┬───────┬────────┬──────┬──────────┐
# │ id │ name   │ namespace │ version │ mode │ pid  │ uptime │ ↺ │ status │ cpu   │ mem    │ user │ watching │
# ├────┼────────┼───────────┼─────────┼──────┼──────┼────────┼───┼────────┼───────┼────────┼──────┼──────────┤
# │ 0  │ digest │ default   │ N/A     │ fork │ 4242 │ 6s     │ 0 │ online │ 86.9% │ 11.3mb │ root │ disabled │
# │ 1  │ worker │ default   │ 2.5.1   │ fork │ 4243 │ 6s     │ 0 │ online │ 0%    │ 2.0mb  │ root │ disabled │
# └────┴────────┴───────────┴─────────┴──────┴──────┴────────┴───┴────────┴───────┴────────┴──────┴──────────┘
#
# 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

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

#Interpreters

1. An explicit --interpreter <cmd> (or interpreter = "..." in a config file) wins.
2. Otherwise the extension picks the interpreter, from PM2's map: .js → node, .py → python, .sh → bash, .rb → ruby, .php → php, .pl → perl, .coffee → coffee, .ls → lsc, .ts / .tsx → bun.
3. Otherwise a binary runs directly (shown as <none> in pm3 describe), and any other file — a text file with no extension — is handed to node, the way PM2 falls back to its own runtime.

$ pm3 start ./worker.rb
Interpreter ruby is NOT AVAILABLE in PATH. (type 'which ruby' to double check.)

pm3 start ./app.js --interpreter-args "--trace-warnings --max-old-space-size=512"

interpreter_args = "--trace-warnings --max-old-space-size=512"   # split like a shell
interpreter_args = ["--trace-warnings", "--max-old-space-size=512"]

#Commands

#start options

#Terminal colors

#Exit status

#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. (A file deliberately named <base>__<something>.log does match the pattern — the stamp is not required to be a date — so keep unrelated files out of the log directory.)
• 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.
• The daemon's own pm3.log rotates under the same policy, as pm2-logrotate rotates pm2.log. Matching PM2's split: the size rule applies to it, the cron trigger and reloadLogs apply to application logs only, and pm3 flush truncates it alongside them.

#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
rotate_interval = "0 3 * * *"
tz = "UTC+8"

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

#Process lifecycle

• Stop sends kill_signal (default SIGINT, PM2's KILL_SIGNAL), 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.
• pm3 resurrect resolves each record the way pm3 start does before running it — an older pm3 could leave a record without an interpreter, which would otherwise be executed directly and fail without explanation — and reports a record it cannot resolve instead of dropping it.
• A daemon left over from another build announces itself before the next command runs, with PM2's out-of-date warning; pm3 update is the fix it points at: save the list, kill the daemon, launch this build, resurrect.
• Records written by an older pm3 (including a dump from before a field existed) are read with the missing values filled in, so upgrading never empties the process list over one missing key.

#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 writes at a fixed level, so the level only documents intent.

#License