# 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 `apm install` / `apm uninstall`.
- **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.

## 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.
- Optional password protection (`gui_password` in the daemon config block).
- 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 regex 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.