pm2

PM2 — プロセスマネージャー

PM2 はプロセスを稼働し続けるように管理し、クラッシュ時に再起動し、モニタリングやログ記録を提供します。 長時間稼働するサービス、常駐エージェント、バックグラウンドワーカーに使用します。

デタッチされたターミナルには使用しないでください — PTY の出力、アタッチ／表示、または対話型セッションが必要な場合は holdpty を使用してください。 一時的なタスクには使用しないでください — 簡単に実行して終了するエージェントの実行には pi -p > file & を使用してください。

クイックリファレンス

プロセスを起動する

# Simple
pm2 start server.js --name myapp

# With interpreter
pm2 start script.py --interpreter python3 --name worker

# With arguments (use -- to separate pm2 args from script args)
pm2 start app.js --name api -- --port 3000 --env production

# From ecosystem file
pm2 start ecosystem.config.cjs

プロセスを管理する

pm2 list                    # List all processes (table)
pm2 jlist                   # List as JSON (for scripting)
pm2 info <name|id>          # Detailed process info
pm2 restart <name|id|all>   # Restart
pm2 stop <name|id|all>      # Stop (keeps in list)
pm2 delete <name|id|all>    # Stop + remove from list
pm2 restart <name> --update-env  # Restart with refreshed env vars

ログ

pm2 logs                     # Tail all logs
pm2 logs <name> --lines 50   # Tail specific process, last 50 lines
pm2 flush                    # Clear all log files

ログファイルの保存先：~/.pm2/logs/<name>-out.log および <name>-error.log。

モニタリング

pm2 monit          # Real-time TUI: CPU, memory, logs
pm2 dash           # Dashboard with monitoring + logs

Ecosystem 設定

再現可能な複数プロセスのセットアップには、ecosystem.config.cjs ファイルを使用してください。

// ecosystem.config.cjs
module.exports = {
  apps: [
    {
      name: "api",
      script: "dist/server.js",
      instances: 2,                // cluster mode
      exec_mode: "cluster",
      env: {
        NODE_ENV: "production",
        PORT: 3000,
      },
      max_memory_restart: "500M",
      log_date_format: "YYYY-MM-DD HH:mm:ss",
    },
    {
      name: "worker",
      script: "dist/worker.js",
      autorestart: true,
      max_restarts: 10,
      restart_delay: 5000,
      exp_backoff_restart_delay: 100,  // exponential backoff
      watch: false,
    },
  ],
};

pm2 start ecosystem.config.cjs           # Start all apps
pm2 start ecosystem.config.cjs --only api  # Start specific app
pm2 restart ecosystem.config.cjs          # Restart all
pm2 delete ecosystem.config.cjs           # Stop + remove all

便利な ecosystem オプション

オプション	型	説明
script	string	実行するスクリプト（必須）
interpreter	string	インタープリターを上書きします（デフォルト：node）
args	string or string[]	スクリプトの引数
cwd	string	作業ディレクトリ
instances	number	インスタンス数（クラスター モード）
exec_mode	string	"fork"（デフォルト）または "cluster"
autorestart	boolean	終了時に自動再起動します（デフォルト：true）
max_restarts	number	停止するまでの連続再起動の最大回数
restart_delay	number	再起動間の遅延時間（ms）
exp_backoff_restart_delay	number	指数バックオフの基準時間（ms）
max_memory_restart	string	メモリ使用量が指定値を超えた場合に再起動します（例："500M"）
cron_restart	string	cron ベースの再起動スケジュール
watch	boolean or string[]	ファイルの変更を監視します
ignore_watch	string[]	監視対象から除外するパス
env	object	環境変数
log_date_format	string	ログのタイムスタンプ形式
error_file	string	標準エラーのカスタムログパス
out_file	string	標準出力のカスタムログパス
merge_logs	boolean	クラスターインスタンスのログを統合します
stop_exit_codes	number[]	自動再起動をスキップする終了コード

永続化

pm2 save               # Save current process list
pm2 resurrect           # Restore saved process list
pm2 startup             # Generate OS startup script (auto-start on boot)
pm2 unstartup           # Remove startup script

pm2 startup の後、出力されたコマンドを実行してください（管理者権限／sudo が必要な場合があります）。 次に pm2 save を実行して、現在のプロセスをスナップショットとして保存します。これらのプロセスは再起動時に自動起動します。

Windows での注意点

.cmd ラッパーの解決

PM2 は .cmd ファイルを Node.js スクリプトとして実行しようとします。PM2 で .cmd シムを直接起動しないでください。

# ❌ WRONG — resolves to pi.cmd, crashes
pm2 start pi -- -p "prompt"

# ✅ CORRECT — point to the actual .js entry point
pm2 start /path/to/cli.js --interpreter node -- -p "prompt"

npm でインストールした CLI の場合は、実際のスクリプトを探してください。

# Find where the .cmd shim points
cat "$(which pi)" | head -5
# → Look for the .js path, then use that with --interpreter node

ecosystem 設定では、必ず解決済みの .js パスを使用してください。

module.exports = {
  apps: [{
    name: "my-agent",
    // Resolve the actual cli.js, not the .cmd wrapper
    script: "C:\\path\\to\\node_modules\\package\\dist\\cli.js",
    interpreter: "node",
    args: ["--mode", "json"],
  }],
};

ログのパス

PM2 は ~/.pm2/logs/ にログを保存します。Windows では通常 C:\Users\<user>\.pm2\logs\ です。

デーモン

PM2 デーモンはバックグラウンドの Node.js プロセスとして実行されます。pm2 kill はデーモンと、管理対象のすべてのプロセスを停止します。pm2 ping はデーモンが実行中かどうかを確認します。

エージェントのパターン

pi エージェントを常駐サービスとして起動する

まず、実際の cli.js のパスを確認してください（上記の「Windows での注意点」を参照）。

# Find pi's real entry point
cat "$(which pi)" | head -5
# e.g. → /path/to/node_modules/@mariozechner/pi-coding-agent/dist/cli.js

// ecosystem.config.cjs
module.exports = {
  apps: [{
    name: "my-agent",
    // Use the resolved cli.js path — NOT the .cmd wrapper
    script: "/path/to/node_modules/@mariozechner/pi-coding-agent/dist/cli.js",
    interpreter: "node",
    args: ["--mode", "json", "--cwd", "/path/to/project"],
    autorestart: true,
    max_restarts: 10,
    restart_delay: 5000,
  }],
};

注：TTY 以外に対する pi -p は最終テキストのみを出力します。PM2 のログにイベントをすべてストリーミングするには、--mode json を使用してください。

エージェントからプロセスの状態を確認する

# Structured output for parsing
pm2 jlist | node -e "
  const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
  d.forEach(p => console.log(p.name, p.pm2_env.status, 'restarts:', p.pm2_env.restart_time));
"

ログをローテーションする

pm2 install pm2-logrotate        # Install log rotation module
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 5

PM2 を使用しない場合

• デタッチされたターミナルセッション → holdpty を使用します（PTY の出力、アタッチ／表示）
• 一時的なエージェントの実行 → pi -p > file & を使用します（出力をキャプチャして実行後に終了）
• コンテナー → ライフサイクルはコンテナーランタイムが管理するため、Docker 内の PM2 は通常不要です
• Systemd 環境 → Linux ではネイティブの systemd サービスユニットを使用します