Overview

APM is Tom's Advanced Process Manager for Linux. One binary, copy and run — no config files required to get started. Complexity is APM's problem, not yours.

APM runs as a background daemon and manages worker processes. You interact with it through the apm CLI. The daemon auto-starts the first time you run any apm command.

Architecture

The daemon communicates with the CLI via an abstract Unix socket. Workers are child processes managed by the daemon. Each worker can have multiple parallel instances. The built-in reverse proxy routes incoming connections across instances using round-robin.

  CLI  ──(unix socket)──  Daemon  ──  Worker [4 instances]
                                  └──  Worker [1 instance]
                                  └──  GUI server (port 6789)

Philosophy

• Zero config to start — defaults are correct for 90% of cases
• CLI-first, config files for persistence and power users
• Every error message answers "what do I do now"
• Never crash on a bad optional field — warn and continue
• Linux only. Windows is not supported.

Installation

Run the install script as root. It downloads the right binary for your architecture, sets up the system group and log file, installs the init service, and starts the daemon.

# One-liner install
$ curl -fsSL https://processmanager.dev/install.sh | sudo bash

# Or download first, review, then run
$ curl -fsSL https://processmanager.dev/install.sh -o install.sh
$ sudo bash install.sh

# Verify
$ apm --version

The installer sets up:

• /usr/sbin/apm — binary
• /var/log/apm.log — daemon log (group-readable by apm)
• /etc/apm/apm.conf — default config (created if absent)
• apm OS group — add users with usermod -aG apm <user>
• Startup service (systemd, OpenRC, or SysV — auto-detected)

The daemon auto-loads /etc/apm/apm.conf at startup — no separate boot step required.

Run as a systemd service

The installer registers APM with your init system automatically. The service runs the daemon at boot, supervised by systemd.

# Check status
$ systemctl status apm

# View logs
$ journalctl -u apm -f

Uninstall

# Remove binary and config
$ sudo apm uninstall

# Remove everything including logs, group, service
$ sudo apm uninstall --purge

Command reference

All commands communicate with the running daemon. If no daemon is running, APM starts one automatically.

apm [command] [options]

Process commands

Config commands

GUI & Monitor commands

Daemon commands

Run flags

Flags for apm run and apm update. The same options are available as config file fields (see Worker options).

# Start a worker from the CLI — no config file needed
$ apm run node server.js \
    --name        myapp \
    --instances   4 \
    --server      http://0.0.0.0:3000 \
    --watch       "*.js" \
    --restart                # restart on clean exit
    --rolling                # rolling restart mode

# Update a running worker's instance count without restarting
$ apm update myapp --instances 8 --no-restart

# Save it back to a conf file
$ apm saveconf myapp /etc/apm/apm.conf.d/myapp.conf

Config file

Config files define workers and daemon settings. They're loaded with apm load or apm reload. The system config path is /etc/apm/apm.conf.

Syntax

• Key-value pairs end with ;
• Blocks use { }
• Comments: # or // to end of line
• Strings: unquoted, or single/double/backtick quoted (quotes are stripped)
• Multiple values: comma-separated on one line, or repeat the key
• The : suffix on keys is optional
• include <glob>; inlines another file at parse position

# Simple worker
worker {
    name       myapp;
    exec       node;
    params     server.js;
    instances  4;
    restart    true;
    watch      *.js;
    server     http://0.0.0.0:3000;
}

Config hierarchy

APM's startup scripts call apm boot after the daemon starts, which loads /etc/apm/apm.conf. The main config is typically structured as:

