KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

bm2

★ 70 Open GitHub ↗

High-performance process orchestration for Bun applications.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ⚡ BM2

**A blazing-fast, full-featured process manager built entirely on Bun native APIs.**
The modern PM2 replacement — zero Node.js dependencies, pure Bun performance.

![Runtime](https://img.shields.io/badge/runtime-Bun-f472b6?style=flat-square)
![Language](https://img.shields.io/badge/language-TypeScript-3178c6?style=flat-square)
![License](https://img.shields.io/badge/license-GPLv3-green?style=flat-square)
[![Tests](https://github.com/bun-bm2/bm2/actions/workflows/test.yml/badge.svg)](https://github.com/bun-bm2/bm2/actions/workflows/test.yml)

**Created by the MaxxPainn Team**
🌐 [https://maxxpainn.com](https://maxxpainn.com)
📧 Support: [zak@maxxpainn.com](mailto:zak@maxxpainn.com)

---

## Table of Contents

- [Why BM2?](#why-bm2)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Reference](#cli-reference)
  - [Process Management](#process-management)
  - [Cluster Mode](#cluster-mode)
  - [Log Management](#log-management)
  - [Monitoring and Metrics](#monitoring-and-metrics)
  - [Dashboard](#dashboard)
  - [Ecosystem Files](#ecosystem-files)
  - [Environment Management](#environment-management)
  - [Deployment](#deployment)
  - [Startup Scripts](#startup-scripts)
  - [Modules](#modules)
  - [Daemon Control](#daemon-control)
- [Foreground Mode (Docker & Containers)](#foreground-mode-docker--containers)
- [Configuration Reference](#configuration-reference)
  - [Ecosystem File Format](#ecosystem-file-format)
  - [Process Options](#process-options)
  - [Cluster Options](#cluster-options)
  - [Log Options](#log-options)
  - [Health Check Options](#health-check-options)
  - [Watch Options](#watch-options)
  - [Deploy Configuration](#deploy-configuration)
- [Web Dashboard](#web-dashboard)
  - [Dashboard Features](#dashboard-features)
  - [REST API](#rest-api)
  - [WebSocket API](#websocket-api)
- [Prometheus and Grafana Integration](#prometheus-and-grafana-integration)
- [Programmatic API](#programmatic-api)
  - [Quick Start](#programmatic-quick-start)
  - [Connection Lifecycle](#connection-lifecycle)
  - [Process Management](#programmatic-process-management)
  - [Introspection](#introspection)
  - [Logs](#logs)
  - [Monitoring and Metrics](#programmatic-monitoring-and-metrics)
  - [Persistence](#persistence)
  - [Dashboard Control](#dashboard-control)
  - [Module Management](#module-management)
  - [Daemon Lifecycle](#daemon-lifecycle)
  - [Low-Level Transport](#low-level-transport)
  - [Events](#events)
  - [Error Handling](#error-handling)
  - [Direct ProcessManager Usage](#direct-processmanager-usage)
- [Architecture](#architecture)
- [Comparison with PM2](#comparison-with-pm2)
- [Recipes and Examples](#recipes-and-examples)
- [Troubleshooting](#troubleshooting)
- [File Structure](#file-structure)
- [Contributing](#contributing)
- [License](#license)

---

## Why BM2?

PM2 is the de facto process manager for Node.js, but it carries years of legacy baggage, a heavy dependency tree, and is fundamentally built for the Node.js runtime. BM2 is a ground-up reimagining of production process management designed exclusively for the Bun runtime.

BM2 replaces PM2's Node.js internals with Bun-native APIs. It uses `Bun.spawn` for process management, `Bun.serve` for the dashboard and IPC, native `WebSocket` for daemon communication, `Bun.file` for high-performance I/O, and `Bun.gzipSync` for log compression. The result is a process manager that starts faster, uses less memory, and leverages Bun's superior performance across the board.

---

## Features

**Core Process Management** — Start, stop, restart, reload, delete, and scale processes with automatic restart on crash, configurable restart strategies, memory-limit restarts, and tree killing.

**Cluster Mode** — Run multiple instances of your application with per-worker environment injection, automatic port assignment, and round-robin-ready configuration using `NODE_APP_INSTANCE` conventions.

**Zero-Downtime Reload** — Graceful reload cycles through instances sequentially, starting the new process before stopping the old one, ensuring your application never drops a request.

**Foreground / No-Daemon Mode** — Run BM2 in blocking foreground mode without spawning a background daemon. Designed for containerized environments like Docker, Kubernetes, and any platform that expects PID 1 to remain in the foreground.

**Real-Time Web Dashboard** — A built-in dark-themed web dashboard with live WebSocket updates, CPU/memory charts, process control buttons, and a log viewer. No external dependencies.

**Prometheus Metrics** — A dedicated metrics endpoint exports process and system telemetry in Prometheus exposition format, ready for scraping by Prometheus and visualization in Grafana.

**Log Management** — Automatic log capture with buffered writes, size-based rotation, configurable retention, optional gzip compression, log flushing, and real-time tailing.

**Health Checks** — HTTP health check probes with configurable intervals, timeouts, and failure thresholds that automatically restart unhealthy processes.

**Cron Restarts** — Schedule periodic restarts using standard cron expressions for applications that benefit from regular recycling.

**File Watching** — Automatic restart on file changes with configurable watch paths and ignore patterns. Ideal for development workflows.

**Ecosystem Files** — Declare your entire application topology in a single JSON or TypeScript configuration file and start everything with one command.

**Process Persistence** — Save the current process list and resurrect it after a daemon restart or system reboot. Combined with startup script generation, your applications survive server reboots.

**Startup Script Generation** — Automatically generate and install systemd (Linux) or launchd (macOS) service configurations so the BM2 daemon starts at boot.

**Remote Deployment** — A built-in deploy system that handles SSH-based deployment with git pull, release directory management, symlink rotation, and pre/post-deploy hooks.

**Module/Plugin System** — Extend BM2 with custom modules that hook into the process manager lifecycle.

**Environment Management** — Store, retrieve, and inject environment variables per process with `.env` file loading support.

**Full IPC Architecture** — A daemonized architecture where the CLI communicates with a long-running daemon process over a Unix domain socket using WebSocket protocol.

---

## Requirements

Bun version 1.0 or higher is required. BM2 is built exclusively for the Bun runtime.

Install Bun if you haven't already:

```
curl -fsSL https://bun.sh/install | bash
```

---

## Installation

### From Source

```
git clone https://github.com/bun-bm2/bm2.git
cd bm2
bun install
bun link
```

### Global Install

```
bun add -g bm2
```

### Verify Installation

```
bm2 --version
```

---

## Quick Start

### Start a process

```
bm2 start app.ts
```

### Start with a name and options

```
bm2 start app.ts --name my-api --instances 4 --port 3000
```

### List all processes

```
bm2 list
```

### List processes with live updates

```
bm2 list --live
```

Output:

```
┌────┬──────────┬──────────┬──────┬───────┬──────────┬──────────┬──────────┐
│ ID │ Name     │ Status   │ PID  │ CPU   │ Memory   │ Restarts │ Uptime   │
├────┼──────────┼──────────┼──────┼───────┼──────────┼──────────┼──────────┤
│ 0  │ my-api-0 │ online   │ 4521 │ 0.3%  │ 42.1 MB  │ 0        │ 5m 23s  │
│ 1  │ my-api-1 │ online   │ 4522 │ 0.2%  │ 39.8 MB  │ 0        │ 5m 23s  │
│ 2  │ my-api-2 │ online   │ 4523 │ 0.4%  │ 41.3 MB  │ 0        │ 5m 23s  │
│ 3  │ my-api-3 │ online   │ 4524 │ 0.1%  │ 40.5 MB  │ 0        │ 5m 23s  │
└────┴──────────┴──────────┴──────┴───────┴──────────┴──────────┴──────────┘
```

### Open the dashboard

```
bm2 dashboard
```

Output:

```
⚡ Dashboard running at http://localhost:9615
📊 Prometheus metrics at http://localhost:9616/metrics
```

### Save and auto-resurrect on reboot

```
bm2 save
bm2 startup
```

---

## CLI Reference

### Process Management

#### bm2 start

Start a new process or processes.

```
bm2 start server.ts
```

```
bm2 start server.ts --name api -- --port 8080 --host 0.0.0.0
```

```
bm2 start server.ts --name api --env NODE_ENV=production --env API_KEY=xxx
```

```
bm2 start server.ts --name api --max-memory-restart 512M
```

```
bm2 start script.py --interpreter python3
```

```
bm2 start server.ts --name api --wait-ready --listen-timeout 10000
```

**Options:**

| Flag | Description | Default |
|---|---|---|
| `--name <name>` | Process name | Script filename |
| `--instances <n>` | Number of instances. Use `max` for all CPUs | `1` |
| `--exec-mode <mode>` | `fork` or `cluster` | `fork` |
| `--cwd <path>` | Working directory | Current directory |
| `--env <KEY=VAL>` | Environment variable (repeatable) | — |
| `--interpreter <bin>` | Custom interpreter binary | Auto-detected |
| `--interpreter-args <args>` | Arguments for the interpreter | — |
| `--node-args <args>` | Additional runtime arguments | — |
| `--max-memory-restart <size>` | Restart when memory exceeds limit | — |
| `--max-restarts <n>` | Maximum consecutive restarts | `16` |
| `--min-uptime <ms>` | Minimum uptime before a restart is considered stable | `1000` |
| `--restart-delay <ms>` | Delay between restarts | `0` |
| `--kill-timeout <ms>` | Grace period before SIGKILL | `5000` |
| `--no-autorestart` | Disable automatic restart | `false` |
| `--cron <expression>` | Cron expression for scheduled restarts | — |
| `--watch` | Enable file watching | `false` |
| `--ignore-watch <dirs>` | Directories to ignore | `node_modules,.git` |
| `--port <n>` | Base port (auto-incremented in cluster mode) | — |
| `--namespace <ns>` | Process namespace for grouping | — |
| `--wait-ready` | Wait for process ready signal | `false` |
| `--listen-timeout <ms>` | Timeout waiting for ready signal | `3000` |
| `--source-map-support` | Enable source map support | `false` |
| `--merge-logs` | Merge all instance logs into one file | `false` |
| `--log-date-format <fmt>` | Date format prefix for log lines | — |
| `--output <file>` | Custom stdout log path | `~/.bm2/logs/<name>-<id>-out.log` |
| `--error <file>` | Custom stderr log path | `~/.bm2/logs/<name>-<id>-error.log` |
| `--log-max-size <size>` | Max log file size before rotation | `10M` |
| `--log-retain <n>` | Number of rotated log files to keep | `5` |
| `--log-compress` | Gzip rotated log files | `false` |
| `--health-check-url <url>` | HTTP endpoint for health probes | — |
| `--health-check-interval <ms>` | Probe interval | `30000` |
| `--health-check-timeout <ms>` | Probe timeout | `5000` |
| `--health-check-max-fails <n>` | Failures before restart | `3` |
| `--no-daemon`, `-d` | Run in foreground without a daemon (blocks) | `false` |
| `--raw` | Also send child logs to stdout/stderr while retaining log files | `false` |

> **Flags are position-independent.** `--no-daemon` (and all other flags) may appear anywhere relative to the script path:
> ```
> bm2 start --no-daemon app.ts
> bm2 start app.ts --no-daemon
> bm2 start --name api --no-daemon app.ts --watch
> ```

---

#### bm2 stop

Stop a process, all processes with a name, or all processes.

```
bm2 stop 0
bm2 stop my-api
bm2 stop my-namespace
bm2 stop all
```

---

#### bm2 restart

Stop and restart a process. The process is fully stopped and then re-spawned.

```
bm2 restart my-api
bm2 restart all
```

---

#### bm2 reload

Graceful zero-downtime reload. New instances start before old ones are killed, ensuring your application always has live workers handling requests.

```
bm2 reload my-api
bm2 reload all
```

The reload process works as follows for each instance. First, a new process is spawned. Then BM2 waits for the new process to become stable or emit a ready signal if `--wait-ready` is enabled. Next, the old process receives SIGTERM and is given the kill timeout to shut down gracefully. Finally, the cycle moves to the next instance.

---

#### bm2 delete

Stop and remove a process from BM2's management.

```
bm2 delete 0
bm2 delete my-api
bm2 delete all
```

---

#### bm2 scale

Dynamically scale a process group up or down.

```
bm2 scale my-api 8
bm2 scale my-api 2
```

When scaling up, new instances inherit the configuration of the existing instances. When scaling down, the highest-numbered instances are stopped and removed first.

---

#### bm2 describe

Show detailed information about a process.

```
bm2 describe my-api
```

Output:

```
┌─────────────────────┬──────────────────────────────────────────┐
│ Name                │ my-api-0                                 │
│ ID                  │ 0                                        │
│ Status              │ online                                   │
│ PID                 │ 4521                                     │
│ Exec Mode           │ cluster                                  │
│ Instances           │ 4                                        │
│ Uptime              │ 2h 15m                                   │
│ Restarts            │ 0                                        │
│ Unstable Restarts   │ 0                                        │
│ CPU                 │ 0.3%                                     │
│ Memory              │ 42.1 MB                                  │
│ File Handles        │ 24                                       │
│ Script              │ /home/user/app/server.ts                 │
│ CWD                 │ /home/user/app                           │
│ Interpreter         │ bun                                      │
│ Watch               │ disabled                                 │
│ Max Memory Restart  │ 512 MB                                   │
│ Health Check        │ http://localhost:3000/health (healthy)    │
│ Cron Restart        │ disabled                                 │
│ Namespace           │ production                               │
│ Created             │ 2025-02-11T10:30:00.000Z                 │
│ Out Log             │ /home/user/.bm2/logs/my-api-0-out.log    │
│ Error Log           │ /home/user/.bm2/logs/my-api-0-error.log  │
└─────────────────────┴──────────────────────────────────────────┘
```

---

#### bm2 list

List all managed processes with their status, resource usage, and uptime.  
Supports a **live mode** with auto-refresh and interactive keyboard shortcuts.

```bash
bm2 list
```

## Live Mode Keyboard Shortcuts

```
R : Reload table manually
M : Sort by Memory usage
C : Sort by CPU usage
U : Sort by Uptime
Q : Quit live mode
```

## Examples

```bash
# List all processes once
bm2 list

# List processes with live updates
bm2 list --live
```

## Notes

* Live mode automatically refreshes the table every second (default interval).
* Sorting can be changed on the fly using the keyboard shortcuts.
* Press `R` to reload manually, `Q` to quit live mode.

---

#### bm2 signal

Send an OS signal to a process.

```
bm2 signal my-api SIGUSR2
```

---

#### bm2 reset

Reset the restart counter for a process.

```
bm2 reset my-api
bm2 reset all
```

---

### Cluster Mode

Cluster mode spawns multiple instances of your application, each running in its own process. This is ideal for CPU-bound workloads and for taking full advantage of multi-core servers.

```bash
bm2 start server.ts --name api --instances max
```

```bash
bm2 start server.ts --name api --instances 4
```

```bash
bm2 start server.ts --name api --instances 4 --port 3000
```

#### ⚠️ Current Status & Limitations

While `bm2` provides the orchestration for clustering, please note that **Bun's native cluster implementation is currently limited by the underlying OS:**

* **Linux Only:** Port sharing via `reusePort` is only fully supported on **Linux**.
* **macOS & Windows:** Due to OS-level limitations with `SO_REUSEPORT`, these platforms ignore the `reusePort` option. On these systems, clustering may result in "Address already in use" errors if attempting to bind multiple workers to the same port.

`bm2` leverages the native [Bun.serve cluster logic](https://bun.sh/docs/api/http#cluster) to ensure maximum performance, but it remains subject to the runtime's maturity.

#### Environment Variables

Each cluster worker receives the following environment variables:

| Variable | Description |
| --- | --- |
| `BM2_CLUSTER` | Set to `"true"` in cluster mode |
| `BM2_WORKER_ID` | Zero-indexed worker ID |
| `BM2_INSTANCES` | Total number of instances |
| `NODE_APP_INSTANCE` | Same as `BM2_WORKER_ID` (PM2 compatibility) |
| `PORT` | `basePort + workerIndex` (if `--port` is specified) |

---

#### Example: Cluster-Aware Port Binding

To enable clustering in Bun, you must explicitly set `reusePort: true`. This allows multiple processes to listen on the same port (on supported OSs).

```typescript
// server.ts
const workerId = parseInt(process.env.BM2_WORKER_ID || "0");
const port = parseInt(process.env.PORT || "3000");

Bun.serve({
  port,
  // Share the same port across multiple processes
  // This is the important part!
  reusePort: true,
  fetch(req) {
    return new Response(`Hello from worker ${workerId} on port ${port}`);
  },
});

console.log(`Worker ${workerId} listening on :${port}`);
```

---

### Log Management

#### bm2 logs

Display recent logs for a process.

```
bm2 logs
```

```
bm2 logs my-api --lines 100
```

```
bm2 logs my-api --err
```

```
bm2 logs my-api --follow
bm2 logs my-api -f
bm2 logs -f
```

---

#### bm2 flush

Clear log files.

```
bm2 flush my-api
bm2 flush
```

---

#### Log Rotation

Log rotation runs automatically in the background. It checks log file sizes once per minute and rotates when the configured threshold is exceeded.

```
bm2 start server.ts --log-max-size 50M --log-retain 10 --log-compress
```

Rotation behavior: When a log file exceeds `--log-max-size`, it is renamed with a numeric suffix. Existing rotated files are shifted up by one number. Files beyond the `--log-retain` count are deleted. If `--log-compress` is enabled, rotated files are gzip-compressed using Bun's native `Bun.gzipSync`.

Default values:

| Setting | Default |
|---|---|
| `log-max-size` | `10 MB` |
| `log-retain` | `5` |
| `log-compress` | `false` |

---

### Monitoring and Metrics

#### bm2 monit

Open an interactive terminal monitor showing real-time CPU, memory, and event loop data for all processes.

```
bm2 monit
```

---

#### bm2 metrics

Dump a current metrics snapshot as JSON.

```
bm2 metrics
```

Output:

```
{
  "timestamp": 1707650400000,
  "processes": [
    {
      "id": 0,
      "name": "my-api-0",
      "pid": 4521,
      "cpu": 0.3,
      "memory": 44150784,
      "handles": 24,
      "status": "online",
      "restarts": 0,
      "uptime": 8100000
    }
  ],
  "system": {
    "totalMemory": 17179869184,
    "freeMemory": 8589934592,
    "cpuCount": 8,
    "loadAvg": [1.23, 1.45, 1.67],
    "platform": "linux"
  }
}
```

---

#### bm2 metrics --history

Retrieve historical metrics. BM2 retains up to 1 hour of per-second snapshots in memory.

```
bm2 metrics --history 600
```

---

#### bm2 prometheus

Output current metrics in Prometheus exposition format.

```
bm2 prometheus
```

Output:

```
# HELP bm2_process_cpu CPU usage percentage
# TYPE bm2_process_cpu gauge
bm2_process_cpu{name="my-api-0",id="0"} 0.3
# HELP bm2_process_memory_bytes Memory usage in bytes
# TYPE bm2_process_memory_bytes gauge
bm2_process_memory_bytes{name="my-api-0",id="0"} 44150784
# HELP bm2_process_restarts_total Total restart count
# TYPE bm2_process_restarts_total counter
bm2_process_restarts_total{name="my-api-0",id="0"} 0
# HELP bm2_process_uptime_seconds Process uptime in seconds
# TYPE bm2_process_uptime_seconds gauge
bm2_process_uptime_seconds{name="my-api-0",id="0"} 8100
# HELP bm2_process_status Process status (1=online)
# TYPE bm2_process_status gauge
bm2_process_status{name="my-api-0",id="0",status="online"} 1
# HELP bm2_system_memory_total_bytes Total system memory
# TYPE bm2_system_memory_total_bytes gauge
bm2_system_memory_total_bytes 17179869184
# HELP bm2_system_memory_free_bytes Free system memory
# TYPE bm2_system_memory_free_bytes gauge
bm2_system_memory_free_bytes 8589934592
# HELP bm2_system_load_average System load average
# TYPE bm2_system_load_average gauge
bm2_system_load_average{period="1m"} 1.23
bm2_system_load_average{period="5m"} 1.45
bm2_system_load_average{period="15m"} 1.67
```

---

### Dashboard

#### bm2 dashboard

Launch the built-in web dashboard.

```
bm2 dashboard
```

```
bm2 dashboard --port 8080 --metrics-port 8081
```

#### bm2 dashboard stop

Stop the web dashboard.

```
bm2 dashboard stop
```

See the Web Dashboard section below for a detailed description of dashboard capabilities.

---

### Ecosystem Files

An ecosystem file defines your entire application topology in a single configuration. BM2 supports JSON and TypeScript ecosystem files.

```
bm2 start ecosystem.config.json
```

```
bm2 start ecosystem.config.ts
```

Example `ecosystem.config.json`:

```
{
  "apps": [
    {
      "name": "api",
      "script": "./src/api/server.ts",
      "instances": 4,
      "execMode": "cluster",
      "port": 3000,
      "env": {
        "NODE_ENV": "production",
        "DATABASE_URL": "postgres://localhost/mydb"
      },
      "maxMemoryRestart": "512M",
      "healthCheckUrl": "http://localhost:3000/health",
      "healthCheckInterval": 15000,
      "logMaxSize": "50M",
      "logRetain": 10,
      "logCompress": true
    },
    {
      "name": "worker",
      "script": "./src/worker/index.ts",
      "instances": 2,
      "env": {
        "NODE_ENV": "production",
        "REDIS_URL": "redis://localhost:6379"
      },
      "cron": "0 */6 * * *",
      "maxRestarts": 50
    },
    {
      "name": "scheduler",
      "script": "./src/scheduler/cron.ts",
      "instances": 1,
      "autorestart": true,
      "watch": ["./src/scheduler"]
    }
  ],
  "deploy": {
    "production": {
      "user": "deploy",
      "host": ["web1.example.com", "web2.example.com"],
      "ref": "origin/main",
      "repo": "git@github.com:your-org/your-app.git",
      "path": "/var/www/app",
      "preDeploy": "bun test",
      "postDeploy": "bun install && bm2 reload ecosystem.config.json --env production"
    }
  }
}
```

Example `ecosystem.config.ts`:

```
// ecosystem.config.ts
import type { EcosystemConfig } from "bm2/types";

const config: EcosystemConfig = {
  apps: [
    {
      name: "api",
      script: "./src/server.ts",
      instances: "max",
      execMode: "cluster",
      port: 3000,
      env: {
        NODE_ENV: "production",
      },
      maxMemoryRestart: "1G",
      healthCheckUrl: "http://localhost:3000/health",
    },
  ],
};

export default config;
```

---

### Environment Management

#### bm2 env set

Set an environment variable for a process.

```
bm2 env set my-api DATABASE_URL postgres://localhost/mydb
```

#### bm2 env get

List all stored environment variables for a process.

```
bm2 env get my-api
```

#### bm2 env delete

Remove an environment variable or all environment variables.

```
bm2 env delete my-api DATABASE_URL
bm2 env delete my-api
```

#### .env File Support

BM2 can load environment variables from `.env` files:

```
bm2 start server.ts --env-file .env.production
```

---

### Deployment

BM2 includes a built-in deployment system for SSH-based deployments with release management.

#### bm2 deploy setup

Initial setup of the remote server. Creates the directory structure and clones the repository.

```
bm2 deploy ecosystem.config.json production setup
```

This creates the following remote directory structure:

```
/var/www/app/
├── source/
├── releases/
│   ├── 2025-02-11T10-30-00-000Z/
│   └── 2025-02-10T15-45-00-000Z/
├── current -> releases/2025-02-11T10-30-00-000Z/
└── shared/
```

#### bm2 deploy

Deploy a new release.

```
bm2 deploy ecosystem.config.json production
```

The deploy process works as follows. It runs the `preDeploy` hook locally such as running tests. It connects via SSH to each configured host. It pulls the latest code from the configured ref. It creates a new timestamped release directory. It updates the current symlink to the new release. It runs the `postDeploy` hook remotely such as installing dependencies and reloading processes. It cleans up old releases, keeping only the 5 most recent.

Multi-host deployment is supported. Specify an array of hosts to deploy to all of them sequentially:

```
{
  "host": ["web1.example.com", "web2.example.com", "web3.example.com"]
}
```

---

### Startup Scripts

#### bm2 startup

Generate and display a startup script for your operating system. On Linux, this generates a systemd unit file. On macOS, this generates a launchd plist.

```
bm2 startup
```

#### bm2 startup install

Automatically install the startup script so the BM2 daemon starts at boot.

```
bm2 startup install
```

#### bm2 startup uninstall

Remove the startup script.

```
bm2 startup uninstall
```

#### bm2 save

Save the current process list so it can be restored on daemon startup.

```
bm2 save
```

#### bm2 resurrect

Restore previously saved processes.

```
bm2 resurrect
```

Recommended boot setup:

```
bm2 start ecosystem.config.json
bm2 save
bm2 startup install
```

On reboot, systemd or launchd starts the BM2 daemon, and the daemon automatically runs resurrect to restore your processes.

---

### Modules

BM2 supports a plugin system for extending functionality.

#### bm2 module install

Install a module from a git URL, local path, or npm package name.

```
bm2 module install https://github.com/user/bm2-logrotate.git
bm2 module install ./my-bm2-module
bm2 module install bm2-prometheus-pushgateway
```

#### bm2 module list

List installed modules.

```
bm2 module list
```

#### bm2 module uninstall

Remove an installed module.

```
bm2 module uninstall bm2-prometheus-pushgateway
```

#### Writing a BM2 Module

A BM2 module is a package with a default export implementing the BM2Module interface:

```
// my-module/index.ts
import type { ProcessManager } from "bm2/process-manager";

export default {
  name: "my-module",
  version: "1.0.0",

init(pm: ProcessManager) {
    console.log("[my-module] Initialized with", pm.list().length, "processes");
  },

destroy() {
    console.log("[my-module] Destroyed");
  },
};
```

---

### Daemon Control

#### bm2 ping

Check if the daemon is running.

```
bm2 ping
```

#### bm2 kill

Stop all processes and kill the daemon.

```
bm2 kill
```

---

## Foreground Mode (Docker & Containers)

By default, BM2 spawns a background daemon process and returns immediately — ideal for long-running servers. However, containerized environments like **Docker**, **Kubernetes**, and **Railway** expect the entrypoint process to stay in the **foreground**. If BM2 daemonizes and exits, the container stops.

Use `--no-daemon` (alias `-d`) to run BM2 in **foreground / blocking mode**. In this mode:

- No background daemon is spawned.
- The `bm2 start` process itself stays alive, blocking the terminal (or container).
- All managed child processes are supervised in-process.
- Auto-restart and crash recovery still work normally.
- The process exits only when all child processes stop or a signal (e.g. `SIGTERM`) is received.

### Flags

| Flag | Alias | Description |
|---|---|---|
| `--no-daemon` | `-d` | Run in foreground without spawning a background daemon |

### Usage

```bash
# Foreground — blocks until the process exits
bm2 start --no-daemon server.ts

# Flag order is flexible — these are all equivalent
bm2 start server.ts --no-daemon
bm2 start --no-daemon server.ts --name api
bm2 start --name api --no-daemon server.ts
```

### Docker

This is the recommended pattern for running BM2 inside a Docker container. The `CMD` instruction should use `--no-daemon` so BM2 stays as PID 1 (or the foreground entrypoint) and Docker can track its lifecycle correctly.

**Dockerfile**

```dockerfile
FROM oven/bun:latest

WORKDIR /app

COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

COPY . .

# Install BM2 globally
RUN bun add -g bm2

# Use --no-daemon so BM2 stays in the foreground
CMD ["bm2", "start", "--no-daemon", "./server.ts"]
```

### Docker logs and log files

Use `--raw` with `--no-daemon` to keep BM2 log files while also exposing the
managed process output to the container runtime:

```dockerfile
CMD ["bm2", "start", "--no-daemon", "--raw", "ecosystem.config.cjs"]
```

`--raw` mirrors child stdout to BM2 stdout and child stderr to BM2 stderr. It
does not disable `outFile` or `errorFile`.

**With additional options**

```dockerfile
CMD ["bm2", "start", "--no-daemon", "--name", "api", "--instances", "2", "./server.ts"]
```

**With an ecosystem file**

```dockerfile
CMD ["bm2", "start", "--no-daemon", "ecosystem.config.json"]
```

> **Note:** Ecosystem file support with `--no-daemon` behaves identically to normal mode — all `apps` entries are started and supervised in-process.

### Docker Compose

```yaml
services:
  api:
    build: .
    ports:
      - "3000:3000"
    command: ["bm2", "start", "--no-daemon", "./server.ts"]
    restart: unless-stopped
```

### Kubernetes

```yaml
containers:
  - name: api
    image: your-org/api:latest
    command: ["bm2", "start", "--no-daemon", "./server.ts"]
```

### Behaviour Differences vs. Daemon Mode

| Behaviour | Daemon mode (default) | Foreground mode (`--no-daemon`) |
|---|---|---|
| CLI returns immediately | ✅ | ❌ — blocks |
| Background daemon spawned | ✅ | ❌ |
| Unix socket IPC | ✅ | ❌ |
| Auto-restart on crash | ✅ | ✅ |
| `bm2 list` / `bm2 logs` from another shell | ✅ | ❌ — no daemon to query |
| Suitable for Docker / containers | ❌ | ✅ |
| Suitable for long-running servers | ✅ | ✅ |

---

## Configuration Reference

### Ecosystem File Format

The ecosystem file is a JSON or TypeScript file with the following top-level structure:

```
interface EcosystemConfig {
  apps: StartOptions[];
  deploy?: Record<string, DeployConfig>;
}
```

---

### Process Options

The complete set of options available for each entry in the apps array:

| Option | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | Filename | Process name |
| `script` | `string` | required | Path to the script to execute |
| `args` | `string[]` | `[]` | Arguments passed to the script |
| `cwd` | `string` | `process.cwd()` | Working directory |
| `env` | `Record<string, string>` | `{}` | Environment variables |
| `instances` | `number` or `"max"` | `1` | Number of instances |
| `execMode` | `"fork"` or `"cluster"` | `"fork"` | Execution mode |
| `autorestart` | `boolean` | `true` | Restart on crash |
| `maxRestarts` | `number` | `16` | Maximum restart attempts before giving up |
| `minUptime` | `number` | `1000` | Minimum ms a process must be up to be considered stable |
| `maxMemoryRestart` | `string` or `number` | — | Memory threshold for restart |
| `restartDelay` | `number` | `0` | Delay in ms between restart attempts |
| `killTimeout` | `number` | `5000` | Grace period in ms before SIGKILL |
| `interpreter` | `string` | Auto | Custom interpreter |
| `interpreterArgs` | `string[]` | — | Arguments for the interpreter |
| `nodeArgs` | `string[]` | — | Additional runtime arguments |
| `namespace` | `string` | — | Namespace for grouping processes |
| `sourceMapSupport` | `boolean` | `false` | Enable source map support |
| `waitReady` | `boolean` | `false` | Wait for process to emit ready signal |
| `listenTimeout` | `number` | `3000` | Timeout when waiting for ready signal |
| `noDaemon` | `boolean` | `false` | Run in foreground without a daemon |

---

### Cluster Options

| Option | Type | Default | Description |
|---|---|---|---|
| `instances` | `number` or `"max"` | `1` | Worker count |
| `execMode` | `"cluster"` | `"fork"` | Set to cluster for multi-instance mode |
| `port` | `number` | — | Base port. Worker i gets port + i |

---

### Log Options

| Option | Type | Default | Description |
|---|---|---|---|
| `outFile` | `string` | `~/.bm2/logs/<name>-<id>-out.log` | Custom stdout log path |
| `errorFile` | `string` | `~/.bm2/logs/<name>-<id>-error.log` | Custom stderr log path |
| `mergeLogs` | `boolean` | `false` | Merge all instance logs into one file |
| `raw` | `boolean` | `false` | Mirror child stdout and stderr to BM2 stdout and stderr |
| `logDateFormat` | `string` | — | Date format for log line prefixes |
| `logMaxSize` | `string` or `number` | `"10M"` | Max log file size before rotation |
| `logRetain` | `number` | `5` | Number of rotated files to keep |
| `logCompress` | `boolean` | `false` | Gzip-compress rotated log files |

---

### Health Check Options

| Option | Type | Default | Description |
|---|---|---|---|
| `healthCheckUrl` | `string` | — | URL to probe |
| `healthCheckInterval` | `number` | `30000` | Probe interval in ms |
| `healthCheckTimeout` | `number` | `5000` | Probe timeout in ms |
| `healthCheckMaxFails` | `number` | `3` | Consecutive failures before restart |

---

### Watch Options

| Option | Type | Default | Description |
|---|---|---|---|
| `watch` | `boolean` or `string[]` | `false` | Enable file watching |
| `ignoreWatch` | `string[]` | `["node_modules", ".git", ".bm2"]` | Patterns to ignore |

---

### Deploy Configuration

| Option | Type | Description |
|---|---|---|
| `user` | `string` | SSH user |
| `host` | `string` or `string[]` | Remote host(s) |
| `ref` | `string` | Git ref to deploy |
| `repo` | `string` | Git repository URL |
| `path` | `string` | Remote deployment path |
| `preDeploy` | `string` | Command to run locally before deploy |
| `postDeploy` | `string` | Command to run remotely after deploy |
| `preSetup` | `string` | Command to run remotely during setup |
| `postSetup` | `string` | Command to run remotely after setup |
| `ssh_options` | `string` | Additional SSH options |
| `env` | `Record<string, string>` | Environment variables for remote commands |

---

## Web Dashboard

The BM2 dashboard is a self-contained web application served directly by the daemon. It requires no external dependencies. The HTML, CSS, JavaScript, and WebSocket server are all built in.

### Dashboard Features

**Process Overview** — Four summary cards showing counts of online and errored processes, total CPU usage, and aggregate memory consumption.

**System Information** — Platform, CPU count, load average, and memory usage with a visual progress bar.

**CPU and Memory Chart** — A real-time canvas-rendered chart showing aggregate CPU percentage and memory usage over the last 60 data points, updating every 2 seconds.

**Process Table** — A detailed table showing every managed process with columns for ID, name, status with color-coded badges, PID, CPU, memory, restart count, uptime, and action buttons for restart, stop, and log viewing.

**Log Viewer** — A tabbed log panel that streams stdout and stderr from any selected process, with syntax highlighting for timestamps and error output. Logs auto-scroll to the latest entry.

**Live Updates** — All data is streamed over WebSocket with a visual pulse indicator confirming the live connection. If the connection drops, the dashboard automatically reconnects within 2 seconds.

---

### REST API

The dashboard exposes a REST API on the same port:

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/` | Dashboard HTML |
| `GET` | `/api/processes` | List all processes as JSON |
| `GET` | `/api/metrics` | Current metrics snapshot |
| `GET` | `/api/metrics/history?seconds=300` | Historical metrics |
| `GET` | `/api/prometheus` or `/metrics` | Prometheus text format |
| `POST` | `/api/restart` | Restart process |
| `POST` | `/api/stop` | Stop process |
| `POST` | `/api/reload` | Graceful reload |
| `POST` | `/api/delete` | Delete process |
| `POST` | `/api/scale` | Scale process |
| `POST` | `/api/flush` | Flush logs |

POST endpoints accept JSON body with `target` field for process identification and additional fields where applicable such as `count` for scaling.

Example using curl:

```
curl http://localhost:9615/api/processes
```

```
curl -X POST http://localhost:9615/api/restart \
  -H "Content-Type: application/json" \
  -d '{"target": "my-api"}'
```

```
curl -X POST http://localhost:9615/api/scale \
  -H "Content-Type: application/json" \
  -d '{"target": "my-api", "count": 8}'
```

```
curl http://localhost:9615/metrics
```

---

### WebSocket API

Connect to `ws://localhost:9615/ws` for real-time bidirectional communication.

Client to server messages:

```
{ "type": "getState", "data": {} }
```

```
{ "type": "getLogs", "data": { "target": 0, "lines": 50 } }
```

```
{ "type": "restart", "data": { "target": "my-api" } }
```

```
{ "type": "stop", "data": { "target": 0 } }
```

```
{ "type": "reload", "data": { "target": "all" } }
```

```
{ "type": "scale", "data": { "target": "my-api", "count": 4 } }
```

Server to client messages:

```
{
  "type": "state",
  "data": {
    "processes": [],
    "metrics": {
      "timestamp": 1707650400000,
      "processes": [],
      "system": {}
    }
  }
}
```

```
{
  "type": "logs",
  "data": [
    { "name": "my-api-0", "id": 0, "out": "...", "err": "..." }
  ]
}
```

---

## Prometheus and Grafana Integration

BM2 runs a dedicated Prometheus metrics server on default port 9616 separately from the dashboard, following best practices for metrics collection.

### Prometheus Configuration

Add the following to your `prometheus.yml`:

```
scrape_configs:
  - job_name: "bm2"
    scrape_interval: 5s
    static_configs:
      - targets: ["localhost:9616"]
```

### Available Metrics

| Metric | Type | Labels | Description |
|---|---|---|---|
| `bm2_process_cpu` | gauge | `name`, `id` | CPU usage percentage |
| `bm2_process_memory_bytes` | gauge | `name`, `id` | Memory usage in bytes |
| `bm2_process_restarts_total` | counter | `name`, `id` | Total restart count |
| `bm2_process_uptime_seconds` | gauge | `name`, `id` | Uptime in seconds |
| `bm2_process_status` | gauge | `name`, `id`, `status` | 1 if online, 0 otherwise |
| `bm2_system_memory_total_bytes` | gauge | — | Total system memory |
| `bm2_system_memory_free_bytes` | gauge | — | Free system memory |
| `bm2_system_load_average` | gauge | `period` | Load average (1m, 5m, 15m) |

### Grafana Dashboard

Import a dashboard with the following panels for comprehensive monitoring: Process Status Overview as a stat panel colored by status, CPU Usage per Process as a time series with `bm2_process_cpu` grouped by name, Memory Usage per Process as a time series with `bm2_process_memory_bytes` grouped by name, Restart Rate as a graph of `rate(bm2_process_restarts_total[5m])` to detect instability, System Load as a time series of `bm2_system_load_average` across all periods, and Memory Pressure as a gauge computing `1 - (bm2_system_memory_free_bytes / bm2_system_memory_total_bytes)`.

### Alert Rules Example

```
groups:
  - name: bm2
    rules:
      - alert: ProcessDown
        expr: bm2_process_status == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Process {{ $labels.name }} is down"

- alert: HighRestartRate
        expr: rate(bm2_process_restarts_total[5m]) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Process {{ $labels.name }} is restarting frequently"

- alert: HighMemoryUsage
        expr: bm2_process_memory_bytes > 1e9
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Process {{ $labels.name }} using > 1GB memory"
```

---

## Programmatic API

BM2 exposes two levels of programmatic access. The `BM2` client class communicates with the daemon over its Unix socket, giving you the same capabilities as the CLI from within any Bun application. For in-process usage without a daemon, you can use the `ProcessManager` class directly.

### Programmatic Quick Start

```ts
import BM2 from "bm2";

const bm2 = new BM2();
await bm2.connect();

// Start a clustered application
await bm2.start({
  script: "./server.ts",
  name: "api",
  instances: 4,
  execMode: "cluster",
  port: 3000,
  env: { NODE_ENV: "production" },
});

// List all processes
const processes = await bm2.list();
console.log(processes);

// Stream metrics every 2 seconds
bm2.on("metrics", (snapshot) => {
  console.log(`CPU: ${snapshot.system.cpu}%  Memory: ${snapshot.system.memory}%`);
});
bm2.startPolling(2000);

// Graceful shutdown
bm2.stopPolling();
await bm2.disconnect();
```

---

### Connection Lifecycle

#### `bm2.connect(): Promise<BM2>`

Connect to the BM2 daemon. If the daemon is not running, it is spawned automatically and the method waits up to 5 seconds for it to become responsive. Returns the `BM2` instance for chaining.

```ts
const bm2 = new BM2();
await bm2.connect();
console.log(`Connected to daemon PID ${bm2.daemonPid}`);
```

#### `bm2.disconnect(): Promise<void>`

Disconnect from the daemon. This stops any internal polling timers but does not kill the daemon — all managed processes continue running.

```ts
await bm2.disconnect();
console.log(bm2.connected); // false
```

#### `bm2.connected: boolean`

Read-only property indicating whether the client believes the daemon is reachable.

#### `bm2.daemonPid: number | null`

Read-only property containing the PID of the daemon process, or `null` if unknown.

---

### Programmatic Process Management

#### `bm2.start(options: StartOptions): Promise<ProcessState[]>`

Start a new process or process group. The `script` path is automatically resolved to an absolute path. Returns the array of `ProcessState` objects for the started instances.

```ts
const procs = await bm2.start({
  script: "./worker.ts",
  name: "worker",
  instances: 2,
  env: { QUEUE: "emails" },
  maxMemoryRestart: "256M",
});
console.log(`Started ${procs.length} instances`);
```

The `StartOptions` object accepts all the same fields documented in the [Process Options](#process-options) configuration reference.

#### `bm2.startEcosystem(config: EcosystemConfig): Promise<ProcessState[]>`

Start an entire ecosystem configuration. All script paths within the config are resolved to absolute paths before being sent to the daemon.

```ts
const procs = await bm2.startEcosystem({
  apps: [
    { script: "./api.ts", name: "api", instances: 4, port: 3000 },
    { script: "./worker.ts", name: "worker", instances: 2 },
  ],
});
```

#### `bm2.stop(target?: string | number): Promise<ProcessState[]>`

Stop one or more processes. The `target` can be a process name, numeric ID, namespace, or `"all"`. Defaults to `"all"` when omitted.

```ts
await bm2.stop("api");       // Stop by name
await bm2.stop(0);           // Stop by ID
await bm2.stop();            // Stop all
```

#### `bm2.restart(target?: string | number): Promise<ProcessState[]>`

Hard restart one or more processes. The process is fully stopped and then re-spawned.

```ts
await bm2.restart("api");
await bm2.restart();          // Restart all
```

#### `bm2.reload(target?: string | number): Promise<ProcessState[]>`

Graceful zero-downtime reload. New instances are started before old ones are stopped, ensuring no dropped requests. Ideal for deploying new code.

```ts
await bm2.reload("api");
await bm2.reload();           // Reload all
```

#### `bm2.delete(target?: string | number): Promise<ProcessState[]>`

Stop and remove one or more processes from BM2's management entirely.

```ts
await bm2.delete("api");
await bm2.delete();           // Delete all
```

#### `bm2.scale(target: string | number, count: number): Promise<ProcessState[]>`

Scale a process group to the specified number of instances. When scaling up, new instances inherit the configuration of existing ones. When scaling down, the highest-numbered instances are removed first.

```ts
await bm2.scale("api", 8);   // Scale up to 8 instances
await bm2.scale("api", 2);   // Scale down to 2 instances
```

#### `bm2.sendSignal(target: string | number, signal: string): Promise<void>`

Send an OS signal to a managed process.

```ts
await bm2.sendSignal("api", "SIGUSR2");
await bm2.sendSignal(0, "SIGHUP");
```

#### `bm2.reset(target?: string | number): Promise<ProcessState[]>`

Reset the restart counter for one or more processes. Defaults to `"all"`.

```ts
await bm2.reset("api");
await bm2.reset();            // Reset all
```

---

### Introspection

#### `bm2.list(): Promise<ProcessState[]>`

List all managed processes with their current state.

```ts
const processes = await bm2.list();
for (const proc of processes) {
  console.log(`${proc.name} [${proc.status}] PID=${proc.pid} CPU=${proc.cpu}%`);
}
```

#### `bm2.describe(target: string | number): Promise<ProcessState[]>`

Get detailed information about a specific process or process group.

```ts
const details = await bm2.describe("api");
console.log(details[0]);
```

---

### Logs

#### `bm2.logs(target?: string | number, lines?: number): Promise<Array<{ name: string; id: number; out: string; err: string }>>`

Retrieve recent log lines for one or all processes. Defaults to `"all"` with `20` lines.

```ts
const logs = await bm2.logs("api", 100);
for (const entry of logs) {
  console.log(`[${entry.name}] stdout:\n${entry.out}`);
  if (entry.err) console.error(`[${entry.name}] stderr:\n${entry.err}`);
}
```

#### `bm2.flush(target?: string | number): Promise<void>`

Truncate log files for one or all processes.

```ts
await bm2.flush("api");      // Flush logs for "api"
await bm2.flush();            // Flush all logs
```

---

### Programmatic Monitoring and Metrics

#### `bm2.metrics(): Promise<MetricSnapshot>`

Take a single metrics snapshot containing process-level and system-level telemetry.

```ts
const snapshot = await bm2.metrics();
console.log(`System CPU: ${snapshot.system.cpu}%`);
for (const proc of snapshot.processes) {
  console.log(`  ${proc.name}: ${proc.memory} bytes, ${proc.cpu}% CPU`);
}
```

#### `bm2.metricsHistory(seconds?: number): Promise<MetricSnapshot[]>`

Retrieve historical metric snapshots from the daemon's in-memory ring buffer. The `seconds` parameter controls the look-back window and defaults to `300` (5 minutes). The daemon retains up to 1 hour of per-second snapshots.

```ts
const history = await bm2.metricsHistory(600);   // Last 10 minutes
console.log(`Got ${history.length} snapshots`);
```

#### `bm2.prometheus(): Promise<string>`

Get the current metrics formatted as a Prometheus exposition text string.

```ts
const text = await bm2.prometheus();
console.log(text);
// # HELP bm2_process_cpu CPU usage percentage
// # TYPE bm2_process_cpu gauge
// bm2_process_cpu{name="api-0",id="0"} 1.2
// ...
```

#### `bm2.startPolling(intervalMs?: number): void`

Start polling the daemon for metrics at a fixed interval and emitting `"metrics"` events. Defaults to `2000` ms. Calling this again replaces the existing polling timer.

```ts
bm2.on("metrics", (snapshot) => {
  console.log(`${snapshot.processes.length} processes running`);
});
bm2.startPolling(1000);       // Poll every second
```

#### `bm2.stopPolling(): void`

Stop the metrics polling loop.

```ts
bm2.stopPolling();
```

---

### Persistence

#### `bm2.save(): Promise<void>`

Persist the current process list to `~/.bm2/dump.json` so it can be restored later.

```ts
await bm2.save();
```

#### `bm2.resurrect(): Promise<ProcessState[]>`

Restore previously saved processes from `~/.bm2/dump.json`.

```ts
const restored = await bm2.resurrect();
console.log(`Restored ${restored.length} processes`);
```

---

### Dashboard Control

#### `bm2.dashboard(port?: number, metricsPort?: number): Promise<{ port: number; metricsPort: number }>`

Start the web dashboard. Defaults to port `9615` for the dashboard and `9616` for the Prometheus metrics endpoint.

```ts
const { port, metricsPort } = await bm2.dashboard(8080, 8081);
console.log(`Dashboard: http://localhost:${port}`);
console.log(`Metrics:   http://localhost:${metricsPort}/metrics`);
```

#### `bm2.dashboardStop(): Promise<void>`

Stop the web dashboard.

```ts
await bm2.dashboardStop();
```

---

### Module Management

#### `bm2.moduleInstall(nameOrPath: string): Promise<{ path: string }>`

Install a BM2 module from a git URL, local path, or npm package name.

```ts
const result = await bm2.moduleInstall("bm2-prometheus-pushgateway");
console.log(`Installed to ${result.path}`);
```

#### `bm2.moduleUninstall(name: string): Promise<void>`

Uninstall a BM2 module.

```ts
await bm2.moduleUninstall("bm2-prometheus-pushgateway");
```

#### `bm2.moduleList(): Promise<Array<{ name: string; version: string }>>`

List all installed modules.

```ts
const modules = await bm2.moduleList();
for (const mod of modules) {
  console.log(`${mod.name}@${mod.version}`);
}
```

---

### Daemon Lifecycle

#### `bm2.ping(): Promise<{ pid: number; uptime: number }>`

Ping the daemon and return its PID and uptime in milliseconds.

```ts
const info = await bm2.ping();
console.log(`Daemon PID ${info.pid}, up for ${Math.round(info.uptime / 1000)}s`);
```

#### `bm2.kill(): Promise<void>`

Kill the daemon and all managed processes. Cleans up the socket and PID files. The daemon connection will not respond after this call, which is expected.

```ts
await bm2.kill();
console.log(bm2.connected); // false
```

#### `bm2.daemonReload(): Promise<string>`

Reload the daemon server itself without killing managed processes.

```ts
const result = await bm2.daemonReload();
console.log(result);
```

---

### Low-Level Transport

#### `bm2.send(message: DaemonMessage): Promise<DaemonResponse>`

Send an arbitrary message to the daemon over the Unix socket and return the raw response. This is useful for custom command types, future extensions, or direct daemon interaction.

```ts
const response = await bm2.send({ type: "ping" });
console.log(response);
// { success: true, data: { pid: 12345, uptime: 60000 }, id: "abc123" }
```

Messages are JSON objects with a `type` field for routing and an optional `id` field for request-response correlation (auto-generated if omitted). The `data` field carries command-specific payload.

---

### Events

The `BM2` class extends `EventEmitter` and emits the following typed events:

| Event | Payload | Description |
|---|---|---|
| `daemon:connected` | — | Daemon connection established |
| `daemon:disconnected` | — | Client disconnected from daemon |
| `daemon:launched` | `pid: number` | Daemon was spawned by this client |
| `daemon:killed` | — | Daemon was killed via `kill()` |
| `error` | `error: Error` | Transport or polling error |
| `process:start` | `processes: ProcessState[]` | Process(es) started |
| `process:stop` | `processes: ProcessState[]` | Process(es) stopped |
| `process:restart` | `processes: ProcessState[]` | Process(es) restarted |
| `process:reload` | `processes: ProcessState[]` | Process(es) reloaded |
| `process:delete` | `processes: ProcessState[]` | Process(es) deleted |
| `process:scale` | `processes: ProcessState[]` | Process group scaled |
| `metrics` | `snapshot: MetricSnapshot` | Metrics snapshot received |
| `log:data` | `logs: Array<{ name, id, out, err }>` | Log data retrieved |

```ts
const bm2 = new BM2();

bm2.on("daemon:connected", () => console.log("Connected!"));
bm2.on("daemon:disconnected", () => console.log("Disconnected"));
bm2.on("process:start", (procs) => {
  console.log("Started:", procs.map((p) => p.name).join(", "));
});
bm2.on("process:stop", (procs) => {
  console.log("Stopped:", procs.map((p) => p.name).join(", "));
});
bm2.on("error", (err) => console.error("BM2 error:", err.message));
bm2.on("metrics", (snapshot) => {
  console.log(`${snapshot.processes.length} processes, system CPU ${snapshot.system.cpu}%`);
});

await bm2.connect();
```

---

### Error Handling

All methods that communicate with the daemon throw a `BM2Error` when the daemon returns a failure response. The error includes the command that failed and the full daemon response for inspection.

```ts
import { BM2Error } from "bm2";

try {
  await bm2.describe("nonexistent");
} catch (err) {
  if (err instanceof BM2Error) {
    console.error(`Command "${err.command}" failed: ${err.message}`);
    console.error("Full response:", err.response);
  }
}
```

Transport-level errors (daemon unreachable, socket closed) throw standard `Error` instances.

#### `BM2Error` Properties

| Property | Type | Description |
|---|---|---|
| `message` | `string` | Human-readable error message |
| `command` | `string` | The daemon command type that failed |
| `response` | `DaemonResponse` | The full response object from the daemon |

---

### Direct ProcessManager Usage

For in-process usage without a running daemon, you can use the `ProcessManager` class directly. This is useful for embedding BM2 into your own application or for custom tooling.

```ts
import { ProcessManager } from "bm2/process-manager";
import { Dashboard } from "bm2/dashboard";

const pm = new ProcessManager();

// Start a process
const states = await pm.start({
  name: "my-api",
  script: "./server.ts",
  instances: 4,
  execMode: "cluster",
  port: 3000,
  env: { NODE_ENV: "production" },
  maxMemoryRestart: "512M",
  healthCheckUrl: "http://localhost:3000/health",
});

console.log("Started:", states.map((s) => `${s.name} (pid: ${s.pid})`));

// List processes
const list = pm.list();

// Get metrics
const metrics = await pm.getMetrics();

// Scale
await pm.scale("my-api", 8);

// Graceful reload
await pm.reload("my-api");

// Start the web dashboard
const dashboard = new Dashboard(pm);
dashboard.start(9615, 9616);

// Get Prometheus-format metrics
const promText = pm.getPrometheusMetrics();

// Save and restore
await pm.save();
await pm.resurrect();

// Stop everything
await pm.stopAll();
```

The `ProcessManager` provides the same process management capabilities but runs in-process rather than communicating with a daemon. Use the `BM2` client class for the standard daemon-based workflow, and `ProcessManager` when you need direct, embedded control.

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                      BM2 CLI                            │
│  (bm2 start, bm2 list, bm2 restart, bm2 dashboard)    │
└────────────────────────┬────────────────────────────────┘
                         │ Unix Socket (WebSocket)
                         │ ~/.bm2/daemon.sock
                         ▼
┌─────────────────────────────────────────────────────────┐
│                    BM2 Daemon                           │
│                                                         │
│  ┌─────────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │ Process Manager  │  │   Dashboard  │  │  Modules  │  │
│  │                 │  │  (Bun.serve) │  │  (Plugins)│  │
│  │  ┌───────────┐  │  │  HTTP + WS   │  └───────────┘  │
│  │  │ Container │  │  │  REST API    │                  │
│  │  │ (Bun.spawn)│  │  └──────────────┘                 │
│  │  └───────────┘  │                                    │
│  │  ┌───────────┐  │  ┌──────────────┐  ┌───────────┐  │
│  │  │ Container │  │  │   Monitor    │  │  Metrics  │  │
│  │  │ (Bun.spawn)│  │  │  CPU/Memory │  │ Prometheus│  │
│  │  └───────────┘  │  └──────────────┘  │  :9616    │  │
│  │  ┌───────────┐  │                    └───────────┘  │
│  │  │ Container │  │  ┌──────────────┐                  │
│  │  │ (Bun.spawn)│  │  │ Health Check │                 │
│  │  └───────────┘  │  │  HTTP Probes │                  │
│  └─────────────────┘  └──────────────┘                  │
│                                                         │
│  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌─────────────┐  │
│  │  Cluster │ │   Logs   │ │  Cron  │ │   Deploy    │  │
│  │  Manager │ │ Manager  │ │Manager │ │   Manager   │  │
│  └──────────┘ └──────────┘ └────────┘ └─────────────┘  │
└─────────────────────────────────────────────────────────┘
```

**Daemon Process** — The daemon is a long-running Bun process that manages all child processes. It listens on a Unix domain socket at `~/.bm2/daemon.sock` for commands from the CLI. The daemon is automatically started when you first run a BM2 command and can be explicitly killed with `bm2 kill`.

**Process Container** — Each managed process is wrapped in a ProcessContainer that handles spawning via `Bun.spawn`, log piping, monitoring, restart logic, health checking, watch mode, and signal handling.

**IPC Protocol** — The CLI and daemon communicate over WebSocket on a Unix socket. Messages are JSON-encoded with a `type` field for routing and an `id` field for request-response correlation.

**Dashboard** — The dashboard is served by a `Bun.serve` instance with WebSocket upgrade support. A single HTTP server handles the dashboard UI, REST API, and WebSocket connections.

**Metrics Server** — A separate `Bun.serve` instance on port 9616 serves Prometheus metrics, keeping the scrape endpoint isolated from dashboard traffic.

---

## Comparison with PM2

| Feature | PM2 | BM2 |
|---|---|---|
| Runtime | Node.js | Bun |
| Language | JavaScript | TypeScript |
| Dependencies | ~40+ packages | Zero (Bun built-ins only) |
| Process Spawning | `child_process.fork` | `Bun.spawn` |
| IPC | Custom protocol over pipes | WebSocket over Unix socket |
| HTTP Server | Express/http | `Bun.serve` |
| Log Compression | External `pm2-logrotate` module | Built-in `Bun.gzipSync` |
| Dashboard | PM2 Plus (paid) or `pm2-monit` | Built-in web dashboard (free) |
| Prometheus Metrics | `pm2-prometheus-exporter` module | Built-in native export |
| Startup Time | ~500ms | ~50ms |
| Memory Overhead | ~40MB (daemon) | ~12MB (daemon) |
| Cluster Mode | `cluster` module | `Bun.spawn` with env-based routing |
| Ecosystem Files | JSON, JS, YAML | JSON, TypeScript |
| Deploy System | Built-in | Built-in |
| Module System | `pm2 install` | `bm2 module install` |
| TypeScript | Requires compilation | Native support |
| File Watching | `chokidar` | Native `fs.watch` |
| Docker / Foreground Mode | `--no-daemon` flag | `--no-daemon` / `-d` flag |

---

## Recipes and Examples

### Basic HTTP Server

```
bm2 start server.ts --name api
```

### Production API with Clustering and Health Checks

```
bm2 start server.ts \
  --name api \
  --instances max \
  --port 3000 \
  --max-memory-restart 512M \
  --health-check-url http://localhost:3000/health \
  --health-check-interval 15000 \
  --log-max-size 50M \
  --log-retain 10 \
  --log-compress
```

### Development Mode with Watch

```
bm2 start server.ts --name dev-api --watch --ignore-watch node_modules,.git,dist
```

### Python Script

```
bm2 start worker.py --name py-worker --interpreter python3
```

### Scheduled Restart (Daily at 3 AM)

```
bm2 start server.ts --name api --cron "0 3 * * *"
```

### Multiple Environments via Ecosystem

```
{
  "apps": [
    {
      "name": "api-staging",
      "script": "./server.ts",
      "env": { "NODE_ENV": "staging", "PORT": "3000" }
    },
    {
      "name": "api-production",
      "script": "./server.ts",
      "env": { "NODE_ENV": "production", "PORT": "8080" }
    }
  ]
}
```

### Docker Container (Foreground Mode)

```dockerfile
FROM oven/bun:latest
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun add -g bm2
CMD ["bm2", "start", "--no-daemon", "./server.ts"]
```

### Full Production Setup

```
bm2 start ecosystem.config.json
bm2 save
bm2 startup install
bm2 dashboard
bm2 list
```

### Monitoring with Prometheus and Grafana

```
bm2 dashboard --metrics-port 9616
curl http://localhost:9616/metrics
```

Then add the target to your `prometheus.yml` and import the Grafana dashboard.

### Zero-Downtime Deploy

```
bm2 deploy ecosystem.config.json production
```

Or manually:

```
git pull origin main
bun install
bm2 reload all
```

### Programmatic Monitoring Service

```ts
import BM2 from "bm2";

const bm2 = new BM2();
await bm2.connect();

// Alert when any process uses more than 512 MB
bm2.on("metrics", (snapshot) => {
  for (const proc of snapshot.processes) {
    if (proc.memory > 512 * 1024 * 1024) {
      console.warn(`⚠️  ${proc.name} using ${Math.round(proc.memory / 1024 / 1024)} MB`);
    }
  }
});

bm2.startPolling(5000);

// Keep running
process.on("SIGINT", async () => {
  bm2.stopPolling();
  await bm2.disconnect();
  process.exit(0);
});
```

### Programmatic Deploy Pipeline

```ts
import BM2 from "bm2";

const bm2 = new BM2();
await bm2.connect();

// Deploy new code, then reload
console.log("Reloading all processes...");
const reloaded = await bm2.reload("all");
console.log(`Reloaded ${reloaded.length} processes`);

// Verify everything is healthy
const processes = await bm2.list();
const allOnline = processes.every((p) => p.status === "online");

if (allOnline) {
  console.log("✅ All processes online");
  await bm2.save();
} else {
  console.error("❌ Some processes failed to come online");
  const failed = processes.filter((p) => p.status !== "online");
  for (const p of failed) {
    console.error(`  ${p.name}: ${p.status}`);
  }
}

await bm2.disconnect();
```

---

## Troubleshooting

### Daemon won't start

If BM2 commands hang or return connection errors, the daemon may have died without cleanup.

```
rm -f ~/.bm2/daemon.sock ~/.bm2/daemon.pid
bm2 list
```

### Process keeps restarting

Check the error logs for crash information:

```
bm2 logs my-app --err --lines 100
```

If the process exits too quickly, it may hit the max restart limit. Check `minUptime` and `maxRestarts` settings:

```
bm2 describe my-app
```

Reset the counter if needed:

```
bm2 reset my-app
```

### High memory usage

If a process is using excessive memory and you have `maxMemoryRestart` configured, BM2 will restart it automatically. You can also check the metrics history:

```
bm2 metrics --history 3600
```

### Port conflicts

In cluster mode, each instance uses `basePort + instanceIndex`. Ensure no other services are using those ports:

```
lsof -i :3000-3007
```

### Log files growing too large

Enable log rotation:

```
bm2 start server.ts --log-max-size 50M --log-retain 5 --log-compress
```

Or flush existing logs:

```
bm2 flush my-app
```

### Dashboard not accessible

Ensure the dashboard is started and check the port:

```
bm2 dashboard --port 9615
curl http://localhost:9615
```

If running behind a firewall, ensure port 9615 (dashboard) and 9616 (metrics) are open.

### Checking daemon health

```
bm2 ping
```

This returns the daemon PID and uptime. If it doesn't respond, the daemon needs to be restarted.

### Container exits immediately

If your Docker container exits right after starting, you are likely missing `--no-daemon`. Without it, BM2 daemonizes and the foreground process exits, causing Docker to stop the container.

```dockerfile
# ❌ Wrong — BM2 daemonizes and the container exits
CMD ["bm2", "start", "./server.ts"]

# ✅ Correct — BM2 stays in the foreground
CMD ["bm2", "start", "--no-daemon", "./server.ts"]
```

---

## File Structure

BM2 stores all data in `~/.bm2/`:

```
~/.bm2/
├── daemon.sock          # Unix domain socket for IPC
├── daemon.pid           # Daemon process ID
├── dump.json            # Saved process list (bm2 save)
├── config.json          # Global configuration
├── env-registry.json    # Stored environment variables
├── logs/                # Process log files
│   ├── my-api-0-out.log
│   ├── my-api-0-error.log
│   ├── my-api-0-out.log.1.gz
│   └── daemon-out.log
├── pids/                # PID files
│   └── my-api-0.pid
├── metrics/             # Persisted metric snapshots
└── modules/             # Installed BM2 modules
```

---

## Contributing

Contributions are welcome. Please follow these guidelines:

1. Fork the repository and create a feature branch.
2. Write tests for new functionality.
3. Follow the existing code style — TypeScript strict mode, no `any` where avoidable.
4. Run the test suite before submitting: `bun test`.
5. Submit a pull request with a clear description of the change.

### Development Setup

```
git clone https://github.com/aspect-dev/bm2.git
cd bm2
bun install
bun run src/index.ts list
bun test
```

---

## License

GPL-3.0-only

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

**Built with ❤️ by the [MaxxPainn Team](https://maxxpainn.com)**
📧 Support: [zak@maxxpainn.com](mailto:zak@maxxpainn.com)

bm2

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README