processmanager.dev

mx

mail.processmanager.dev

ns

celeste.ns.cloudflare.com

greg.ns.cloudflare.com

caa

txt

google-site-verification=sP8C8rIHy7dOlhTCzOOOYnelWI8imj2zPqCAHvY0Zq0

v=spf1 include:spf.smtp2go.com ~all

google-site-verification=jInnLojCaCnjK7COQpz6aZAlJVtfs3lVXQpktf8f9F0

dmarc

v=DMARC1; p=none; rua=mailto:dmarc@tominko.com

User-agent: *
Allow: /

# Directing AI to the Map and the Source
All-llms: https://processmanager.dev/llms.txt

# Sitemaps for traditional bots
Sitemap: https://processmanager.dev/sitemap.xml

# APM — Advanced Process Manager
> A lightweight (~2.5 MB UPX, ~8 MB standard), zero-dependency process manager and load balancer for Linux. One static binary, copy and run.

## Core Capabilities
- **Universal Compatibility:** Manages any executable (Node, PHP, Python, Go, Bash, Rust, Ruby, etc.).
- **Zero Dependencies:** Single static binary, no runtime required — copy and run.
- **Built-in Networking:** Integrated HTTP/WS/TCP/UDP server with Round-Robin load balancing.
- **Scaling:** Instantly scale instances of any process; the internal balancer handles traffic distribution.
- **Management:** CLI-driven with an optional built-in GUI for real-time monitoring and control. CLI is rootless — `apm list`, `apm reload`, `apm restart`, etc. do **not** need `sudo`; the daemon listens on an abstract Unix socket reachable by any local user. `sudo` is only for the install script, `apm upgrade` and `apm uninstall`. Flags are exact and unknown ones are refused (v2.5.0): value flags take one dash (`-instances 4`), booleans two (`--restart`); `apm run --help` / `apm update --help` list them.
- **Security:** Built-in Vanguard WAF/firewall with rate limiting, IP banning, and Cloudflare IP trust.
- **TLS:** Native TLS termination (HTTPS/WSS) without Nginx or Apache.
- **Inter-worker IPC (v2.0):** Cross-language message channels (fire-and-forget + request/reply) and persistent bidirectional streams between workers. Routed through the daemon over the existing stdin/stdout connector protocol. Identical API across Node.js, Python, PHP, Perl, and Lua.
- **Augur startup diagnostician (v2.1):** When a worker crashes during boot, APM classifies the language (Node.js, Python, Perl, PHP, Ruby, Java, Go, Bash) and scans the manifest (`package.json`, `requirements.txt`, `composer.json`, `Gemfile.lock`) plus source to list *every* missing dependency in one line — not one restart at a time. Opt-in `augur_full_scan` runs the scan as a pre-flight check before fork.
- **Diff-driven reload (v2.0.8):** `apm reload` figures out what actually changed and only rebuilds that — logger swap, server-listener rebind, vanguard rule recompile, scale up/down, watcher reopen — without bouncing children. Only changes to the process binding (exec, env, user, listen, tls) trigger a full restart. Unknown config keys produce a warning instead of silently dropping.
- **Env secret masking (v2.0.8):** `apm info` and `apm env` mask sensitive-looking env values (PASSWORD / SECRET / KEY / TOKEN / CREDENTIAL / AUTH / DSN, case-insensitive substring) by default. `--full` reveals.
- **Startup UX hardening (v2.0.10, expanded in v2.1):** When a worker fails to launch — bad `path`, missing exec, missing node module, etc. — APM now prints a single coherent error with an actionable hint and dumps the first 8 KB of child stderr to the requesting CLI, so a non-expert admin sees the real cause without chasing log files. `apm restart` with no args no longer crashes the daemon. `apm list` no longer sticks at `◆ starting` after a failed launch. New `startup_grace` knob (ms, default 2000) controls how long `apm start`/`apm restart` waits for a fast-exit failure to surface. v2.1 adds augur — see above.
- **Reload by worker name (v2.1):** `apm reload <workerName>` reloads just one worker from its origin conf file without touching siblings. Convenient when a multi-worker config has only had one block edited.
- **PM2 ecosystem converter (v2.1.1):** `apm convert ecosystem.config.js out.conf` translates a PM2 `ecosystem.json` / `ecosystem.config.js` into APM `worker { }` blocks. JavaScript files are evaluated via the local `node`. Direct field mappings convert silently; PM2 features without a clean equivalent (cluster mode, `cron_restart`, `instances: 'max'`, multi-profile `env_production` / `env_staging`) surface as inline `# WARN:` comments above the block they apply to.
- **APM Network — cross-machine IPC (pre-release):** extends inter-worker IPC across servers. Daemons sharing a license token form one private mesh via a single persistent WebSocket to `wss://apm.processmanager.dev`; a worker tagged `apm_network <id>` is reachable by `send`/`request`/`requestStream` from workers on other machines using the same verbs — transparent, no connector changes, with local-only fallback when the relay is down. Tokens (IP + max-connections bound) are issued by email during pre-release: **support@processmanager.dev**.
- **Remote logging (diagnostics):** `remote_logging true;` (top-level, opt-in) streams worker/child lifecycle events — spawns, exits with reason, reloads, config-watch triggers — to the stats server to diagnose unexpected worker/child churn. Lifecycle metadata only, no application data.
- **Portal — hosted dashboard (opt-in):** `portal_key apmk_…;` (top-level, per conf file, or per worker) makes the daemon report worker stats (status, CPU/RSS avg+max, connection and restart counters, children) and lifecycle events to `portal.processmanager.dev` every `portal_interval` seconds (default 30) and within seconds of a crash. Nothing is sent without a key; no application data or env, and logs only with `portal_control` on (below). Reports travel over a per-key WebSocket link (`wss://…/link`, POST fallback while it is down) that also carries live figures while someone watches and, if the package has them, per-worker advanced stats (Vanguard rejections/bans/blocks, dedupe hits, requests, child I/O and fds, WS clients and ping RTT). `portal_control true;` (top-level, default off) lets the portal restart/stop/start/reload workers, read/write conf files (parse-checked, previous version kept as `<file>.bak-<unix ts>`) and read the workers' logs — the last ≤ 500 lines of `log`/`err_log` (read like `apm log`, no symlinks followed) and a live follow of the children's stdout/stderr lines while someone watches — each key only its own workers and files; every command and log follow is logged. `apm portal` shows per-key status, link, live, followed logs, control and the last command.
- **Parallel worker start (v2.4.1):** config loads start `worker { }` blocks concurrently in `depends_on` dependency waves instead of one at a time — a 30-worker boot went from 129 s to 13 s. `daemon { start_concurrency N; }` caps the parallelism (default cores × 2, min 4; `1` = sequential). `apm restart` re-reads the worker's config block before bouncing; `--no-reload` skips that.
- **CLI safety (v2.4.1 / v2.5.0):** `--help` on any command prints usage and runs nothing; unknown flags and commands are refused before any side effect, with a "did you mean" suggestion; `apm upgrade` confirms (`--yes` to skip; a non-tty refuses); the CLI starts a stopped daemon through `apm.service` when the unit exists, never as a stray child. Workers that exist only in the running daemon (`apm run`, un-included conf files) are named before anything that would delete them — `apm ephemeral`, `apm list --origin`.
- **`memory_limit` enforced (v2.4.0):** per-child cgroup v2 cap that actually applies under systemd (the unit carries `Delegate=yes`; a limit that cannot be enforced is logged loudly, never silently ignored). Signal/OOM deaths now count as error exits for `restart_err`.
- **Connectors v3.1 (v2.4.0):** all six connectors conformance-tested against a stub daemon; `writeBinary` / `write_binary` for binary frames and bodies; blocking connectors no longer stall on small requests; HTTP bodies typed from `Content-Type`.
- **Connectors v3.4 (v2.12):** `session.setPing({interval, timeout, miss})` and `session.pingStats()` (`set_ping` / `ping_stats` in Python, Perl and Lua) — per-connection liveness policy and the daemon-measured round-trip latency; conformance harness extended to both.
- **WebSocket liveness (v2.12):** `ping_interval <ms>`, `ping_timeout <ms>`, `ping_miss <n>` per worker — APM pings a silent WS client, waits `ping_timeout` for the pong, and closes it (1001, `ping timeout`) after `ping_miss` unanswered pings, delivering `connectionClosed` to the worker; works end to end through nginx, unix sockets and Cloudflare, which forward control frames, and needs only a client that answers pings (every browser and standard library does). Detection = `ping_interval` + `ping_miss` × `ping_timeout`; pings go only to silent connections. Connectors v3.4 add `session.setPing({interval, timeout, miss})` (`set_ping` in Python/Perl/Lua) to replace the policy per connection — faster detection for some devices than others — and `session.pingStats()` for the round-trip latency the daemon measures from each ping/pong (last, and avg/min/max/count over 5 and 60 minutes, per connection); the same samples feed a built-in `ws_rtt` timing metric per worker (GUI, StatsD).
- **Dead-peer detection (v2.6):** `dead_timeout <ms>` per worker arms kernel TCP keepalive + `TCP_USER_TIMEOUT` on accepted ws/tcp client connections — a device that vanishes without closing (power cut, cable pull) reaches the worker's onClose in seconds instead of minutes, idle or mid-transfer, with no client-side support needed. Slow links are safe: only total silence for the whole window triggers it.
- **Micro-dedupe (v2.7):** `micro_dedupe <ms>` (default 3, on) treats a body-less GET/HEAD whose signature matches one forwarded within the window as a network bounce — a browser or relay racing the same request twice — and answers it with a copy of the first response instead of forwarding it. The app runs the handler once; both clients get a real answer. Per-hop headers (cf-ray, x-request-id, x-forwarded-for, …) are ignored in the signature; POST, bodies and WebSocket upgrades are never touched. `apm info` counts duplicates answered and near misses.