1. /etc/apm/apm.conf — main config (daemon block + includes)
2. /etc/apm/apm.conf.d/*.conf — drop-in worker configs, sorted by filename

You can also load configs manually at any time with apm load <file> or do a live diff with apm reload <file>.

daemon {
    gui_port  6789;
    log       /var/log/apm/apm.log;
}

# Load drop-in worker configs
include apm.conf.d/*.conf;

worker {
    name  portal;
    exec  node;
    params app.js;
}

Multiple values

# Comma-separated on one line
server  http://0.0.0.0:3000, ws://0.0.0.0:3001;

# Or repeat the key
ban_path  *.php;
ban_path  *wp-*;
ban_path  *.env;

Worker options

All options are available both as CLI flags to apm start and as fields in a worker { } config block.

Identity

Environment

Restart on clean exit

Restart on error exit

Shutdown

Logging

Proxy / HTTP

File watcher

Rolling restart

Stats

Crash webhook (on_crash)

APM can POST a JSON payload (or send a GET request) to a URL of your choice whenever a child process crashes — i.e. exits with a non-zero code or is killed by a signal. Intentional stops (apm stop) are never reported.

worker {
    name  myapp;
    cmd   node server.js;

    on_crash {
        url         https://hooks.example.com/apm-crash;
        method      POST;           # POST (default) or GET
        debounce    10000;          # min ms between calls (floor: 5000)
        log_lines   20;             # tail lines to include in payload
        log_source  err;            # "err" (default) or "out"
        secret      mysecret;       # signs payload with HMAC-SHA256
    }
}

Request headers

POST payload

{
  "worker":         "myapp",
  "instance":       1,
  "exit_code":      1,
  "exit_signal":    "SIGKILL",   // omitted if process exited normally
  "runtime_ms":     4821,
  "error_restarts": 3,
  "timestamp":      "2025-06-01T12:00:00Z",
  "log":            "Error: cannot connect to DB\n..."  // omitted if log_lines = 0
}

Daemon config

Global APM settings live in a top-level daemon { } block. No daemon block = all defaults. Zero config still works.

daemon {
    allow_group    apm-admin;     # OS group allowed to use apm CLI
    default_user   www-data;      # fallback user for workers without user=
    log            /var/log/apm/apm.log;
    gui_port       6789;           # 0 = disabled
    gui_bind       127.0.0.1;
    gui_password   secret;
    gui_rate_limit 20;             # failed auth attempts/min before ban
    telemetry      true;           # hourly anonymous ping (opt-out with false)
}

Server types

APM's built-in proxy accepts connections and forwards them to worker instances via IPC. Specify servers with the server field. Multiple servers per worker are supported.

worker {
    name    api;
    exec    node;
    params  api.js;

    # HTTP and WebSocket on separate ports
    server  http://0.0.0.0:3000;
    server  ws://0.0.0.0:3001;

    # Or combined on one line
    server  http://0.0.0.0:3000, ws://0.0.0.0:3001;
}

Client IP resolution

When behind a CDN or reverse proxy (e.g. nginx), enable trust_proxy so APM resolves the real client IP from X-Forwarded-For headers. This affects Vanguard rate limiting and ban decisions.

trust_proxy  true;

Vanguard

Vanguard is APM's built-in request firewall. It runs before worker IPC — rejected connections never reach your app. Configure it with a vanguard { } sub-block inside a worker.

worker {
    name    api;
    exec    node;
    params  api.js;
    server  http://0.0.0.0:3000;

    vanguard {
        rate_limit    100;          # requests/sec per IP
        rate_burst    200;          # burst capacity
        ban_ttl       300000;       # auto-ban for 5 minutes
        ban_path      *.php, *wp-*, *.env, /.git*;
        ban_response  Forbidden;
    }
}

IP filtering

Path banning

ban_path  *.php;          # ends-with  — block all .php requests
ban_path  *wp-*;          # contains   — block WordPress probes
ban_path  /.git*;         # starts-with — block .git exposure
ban_path  *.env;          # ends-with  — block .env file reads
ban_path  /admin/login;   # exact match — block a specific path

Rate limiting

Rate-limited requests receive 429 Too Many Requests. Path/IP bans return 403 Forbidden (or silent TCP RST).

CDN IP lists

APM's installer fetches Cloudflare's published egress IP ranges and writes them to /etc/apm/ips/ as ready-to-include partial configs. Include them inside a vanguard { } block to restrict direct access to CDN traffic only.

vanguard {
    # Only allow Cloudflare egress IPs (IPv4 + IPv6)
    include /etc/apm/ips/cloudflare-v4.part;
    include /etc/apm/ips/cloudflare-v6.part;

    rate_limit  500;
    ban_path    *.php, *wp-*, *.env, /.git*;
}

The IP lists are re-fetched automatically on every apm install or upgrade. To refresh them manually:

$ sudo apm install  # re-runs the full installer, including IP fetch

TLS

APM has first-class TLS support for all server types — HTTP, WebSocket, and TCP. Bring your own certificates.

worker {
    name      api;
    exec      node;
    params    api.js;
    server    https://0.0.0.0:443;

    tls       true;
    tls_cert  /etc/ssl/certs/myapp.crt;
    tls_key   /etc/ssl/private/myapp.key;
    # tls_ca for mutual TLS (client cert verification)
    tls_ca    /etc/ssl/certs/ca.crt;
}

File watcher

The file watcher monitors your source directory and triggers a worker restart when matching files change. Uses kernel file-watch events (inotify) — no polling.

worker {
    name          api;
    exec          node;
    params        server.js;
    path          /home/user/myapp;

    watch         *.js, *.json;        # watch .js and .json files
    watch_ignore  *node_modules*;      # ignore anything inside node_modules
    watch_delay   200;                  # 200ms debounce
}

Pattern syntax

Watch patterns use a simple glob-style syntax — no regex needed. Four matching modes:

# Go source files, excluding generated code and vendor
watch         *.go;
watch_ignore  *_generated.go, *vendor*;

# JS/TS project — watch src/, ignore build output and deps
watch         *.js, *.ts, *.json;
watch_ignore  *node_modules*, *dist/*;

# Python — any .py file anywhere under path
watch         *.py;
watch_ignore  *__pycache__*;

Rolling restart

Rolling restarts cycle through instances one at a time, keeping the rest running to serve traffic. Zero downtime for multi-instance workers.

worker {
    instances     4;
    rolling       true;
    rolling_delay 1000;  # 1s between each instance restart
}

With session_persist true, open connections are migrated to a new instance before the old one is killed. Use session_wait to control how long APM waits for the new instance to become ready.

rolling          true;
rolling_delay    500;
session_persist  true;
session_wait     2000;  # wait up to 2s for new instance

Logger

APM has a built-in logger for each worker. Every line written to a child process's stdout or stderr is intercepted, prefixed with a timestamp and worker name, and written to the configured destination. Coloring is applied by APM before writing — use strip_ansi to remove it when logging to files.

Destinations

Prefix

Each log line is prefixed with the worker name (or a custom string). The prefix field supports the color syntax described below. APM automatically appends the instance number in multi-instance workers:

worker {
    name    api;
    exec    node;
    params  server.js;

    # cyan name, reset after — instance # is appended automatically
    prefix  ç51-api-serverçR-;

    log     /var/log/myapp/out.log;
    err_log /var/log/myapp/err.log;
}

For a worker with instances 3, the stdout prefix becomes api-server#1, api-server#2, api-server#3 — each in a distinct color so instances are visually distinct in the live GUI and in log files.

Timestamp format

The timestamp prepended to each line is controlled by log_time_format. The format string uses strftime-style tokens and supports color escapes. The default is ç214-%Y-%m-%d %Tç59-.%FçR- (orange date, dim fractional seconds).

Strftime tokens

# Default — orange date, dim microseconds
log_time_format  ç214-%Y-%m-%d %Tç59-.%FçR-;

# Compact — just HH:MM:SS in gray
log_time_format  ç59-%TçR-;

# No color — plain ISO timestamp
log_time_format  %Y-%m-%d %T;

Strip ANSI

Color syntax — çN-

APM uses a compact color escape based on the 256-color terminal palette. The ç character (U+00E7) acts as the escape marker. This syntax works in prefix, log_time_format, and anywhere APM renders text to the terminal or log files.

# Foreground only
prefix  ç82-myappçR-;      # bright green name
prefix  ç196-myappçR-;     # bright red name
prefix  ç214-myappçR-;     # orange name

# Foreground + background
prefix  ç15,88-ERRORçR-;    # white text on dark red background

# Bold foreground
prefix  ç51,0,1-myappçR-;   # bold cyan

Useful color reference

StatsD

Web GUI

APM ships a built-in real-time web dashboard. Enable it with gui_port in the daemon config:

daemon {
    gui_port  6789;         # 0 = disabled (default)
    gui_bind  127.0.0.1;   # use 0.0.0.0 to expose on the network
}

When the daemon starts with the GUI enabled it prints the access URL:

$ apm start
GUI: http://127.0.0.1:6789/

Views

Server Info — latency

The Server Info page has a Latency section with two cards:

Disconnect behaviour

When the daemon stops, the WebSocket closes and the GUI immediately dims with a Session Ended overlay. Click Refresh Page to reconnect.

Dashboard

Each worker can expose a custom metric dashboard in the GUI. Define a dashboard { } block inside a worker config to create one. The dashboard is shown in the Dashboard tab when that worker is selected.

worker my-api {
    exec    node;
    params  server.js;
    server  http://127.0.0.1:3000;

    dashboard {
        name  My API;
        cols  6;
        rows  4;

        module {
            type  graph;
            id    1;
            name  Requests/sec;
            x 0; y 0; w 3; h 1;
        }
        module {
            type  gauge;
            id    2;
            name  CPU %;
            x 3; y 0; w 1; h 1;
            min 0; max 100; unit %;
        }
        module {
            type  counter;
            id    3;
            name  Total errors;
            x 4; y 0; w 1; h 1;
        }
        module {
            type  text;
            id    4;
            name  Last error;
            x 5; y 0; w 1; h 1;
        }
    }
}

Dashboard block fields

Module fields

Module types

Sending metrics from code

Use apm.setDashValue(id, value, color?) in the Node.js connector to push a value to a dashboard module. This is distinct from apm.metric(), which is for StatsD-style system metrics only.

const ApmModule = require('./apm_module.node.js')
const apm = new ApmModule(async (session) => { /* handle connections */ })

