pm2-forwarder

A tiny, zero-config REST API that forwards PM2 process control over HTTP. Point it at your local PM2 daemon and list, inspect, restart, stop, reload, or delete processes with plain HTTP requests.

npx pm2-forwarder
# pm2-forwarder v0.1.0 → http://127.0.0.1:9616  (auth: disabled)

Quick start

PM2 plugin (recommended)

Run it as a managed PM2 module — it starts in the background and on boot:

pm2 install pm2-forwarder

NPX

Run it directly with no install, or install globally for a persistent command:

npx pm2-forwarder
# or: npm install -g pm2-forwarder && pm2-forwarder

Library

import { createApp, startServer } from "pm2-forwarder";

// Start a server (connects to PM2, installs signal handlers):
await startServer({ port: 9616, host: "127.0.0.1", token: "secret" });

// Or get just the Hono app to mount/test yourself:
const app = createApp({ token: "secret" });
const res = await app.fetch(new Request("http://localhost/health"));

Requirements

• Node.js >= 18
• PM2 installed and running. The forwarder talks to your local PM2 daemon; if the daemon isn't up yet, PM2 starts it automatically on first connect.

Configuration

Every option has a flag and an environment variable. Precedence is flag > PM2_FORWARDER_* env > generic PORT > default.

| Setting | Flag | Env | Default | | --- | --- | --- | --- | | Port | -p, --port | PM2_FORWARDER_PORT, then PORT | 9616 | | Host | -H, --host | PM2_FORWARDER_HOST | 127.0.0.1 | | Token | -t, --token | PM2_FORWARDER_TOKEN | (unset → no auth) | | Tunnel | --tunnel | PM2_FORWARDER_TUNNEL | (off) | | CF token | --cf-token | CLOUDFLARED_TOKEN, then PM2_FORWARDER_CF_TOKEN | (unset) |

pm2-forwarder --port 8080
PM2_FORWARDER_PORT=8080 pm2-forwarder

When installed as a PM2 module, configure it with pm2 set (then restart it):

pm2 set pm2-forwarder:PM2_FORWARDER_PORT 8080
pm2 set pm2-forwarder:PM2_FORWARDER_TOKEN "$(openssl rand -hex 16)"
pm2 restart pm2-forwarder

Security

The API can stop and delete processes and has no auth by default, so:

• It binds to 127.0.0.1 (localhost only) by default. Use --host 0.0.0.0 to expose it on your network — but only together with --token.

• Set a bearer token to require Authorization: Bearer <token> on every route:

  pm2-forwarder --token "$(openssl rand -hex 16)"

• There is no built-in TLS. To reach it over an untrusted network, put it behind a reverse proxy that terminates HTTPS.

Hosting at home or don't want to expose your ports?

Running PM2 on a box behind your home router, a NAT, or CGNAT — or just don't want to open a port on your firewall? pm2-forwarder can reach the public internet for you through a Cloudflare Tunnel: an outbound-only connection, so there's no port forwarding, no inbound firewall rule, and no public IP required. The cloudflared binary is fetched automatically on first use.

Because a tunnel makes the process-control API reachable publicly, if you enable a tunnel without --token, a random bearer token is generated, required, and printed — so the public URL is never left open. Pass your own --token to choose it.

Guest tunnel — no Cloudflare account, gives an ephemeral https://<random>.trycloudflare.com URL:

pm2-forwarder --tunnel
# Cloudflare tunnel (guest) → https://abc-def-ghi.trycloudflare.com
# Auth token (required on every request — auto-generated):
#   <printed token>