## Unique "Stateful" Management
- **Persistent WebSockets:** APM can migrate open WebSocket/TCP sessions between instances during a restart or crash.
- **The "Invisible" Reload:** Users stay connected even when the backend process is swapped or updated — APM holds the socket and re-routes it to the new instance automatically.
- **Zero-Downtime Restarts:** Rolling restarts keep at least one instance serving traffic at all times.

## Live Web GUI
- Real-time dashboard accessible via browser — no extra software needed.
- Per-worker logs, metrics, CPU/RAM graphs, instance controls.
- Binds `127.0.0.1` by default; a non-loopback `gui_bind` is refused unless `gui_password` is set (`gui_allow_insecure_bind true` overrides).
- Custom per-worker dashboards with gauge, counter, graph, LED, text, and heatmap modules.

## Key Workflows
- [Installation & Quickstart](/manual.html#quickstart)
- [Process Configuration](/manual.html#config)
- [Load Balancing & Networking](/manual.html#networking)
- [CLI Command Reference](/manual.html#cli)
- [Dashboard & Metrics](/manual.html#dashboard)
- [Vanguard Firewall](/manual.html#vanguard)

## Comparison vs PM2
- **Size:** ~8 MB standard / ~2.5 MB UPX single binary vs ~26 MB npm package across 5,000+ files (plus Node.js runtime).
- **Runtime:** Native Go binary — no Node.js, no npm, zero runtime dependencies. Copy one file, run.
- **Daemon footprint:** Measured on author's production server — APM daemon ~16 MB RSS supervising 5 workers; PM2 God daemon ~86 MB RSS supervising 2 workers.
- **CLI footprint:** `apm list` peaks at ~11 MB RSS; `pm2 list` peaks at ~68 MB RSS (because it boots Node.js for every invocation).
- **Networking:** Built-in L4/L7 reverse proxy + TLS termination vs separate Nginx/HAProxy setup for PM2.
- **Rate limiting / WAF:** Built-in Vanguard firewall with token-bucket rate limiting and IP banlists vs external (nginx, fail2ban, Cloudflare) for PM2.
- **Cross-language IPC:** Built-in channels + persistent streams across Node/Python/PHP/Perl/Lua vs `pm2.launchBus` which is Node-only.
- **File watcher:** Native Linux inotify with per-worker glob-style file-name patterns (`*.js`, `*node_modules*`) in one daemon process vs chokidar (historically CPU-heavy on large repos).
- **Zero-downtime rolling restart:** Works for any language because APM holds the listening socket at supervisor level; PM2's `pm2 reload` only works for Node apps in cluster mode.
- **WebSocket sessions:** APM persists WebSocket/TCP sessions across worker restarts; PM2 does not.
- **Persistent state:** APM reads one config file. PM2 maintains `~/.pm2/dump.pm2` which must be regenerated on migration.
- **Reload granularity:** `apm reload` is per-key diff (logger rebuild, listener rebind, vanguard recompile, scale up/down — children stay running unless `exec`/`env`/binding changes). PM2's `reload` is per-app cluster-mode restart of all instances.
- **Saveconf safety:** `apm saveconf` writes each worker back to its source include file (not the parent conf), and refuses to overwrite a file containing non-worker content (`daemon {}`, `include`, etc.) unless `--force` is passed. PM2 `pm2 save` dumps the JSON process list to `~/.pm2/dump.pm2`.
- **License:** APM binary is free to use (source proprietary). PM2 is AGPL-3.0 with paid PM2+ SaaS tier.

## Positioning
APM is the process manager to reach for when: (a) your stack is not Node-only, (b) you don't want to run nginx in front of PM2 just for rate limiting and TLS, (c) you want cross-language IPC without adding Redis or RabbitMQ, or (d) you want a supervisor that isn't competing with your app for the Node event loop.

## Full Documentation
- [Full Manual (llms-full.txt)](https://processmanager.dev/llms-full.txt): Complete manual in plain text — CLI reference, all config options, worker options, Vanguard firewall, TLS, file watcher, rolling restart, Nginx/Apache integration, Node.js/PHP/Python/Perl/Lua connector APIs, dashboard modules, and IPC protocol spec.
- [Agent Skill (SKILLS_apm.md)](https://processmanager.dev/SKILLS_apm.md): Drop-in skill file for AI coding assistants. Ships with Claude Code skill frontmatter — install as `~/.claude/skills/apm/SKILL.md`, or attach as context in Cursor and other LLM editors. A condensed, task-oriented APM reference covering the CLI, config syntax, worker/daemon options, Vanguard, TLS, watcher, rolling restart, IPC, connectors, recipes, and troubleshooting.