// Push a number to module id 1 (graph)
apm.setDashValue(1, requestsPerSecond)

// Push a number with a dynamic color
apm.setDashValue(2, cpuPercent, cpuPercent > 80 ? '#ff5a5a' : '#4f8cff')

// Push a string to a text module (id 4)
apm.setDashValue(4, lastErrorMessage)

// LED on/off (1 = on, 0 = off)
apm.setDashValue(5, isHealthy ? 1 : 0, isHealthy ? '#47d16c' : '#ff5a5a')

Counter vs gauge vs graph

Node.js connector

The Node.js connector (apm_module.node.js) provides a session API for APM-managed Node.js processes. IPC happens over stdin/stdout using binary frames — no Unix sockets required in the child.

$ curl -fsSL https://processmanager.dev/connectors/apm_module.node.js -o apm_module.node.js

$ node apm_module.node.js -update

const ApmModule = require('./apm_module.node.js')
const apm = new ApmModule(async (session) => {
    // session.protocol  — 'http' | 'ws' | 'tcp'
    // session.method    — HTTP method
    // session.path      — full path + query
    // session.headers   — request headers
    // session.remoteIp  — real client IP (proxy-aware)
    // session.cookies   — parsed cookie map

    session.write('Hello World', {
        'content-type': 'text/plain',
        'x-status': '200'
    })
    session.close()
})

