User Guide · v1.6.0

Master every screen in EZ PM2 GUI

A visual walkthrough of every page — Processes, Monitoring, Remote Servers, Deploy, Modules, Ecosystem, Cluster, Cron Jobs, Load Balancing, Logs and Settings — with annotated screenshots.

Get Started View on GitHub

Getting Started

Installation

EZ PM2 GUI requires Node.js 18+ and PM2 installed globally. Install both with:

# Install PM2 globally (skip if already installed)
npm install -g pm2

# Install EZ PM2 GUI globally
npm install -g ezpm2gui
On Linux/macOS, prefix with sudo if you get a permission error, or configure npm to use a user-writable directory.

First Launch

1

Start the GUI server

Run ezpm2gui from any terminal. The server starts on port 3101 by default.

2

Open the dashboard

Navigate to http://localhost:3101 in your browser.

3

Unlock with your PIN or password

On first use, set a 4-digit PIN or password. Every subsequent launch starts at the lock screen below.

Lock Screen

When you open the dashboard, the lock screen appears first. Choose between a 4-digit PIN keypad or password entry — PIN auto-submits once all four digits are entered. The app auto-locks after an idle period (default 5 minutes — configurable in Settings → Security).

localhost:3101 — Lock screen
EZ PM2 GUI lock screen with PIN keypad
Lock screen — PIN keypad with optional password fallback.

Processes (Dashboard)

The default landing page shows system health and every PM2 process at a glance.

localhost:3101/processes
Process Dashboard showing system metrics and empty process list
Process Dashboard — system metrics on the left, process list on the right.
⏱️

Uptime

Host uptime since boot, formatted as days/hours/minutes.

📈

Load Average

Classic 1 / 5 / 15-minute load averages from the OS.

🧠

Memory

Used vs. total host memory with a live progress bar.

⚙️

CPU Cores

Detected logical CPU count — useful when sizing cluster mode.

  • Search bar — filter processes by name or ID as you type.
  • All Processes dropdown — narrow by status or namespace.
  • Active / total counter — top-right summary of online vs. stopped.
  • Each process card shows status, CPU %, memory, uptime, restarts, and action buttons.

Monitoring

Real-time CPU, memory, and uptime per process. All values update live via WebSocket — no manual refresh required.

localhost:3101/monit
Process Monitor showing total, online, CPU peak and memory peak cards
Process Monitor — aggregate cards above a sortable per-process table.
  • Total / Online — count of registered and running processes.
  • CPU Peak — highest CPU-consuming process right now.
  • Memory Peak — highest RSS with the process name labelled below.
  • Sortable table — click any column header to sort by ID, Name, Status, CPU, Memory, Uptime, or Restarts.
  • Refresh icon — force an immediate poll (top-right).
CPU usage above 80% turns the bar red; 60–80% shows orange. Memory thresholds follow the same colour pattern.

Remote Servers

Manage PM2 instances on other machines over SSH — no agent installation needed on the remote side, just PM2 and SSH access.

localhost:3101/remote
Remote Servers page for managing SSH-connected PM2 hosts
Remote Servers — add, edit and test SSH connections to remote PM2 hosts.
FieldNotes
NameFriendly label shown in the top-bar server switcher
HostIP address or hostname of the remote server
PortSSH port (default: 22)
UsernameSSH user — must have PM2 access
Auth typePassword or private key (PEM format)
Passwords are encrypted at rest using AES-256-GCM before being saved. Private keys are never stored — only referenced by path.
PM2 must be installed on the remote machine and reachable in the SSH user's PATH. Use the built-in Install PM2 button if detection fails.

Deploy App

Start a new PM2-managed process from a structured form — no terminal needed.

localhost:3101/deploy
Deploy Application form with Basic Info, Runtime and Environment Variables sections
Deploy Application — Basic Info, Runtime and Environment Variables panels.
1

Fill in Basic Info

Choose the app type (Node.js, Python, Bash, .NET…), name, namespace, entry file, and optional working directory.

2

Configure Runtime

Set instance count, exec mode (Fork / Cluster), memory cap and port. Toggle Auto Restart, Watch for Changes, or Auto Setup on Deploy as needed.

3

Add environment variables

Use the key / value inputs to add one variable at a time — press Add or Enter.

4

Click Deploy

The process starts under PM2 and appears immediately on the Processes page.

PM2 Modules

Install and manage official and community PM2 modules (equivalent to pm2 install <module>).

localhost:3101/modules
PM2 Modules management page
PM2 Modules — browse, install and configure modules like pm2-logrotate.
  • Browse popular modules (pm2-logrotate, pm2-server-monit, pm2-auto-pull, etc.).
  • Install / uninstall / enable / disable modules with a single click.
  • Edit module configuration inline — changes apply without restarting PM2.

Ecosystem Config