Authenticated named tunnel — pass a Cloudflare tunnel token (same one you'd use with cloudflared tunnel run --token):

pm2-forwarder --cf-token "$CLOUDFLARED_TOKEN"
# or: CLOUDFLARED_TOKEN=... pm2-forwarder

For a named tunnel the public hostname → origin mapping lives in the Cloudflare Zero Trust dashboard; point its ingress at http://localhost:9616 (or whatever --port you use). A CF token implies --tunnel, so you don't need both.

Live log streaming (GET /processes/:id/logs/stream, SSE) works locally and over named tunnels, but not over guest trycloudflare.com tunnels, which don't support Server-Sent Events.

API

All responses are JSON: { "data": ... } on success, { "error": "..." } on failure. Examples assume the default http://127.0.0.1:9616.

# Liveness — does not touch PM2
curl http://127.0.0.1:9616/health

# Dashboard rollup — counts by status, total cpu/memory, pm2 version
curl http://127.0.0.1:9616/summary

# List all processes
curl http://127.0.0.1:9616/processes

# Describe one process (by name or pm_id)
curl http://127.0.0.1:9616/processes/api
curl http://127.0.0.1:9616/processes/0

# Tail logs (last 200 lines of stdout+stderr by default)
curl "http://127.0.0.1:9616/processes/api/logs?lines=100&type=err"

# Stream logs live as Server-Sent Events (Ctrl-C to stop)
curl -N "http://127.0.0.1:9616/processes/api/logs/stream"

# Control a process
curl -X POST   http://127.0.0.1:9616/processes/api/restart
curl -X POST   http://127.0.0.1:9616/processes/api/stop
curl -X POST   http://127.0.0.1:9616/processes/api/reload
curl -X DELETE http://127.0.0.1:9616/processes/api

# Restart re-reading environment variables
curl -X POST http://127.0.0.1:9616/processes/api/restart \
  -H 'content-type: application/json' -d '{"updateEnv":true}'

# Scale a cluster app, send a signal, flush logs, reset counters
curl -X POST http://127.0.0.1:9616/processes/api/scale  -H 'content-type: application/json' -d '{"instances":4}'
curl -X POST http://127.0.0.1:9616/processes/api/signal -H 'content-type: application/json' -d '{"signal":"SIGUSR2"}'
curl -X POST http://127.0.0.1:9616/processes/api/flush
curl -X POST http://127.0.0.1:9616/processes/api/reset

# Save the current process list / restore it later (survives reboot)
curl -X POST http://127.0.0.1:9616/dump
curl -X POST http://127.0.0.1:9616/resurrect

# Apply any action to every process with the "all" target
curl -X POST http://127.0.0.1:9616/processes/all/restart

# With auth enabled (--token secret123)
curl -H "Authorization: Bearer secret123" http://127.0.0.1:9616/processes

| Method | Path | Description | Codes | | --- | --- | --- | --- | | GET | / and /health | Service info / liveness | 200 | | GET | /summary | Counts by status, total cpu/memory, pm2 version | 200, 500 | | GET | /processes | List processes with status, cpu, memory, uptime, restarts | 200, 500 | | GET | /processes/:id | Describe one process by name or pm_id | 200, 404, 500 | | GET | /processes/:id/logs | Tail stdout/stderr — ?lines= (1–5000), ?type=out\|err\|all | 200, 404, 500 | | GET | /processes/:id/logs/stream | Live logs via SSE — ?type=out\|err\|all; events out/err/ping | 200, 404, 500 | | POST | /processes/:name/restart | Restart — optional body {"updateEnv":true} | 200, 404, 500 | | POST | /processes/:name/stop | Stop | 200, 404, 500 | | POST | /processes/:name/reload | Reload (zero-downtime) — optional {"updateEnv":true} | 200, 404, 500 | | POST | /processes/:name/scale | Scale a cluster app — body {"instances":<int>} | 200, 400, 404, 500 | | POST | /processes/:name/signal | Send a signal — body {"signal":"SIGUSR2"} | 200, 400, 404, 500 | | POST | /processes/:name/flush | Clear the process's log files | 200, 404, 500 | | POST | /processes/:name/reset | Reset restart counters/metadata | 200, 404, 500 | | DELETE | /processes/:name | Delete from PM2 | 200, 404, 500 | | POST | /dump | Save the process list (persists across reboot) | 200, 500 | | POST | /resurrect | Restore the process list saved by /dump | 200, 500 |

The :name control routes also accept all to target every process (e.g. POST /processes/all/restart). When a token is configured, any request without a valid Authorization: Bearer <token> header gets 401.

License

MIT