If your worker doesn't handle sessions (e.g. a background job pushing dashboard metrics), pass an empty async function: new ApmModule(async () => {}).

Session API

Instance methods

Environment variables

APM injects the following into managed child processes:

WebSocket example

const ApmModule = require('./apm_module.node.js')
const apm = new ApmModule(async (session) => {
    if (session.protocol !== 'ws') {
        session.close(400)
        return
    }

    session.onData = (data, isBinary) => {
        // echo back
        session.write(data)
    }

    session.onClose = () => {
        console.log('disconnected', session.sessionId)
    }
})

PHP / Python / Perl / Lua connectors

Connectors for other languages follow the same pattern: drop a single file into your project, require / include it, and pass an onConnect callback. All connectors implement the full APM IPC protocol over stdin/stdout — no extra dependencies beyond what's noted on the connectors page.

$ curl -fsSL https://processmanager.dev/connectors/apm_module.php   -o apm_module.php
$ curl -fsSL https://processmanager.dev/connectors/apm_module.py    -o apm_module.py
$ curl -fsSL https://processmanager.dev/connectors/ApmModule.pm     -o ApmModule.pm
$ curl -fsSL https://processmanager.dev/connectors/apm_module.lua   -o apm_module.lua

Each connector file also supports self-update — run it with -update to fetch the latest version from the server (e.g. php apm_module.php -update). See the connectors page for version info, MD5 checksums, and per-language update commands.

All connectors expose the same setDashValue(id, value, color?) and metric(name, value, type?) methods as the Node.js connector. Refer to the Dashboard section for how to define dashboard modules in the config and push values to them.

What's new in v1.3.0

Improvement — Config reload syncs all worker parameters

apm reload previously only applied exec, path, params, and instances to a running worker. All other fields (watcher patterns, restart settings, rolling delay, kill timeout, TLS, session, proxy flags, etc.) were silently ignored — the old values stayed active until the worker was fully stopped and restarted.

All fields are now applied live before the rolling restart. The file watcher is additionally closed and reopened if watch, watch_ignore, or watch_delay changed, so the new patterns take effect immediately without a full stop/start.

Bug fix — watch_ignore with multiple patterns

Config values with multiple comma-separated entries (e.g. watch_ignore web_*, node_modules) are stored internally as a string list. A type mismatch caused watch_ignore to be silently discarded when more than one pattern was given — all matching files would trigger a restart, including those in excluded directories. This is now fixed: all patterns are passed through correctly.

Bug fix — Orphaned processes on rapid file changes

When multiple file-change events fired in quick succession, the debounce timer could start a second WatcherRestart goroutine while the first was still running. Both goroutines would wait for the child to exit, then both call Start() — spawning two processes for the same slot and orphaning the first. This is now prevented with a per-worker mutex that serialises concurrent watcher-triggered restarts.