Edit, preview and generate your ecosystem.config.js file from a structured editor.

localhost:3101/ecosystem
Ecosystem Config generator and editor
Ecosystem Config — form-driven editor with live file preview.
  • Visual editor for the apps array — add, remove and reorder entries.
  • Deploy section for staging and production targets (host, user, ref, post-deploy hooks).
  • Export to disk, copy to clipboard, or generate a sample skeleton.
You can also generate a starter ecosystem file from the CLI: ezpm2gui-generate-ecosystem.

Cluster

Scale a single app across multiple CPU cores with zero-downtime reloads.

localhost:3101/cluster
Cluster Management page
Cluster Management — scale instance count and switch between fork and cluster mode.
  • Pick an app, then slide the instance count up or down.
  • Switch Exec Mode between Fork and Cluster.
  • View per-instance CPU/memory breakdown for the selected app.
  • Use Reload for rolling, zero-downtime restarts.

Cron Jobs

Schedule recurring tasks without editing crontab — jobs are stored and executed by the EZ PM2 GUI server.

localhost:3101/cron-jobs
Cron Jobs page with two example jobs
Cron Jobs — schedule counters at the top, enable/disable toggles on each row.
🕐

Schedule

Standard 5-field cron expressions (seconds-precision supported).

💻

Command types

Shell, Node.js, Python, and .NET executables.

📋

Run log

Exit code, stdout and stderr saved per execution for review.

Cron jobs run as the same OS user as the EZ PM2 GUI server. Ensure that user has permission to execute the configured commands.

Load Balancing

Interactive guide to setting up load balancing with PM2's cluster mode, sticky sessions, and graceful reloads.

localhost:3101/load-balancing-guide
Load Balancing guide page
Load Balancing — explanation of cluster mode with copyable command snippets.
  • Use the number of instances equal to your CPU core count for CPU-bound apps.
  • Use more instances than cores for I/O-bound apps.
  • Always use cluster mode for port-sharing between instances.
  • Use Reload (not Restart) for zero-downtime deployments.

Log Streaming

Follow stdout and stderr in real time for any process.

localhost:3101/logs
Log Streaming page
Log Streaming — pick a process, tail output live over WebSocket.
  • Select a process from the dropdown.
  • Toggle between stdout and stderr.
  • Adjust the line buffer (50 / 200 / 500 / All) — default in Settings.
  • Pause / resume the stream, filter by keyword, or download the full log file.
Log paths are read from PM2's process descriptor. If PM2 was started without log paths configured, logs may be unavailable.

Settings

Application-wide preferences, auto-saved as you change them.

localhost:3101/settings
Settings page showing General, Appearance, PM2, Advanced, Updates and Security tabs
Settings — sections in the left rail, auto-saved on change.
SectionWhat you can change
GeneralAuto refresh toggle, refresh interval, log line count, timestamp display
AppearanceLight / dark mode, accent colour
PM2Daemon connection options
AdvancedLow-level flags for power users
UpdatesCheck for and install a newer ezpm2gui version from npm
SecurityPIN, password, and auto-lock timeout

Checking for Updates

Go to Settings → Updates and click Check for Updates. EZ PM2 GUI queries the npm registry and compares your installed version against the latest published release.

If an update is available, an Install button appears. Installation runs npm install -g ezpm2gui@latest and streams output live. After a successful install, click Restart Server to apply.

A pulsing yellow badge also appears in the top navbar whenever a newer version is detected (checked automatically 4 seconds after page load).

Theme

Click the / icon in the top navigation bar to toggle between dark and light mode. Your preference is saved and applied instantly across all pages.

FAQ

EZ PM2 GUI says "PM2 not connected" on startup

This usually means PM2 has no running processes. Start at least one process with pm2 start <app> and refresh the page.

Remote server shows "PM2 not found"

PM2 is installed in a non-standard PATH on the remote machine. EZ PM2 GUI tries several detection methods automatically. If all fail, use the Install PM2 button in the connection settings, or SSH in manually and run npm install -g pm2.

Can I run multiple instances of EZ PM2 GUI?

Yes — set a different port with the PORT environment variable: PORT=3102 ezpm2gui.

How do I run EZ PM2 GUI as a system service?

On Linux, copy ezpm2gui.service to /etc/systemd/system/, then run:

sudo systemctl daemon-reload
sudo systemctl enable --now ezpm2gui

On Windows, run install-windows-service.js with Node.js (requires administrator privileges).

Where are config files stored?

FilePurpose
src/server/config/remote-connections.jsonRemote SSH connections (passwords AES-256 encrypted)
src/server/config/project-configs.jsonDeployment project definitions
src/server/config/cron-jobs.jsonScheduled cron job definitions
src/server/config/auth.jsonPIN / password hashes and auto-lock settings
src/server/logs/deployment.logDeployment history log