Documentation

PM2 Migration

Oxmgr supports PM2's ecosystem.config.json for a smooth migration path. Import existing config directly, then convert to the native format at your own pace.

Migration Steps

# Step 1 — Import existing PM2 ecosystem file
oxmgr import ./ecosystem.config.json

# Step 2 — Convert to native oxfile format
oxmgr convert ecosystem.config.json --out oxfile.toml

# Step 3 — Validate
oxmgr validate ./oxfile.toml --env prod

# Step 4 — Apply
oxmgr apply ./oxfile.toml --env prod

The import command lets you run Oxmgr with your existing PM2 config immediately, with no changes required. Convert to oxfile.toml when you're ready.

Format Comparison

Side-by-side: the same app in PM2 and Oxmgr format.

PM2 ecosystem.config.js

// ecosystem.config.js (PM2)
module.exports = {
  apps: [{
    name: 'api',
    script: 'dist/server.js',
    instances: 4,
    exec_mode: 'cluster',
    env: { NODE_ENV: 'development' },
    env_production: { NODE_ENV: 'production', PORT: 80 }
  }]
};

Oxmgr oxfile.toml

# oxfile.toml (Oxmgr equivalent)
version = 1

[[apps]]
name = "api"
command = "node dist/server.js"
cluster_mode = true
cluster_instances = 4

[apps.env]
NODE_ENV = "development"

[apps.profiles.production.env]
NODE_ENV = "production"
PORT = "80"

Feature Comparison

Topic	PM2 ecosystem.json	oxfile.toml
Profiles / environments	env_<name> pattern	[apps.profiles.<name>]
App dependencies	limited/indirect	explicit depends_on
Crash-loop cutoff	compatibility only	native crash_restart_limit
Apply idempotency	medium	high
Readability at scale	medium	high
Dynamic JS execution	yes (config.js)	no (safer, version-controlled)
Health checks	basic	command-based + readiness gating
Resource limits	memory only	memory + CPU + cgroup v2
Daemon memory	~83 MB	~4 MB

Things to watch when migrating

—PM2's exec_mode: "cluster" maps to cluster_mode = true.
—PM2's env_production maps to [apps.profiles.production.env].
—Oxmgr health checks are command-based, not HTTP endpoint objects like in PM2.
—Oxmgr doesn't support dynamic JavaScript in config files — use profiles instead.
—Run oxmgr validate ./oxfile.toml before applying to catch errors early.

Still have questions?

Open an issue or browse the source on GitHub.

Open an Issue ↗