ProcBoss

https://docs.procboss.com/
Admin
ProcBoss (pboss) is a runtime-agnostic, open-source process manager for Bun, Node.js, and Deno, with...
Tokens:79,378
Snippets:624
Trust Score:3.2
Update:3 hours ago
Show doc for...
Tokens:
Raw
### pboss setup and start example

Source: https://docs.procboss.com/cli/startup/

Shows the one-time installation and subsequent usage of pboss. After installation, all processes are persisted automatically.

```bash
# the whole setup, once, at install time:
bun add -g pboss

# then just use pboss — everything is persisted from here on:
pboss start ecosystem.config.json
```

--------------------------------

### Full production setup: pboss start, save, startup install, dashboard, list

Source: https://docs.procboss.com/recipes/

Starts the whole topology, persists it, installs the boot service, and opens the dashboard. After a reboot, systemd/launchd/Task Scheduler starts the daemon and processes resurrect automatically.

```bash
pboss start ecosystem.config.json
pboss save
pboss startup install
pboss dashboard
pboss list
```

--------------------------------

### Recommended boot setup commands

Source: https://docs.procboss.com/cli/ecosystem/

Run these commands to start the ecosystem, save the process list, and install startup scripts. On reboot, systemd/launchd/Task Scheduler starts the pboss daemon and automatically resurrects processes.

```bash
pboss start ecosystem.config.json
pboss save
pboss startup install
```

--------------------------------

### Clone and Setup pboss Repository

Source: https://docs.procboss.com/architecture/

Commands to clone the pboss repository, install dependencies with Bun, run the CLI, and execute tests. Use this to set up the development environment.

```bash
git clone https://github.com/procboss/pboss.git
cd pboss
bun install
bun run src/index.ts list
bun test
```

--------------------------------

### pboss startup install command

Source: https://docs.procboss.com/cli/startup/

Installs and starts the boot startup service as the current user. On Linux it writes a per-user systemd unit and enables linger; on macOS it loads a launchd LaunchAgent; on Windows it registers a Scheduled Task or falls back to a Registry Run key. Running under sudo is rejected.

```bash
pboss startup install
```

--------------------------------

### Use custom interpreter with pboss start

Source: https://docs.procboss.com/cli/processes/

Specifies a custom interpreter binary and arguments. This example uses `deno run -A` as the interpreter.

```bash
pboss start server.ts --interpreter "deno run -A" --name deno-api
```

--------------------------------

### Survive a reboot with pboss start and startup status

Source: https://docs.procboss.com/quickstart/

The default behavior: pboss saves the process list automatically and resurrects apps on boot. The first start shows persistence status. The startup status command is read-only and shows service installation and what a reboot would restore.

```bash
pboss start my-api.ts   # saved automatically, resurrected at every boot
```

```bash
pboss startup status    # read-only: service installed? daemon up? what a
                        # reboot would restore
```

--------------------------------

### Namespace boundaries example output

Source: https://docs.procboss.com/cli/ecosystem/

Example output showing how apps with and without namespaces are reported after a start sweep. Standalone apps are unaffected, namespace members are rolled back or failed, and other namespaces remain online.

```text
api                     online   (standalone — unaffected)
shop
├── shop-api            rolled back
├── shop-worker         rolled back
└── shop-scheduler      failed
admin
├── admin-api           online   (other namespace — unaffected)
└── admin-worker        online
```

--------------------------------

### Start with ecosystem.config.json

Source: https://docs.procboss.com/cli/ecosystem/

Starts the application using the ecosystem.config.json file. Relative script paths resolve against the file's directory.

```bash
pboss start ecosystem.config.json
```

--------------------------------

### pboss start with --env-file

Source: https://docs.procboss.com/cli/env/

Load environment variables from a .env-style file at start. Natural for twelve-factor deployments: keep the file out of git and load it at start.

```bash
pboss start server.ts --env-file .env.production
```

--------------------------------

### One-line installer for Linux/macOS

Source: https://docs.procboss.com/installation/

Installs pboss on Linux or macOS. The installer will ask for the runtime if not provided.

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

--------------------------------

### Install pboss via Deno

Source: https://docs.procboss.com/

Install the pboss CLI globally using Deno's installer with specific flags for permissions and cache.

```bash
deno install -g -A --min-dep-age=0 --name pboss --reload --force npm:pboss/deno-entry
```

--------------------------------

### Start with ecosystem.config.ts

Source: https://docs.procboss.com/cli/ecosystem/

Starts the application using the TypeScript ecosystem file.

```bash
pboss start ecosystem.config.ts
```

--------------------------------

### Run Bun applications with pboss

Source: https://docs.procboss.com/runtimes/

Commands to start a TypeScript/JS/JSX app with Bun, which is the default runtime when installed. Use --node-args to pass Bun flags.

```bash
# TypeScript, JS, JSX — bun runs them all natively
pboss start server.ts --name bun-api

# Pass Bun flags
pboss start server.ts --node-args "--smol"
```

--------------------------------

### Docker CMD examples for pboss start (wrong and correct)

Source: https://docs.procboss.com/troubleshooting/

Shows the wrong and correct Docker CMD instructions. The wrong one omits --no-daemon, causing the container to exit because pboss daemonizes. The correct one uses --no-daemon to keep pboss in the foreground.

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

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

--------------------------------

### Namespace startup failure rollback output

Source: https://docs.procboss.com/cli/processes/

Example output when a namespace startup fails. The primary error is reported, followed by rollback results for members started by that invocation.

```text
namespace "my-app" startup failed: Script not found: ./worker.ts
Rollback: ✓ api stopped, ✓ web stopped
```

--------------------------------

### Check pboss runtime with 'pboss runtime'

Source: https://docs.procboss.com/troubleshooting/

Use this command to see the full picture of the runtime: configured, executing, and install details. It also prints the install flavor, such as 'package install running on the system Node.js runtime'.

```bash
pboss runtime      # Configured / Executing / Install — the full picture
```

--------------------------------

### Start a process with pboss

Source: https://docs.procboss.com/quickstart/

Spawns a daemon if needed, starts the script under supervision, and restarts it automatically if it crashes.

```bash
pboss start app.ts
```

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

--------------------------------

### Install pboss via Bun

Source: https://docs.procboss.com/

Install the pboss CLI globally using Bun's package manager.

```bash
bun add -g pboss
```

--------------------------------

### pboss startup status - check boot persistence

Source: https://docs.procboss.com/cli/startup/

Read-only command that reports boot persistence without starting, installing, or changing anything. Output shows service details, linger status, daemon socket, and reboot persistence. When the service is missing, it prints the exact install command; when nothing is saved, it says so. The socket and dump are read from the home the daemon uses (PBOSS_HOME wins, otherwise ~/.pboss).

```bash
pboss startup status
```

```text
Boot startup service (systemd, per-user)
  Service:    /home/ra/.config/systemd/user/pboss.service
  Installed:  yes
  Enabled:    yes — starts with your session (default.target)
  Active:     active
  Linger:     on — the daemon starts at BOOT, before login
  Daemon:     reachable (pid 1234) at /home/ra/.pboss/daemon.sock

Reboot persistence:
  Dump:       /home/ra/.pboss/dump.json
  On boot:    3 process(es) come back running, 1 stopped
```

--------------------------------

### Verify pboss installation

Source: https://docs.procboss.com/installation/

Run these commands to check the installed version and the configured runtime. If 'pboss' is not found, ensure the install directory is on your PATH.

```bash
pboss --version
pboss runtime
```

--------------------------------

### Start a new process with pboss start

Source: https://docs.procboss.com/cli/processes/

Starts a new process from a script file. The process name defaults to the script filename.

```bash
pboss start server.ts
```

--------------------------------

### Enable log rotation with pboss start

Source: https://docs.procboss.com/troubleshooting/

Starts an app with log rotation enabled: max log size 50M, retain 5 files, and compression.

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

--------------------------------

### Error when no config or application found

Source: https://docs.procboss.com/cli/ecosystem/

Output shown when pboss start cannot find a config file or application to start.

```text
No PBoss configuration file or application was found.

Please provide a config file, executable script, or application to start.
```

--------------------------------

### One-line installer with explicit runtime for Linux/macOS

Source: https://docs.procboss.com/installation/

Installs pboss on Linux or macOS with a specific runtime. Use `--runtime=node`, `--runtime=bun`, or `--runtime=deno` to avoid the interactive prompt.

```bash
curl -fsSL https://procboss.com/install.sh | sh -s -- --runtime=node
```

```bash
curl -fsSL https://procboss.com/install.sh | sh -s -- --runtime=bun
```

```bash
curl -fsSL https://procboss.com/install.sh | sh -s -- --runtime=deno
```

--------------------------------

### pboss module install - install from git, local path, or npm

Source: https://docs.procboss.com/cli/modules/

Install a module from a git URL, a local path, or an npm package name. The command is `pboss module install` followed by the source.

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

--------------------------------

### Install pboss via npm

Source: https://docs.procboss.com/

Install the pboss CLI globally using npm for Node.js.

```bash
npm install -g pboss
```

--------------------------------

### One-line installer for Windows PowerShell

Source: https://docs.procboss.com/installation/

Installs pboss on Windows without Administrator. Accepts `-Runtime node|bun|deno` to select the runtime.

```powershell
powershell -c "irm https://procboss.com/install.ps1 | iex"
```

--------------------------------

### Start process with dependency failure handling

Source: https://docs.procboss.com/guide/programmatic-api/

Starts a process with a dependency on 'postgresql'. If the dependency is not running, a PBossError is thrown with structured failure details in err.response.dependencyFailure.

```javascript
try {
  await pboss.start({ script: "./api.ts", name: "api", dependsOn: ["postgresql"] });
} catch (err) {
  // err.response.dependencyFailure:
  // { process: "api", dependency: "postgresql", provider: "systemd",
  //   service: "postgresql.service", state: "inactive",
  //   reason: "dependency_not_running" }
}
```

--------------------------------

### Start cluster with 4 instances

Source: https://docs.procboss.com/cli/cluster/

Starts a cluster with exactly 4 instances for the server.ts file, using the name 'api'.

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

--------------------------------

### pboss.startEcosystem(config)

Source: https://docs.procboss.com/guide/programmatic-api/

Starts an ecosystem with atomic namespace groups.

```APIDOC
## pboss.startEcosystem(config)

### Description
Starts an ecosystem. Standalone apps are independent, each namespace is one atomic group.

### Method
startEcosystem

### Endpoint
pboss.startEcosystem(config)

### Parameters
#### Request Body
- **config** (object) - Required - Ecosystem configuration.

### Response
#### Success Response
- **Promise** - Resolves when the ecosystem is started.
```

--------------------------------

### Deno install with explicit permissions

Source: https://docs.procboss.com/installation/

Recommended install command granting the exact permission set pboss needs: --allow-run, --allow-read, --allow-write, --allow-net, --allow-env, --allow-sys.

```bash
deno install -g --min-dep-age=0 --name pboss --reload --force --allow-run --allow-read --allow-write --allow-net --allow-env --allow-sys npm:pboss/deno-entry
```

--------------------------------

### pboss.start(options)

Source: https://docs.procboss.com/guide/programmatic-api/

Starts a process with options, including dependency-aware resolution and namespace member exit policy.

```APIDOC
## pboss.start(options)

### Description
Starts a process with the given options. It is dependency-aware: dependencies are resolved before the process spawns. Accepts `onNsMemberExit` option for namespace member exit behavior.

### Method
start

### Endpoint
pboss.start(options)

### Parameters
#### Request Body
- **options** (object) - Required - Options for starting the process.
  - **script** (string) - Required - Path to the script to run.
  - **name** (string) - Optional - Name of the process.
  - **dependsOn** (array) - Optional - List of dependencies, each can be a string or an object with `name` and `policy` (e.g., `{ name: "metrics", policy: "optional" }`).
  - **onNsMemberExit** (string) - Optional - `"ignore"` or `"exit"`.

### Request Example
```javascript
await pboss.start({ script: "./api.ts", name: "api", dependsOn: ["postgresql"] });
```

### Response
#### Success Response
- **Promise** - Resolves when the process starts.

#### Error Response
- **PBossError** - Thrown if a dependency is not running. The error has a `response.dependencyFailure` property with structured facts.

#### Error Example
```javascript
try {
  await pboss.start({ script: "./api.ts", name: "api", dependsOn: ["postgresql"] });
} catch (err) {
  // err.response.dependencyFailure:
  // { process: "api", dependency: "postgresql", provider: "systemd",
  //   service: "postgresql.service", state: "inactive",
  //   reason: "dependency_not_running" }
}
```
```

--------------------------------

### pboss deploy setup command

Source: https://docs.procboss.com/cli/deploy/

Initializes the remote server by creating the directory structure and cloning the repository. The command takes the ecosystem file and the environment name (e.g., production).

```bash
pboss deploy ecosystem.config.json production setup
```

--------------------------------

### Pass arguments to script with pboss start

Source: https://docs.procboss.com/cli/processes/

Arguments after `--` are passed through to the script. This example sets the process name and passes `--port` and `--host` to the script.

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

--------------------------------

### Language quick starts for pboss

Source: https://docs.procboss.com/recipes/

Shows how to start servers with different runtimes: TypeScript (auto-detected), Node.js pinned, and Deno with a scoped permission set. Each command uses the --name flag to label the process.

```bash
# TypeScript server — runs on Bun, Deno, or Node (via tsx) per the chain
pboss start server.ts --name ts-api

# Node.js server, pinned
pboss start server.js --interpreter node --name node-api

# Deno server, pinned, with a scoped permission set
pboss start server.ts --interpreter "deno run --allow-net" --name deno-api
```

--------------------------------

### Distinct ports server example (Bun, Node, Deno)

Source: https://docs.procboss.com/cli/cluster/

Portable strategy: each worker gets basePort + workerIndex via --port. Works under Bun, Node, and Deno.

```typescript
// server.ts — works under Bun, Node, and Deno
const workerId = parseInt(process.env.PBOSS_WORKER_ID || "0");
const port = parseInt(process.env.PORT || "3000");

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

--------------------------------

### Run Procboss benchmarks: clone, install, and execute

Source: https://docs.procboss.com/benchmarks/

Clone the benchmarks repository, navigate to the desired runtime directory (node, bun, or deno), install dependencies, and run the benchmark script. The script regenerates the REPORT from the raw data it measures.

```bash
git clone https://github.com/Procboss/benchmarks
cd benchmarks/node   # or benchmarks/bun, benchmarks/deno
npm install
bash scripts/benchmark.sh
```

--------------------------------

### Position-independent flags with pboss start

Source: https://docs.procboss.com/cli/processes/

Flags can appear anywhere relative to the script path. These examples show `--no-daemon` and `--name` placed before, after, or mixed with the script path.

```bash
pboss start --no-daemon app.ts
pboss start app.ts --no-daemon
pboss start --name api --no-daemon app.ts --watch
```

--------------------------------

### Automatic saving examples

Source: https://docs.procboss.com/cli/startup/

Shows that `pboss start` and `pboss delete` automatically save the process list to `~/.pboss/dump.json`. The comment notes that a deleted process won't resurrect after reboot.

```bash
pboss start app.ts            # saved automatically
pboss delete app              # saved automatically (it won't resurrect)
```

--------------------------------

### Build from source with Bun

Source: https://docs.procboss.com/installation/

Clone the repository, install dependencies with Bun, and run the version command. Bun is the development toolchain; the built bundle also runs under Node and Deno.

```bash
git clone https://github.com/procboss/pboss.git
cd pboss
bun install
bun run src/index.ts --version
```

--------------------------------

### Docker CMD with ecosystem file

Source: https://docs.procboss.com/guide/docker/

Example of using an ecosystem file with --no-daemon. Ecosystem file support behaves identically to normal mode; all apps entries are started and supervised in-process.

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

--------------------------------

### Manual zero-downtime deploy: git pull, bun install, pboss reload all

Source: https://docs.procboss.com/recipes/

Manually updates the codebase and reloads all processes. reload cycles workers one at a time, bringing new instances up before old ones get SIGTERM.

```bash
git pull origin main
bun install
pboss reload all
```

--------------------------------

### pboss start with log rotation options

Source: https://docs.procboss.com/cli/logs/

Starts a process with custom log rotation settings: `--log-max-size` sets the threshold (default 10 MB), `--log-retain` sets the number of rotated files to keep (default 5), and `--log-compress` enables gzip compression of rotated files using the runtime's native compression (Bun.gzipSync under Bun, node:zlib under Node and Deno).

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

--------------------------------

### Ecosystem config with dependsOn field

Source: https://docs.procboss.com/cli/ecosystem/

Example ecosystem configuration showing the dependsOn field to define dependency ordering. The apps array declares worker, api, and postgres with dependencies, and pboss start ecosystem.config.json brings the chain up postgres → api → worker.

```javascript
module.exports = {
  apps: [
    { name: "worker", script: "./worker.ts", dependsOn: ["api"] },   // declared first…
    { name: "api", script: "./api.ts", dependsOn: ["postgres"] },    // …starts second…
    { name: "postgres", script: "./postgres-wrapper.ts" },           // …starts first
  ],
};
```

--------------------------------

### Start with dependencies via CLI

Source: https://docs.procboss.com/cli/processes/

Shows the CLI forms for starting a process with dependencies: pboss start worker resolves the dependency graph, and pboss start api.ts --name api --depends-on postgres,redis uses the CLI flag.

```bash
pboss start worker     # starts postgres → api → worker, in that order
pboss start api.ts --name api --depends-on postgres,redis   # CLI form
```

--------------------------------

### Remote directory structure created by setup

Source: https://docs.procboss.com/cli/deploy/

Shows the directory layout created on the remote server after running the setup command. Includes source/, releases/ with timestamped directories, a current symlink, and shared/.

```text
/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/
```

--------------------------------

### JSON ecosystem configuration example

Source: https://docs.procboss.com/cli/ecosystem/

Defines multiple apps (api, worker, scheduler) with settings like instances, execMode, env, health checks, logging, and cron. Includes a deploy section for production with preDeploy and postDeploy commands.

```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 && pboss reload ecosystem.config.json --env production"
    }
  }
}
```

--------------------------------

### Bun: One-off command to check pboss version without installing

Source: https://docs.procboss.com/troubleshooting/

Use this command to run pboss once without installing it globally, useful when Bun's global install is failing due to corrupted state.

```bash
bunx --bun pboss --version
```

--------------------------------

### Start dashboard and verify with curl

Source: https://docs.procboss.com/troubleshooting/

Starts the dashboard on port 9615 and checks that it responds on localhost.

```bash
pboss dashboard --port 9615
curl http://localhost:9615
```

--------------------------------

### Docker CMD with additional options

Source: https://docs.procboss.com/guide/docker/

Example of running pboss in foreground mode with additional options like --name and --instances.

```dockerfile
CMD ["pboss", "start", "--no-daemon", "--name", "api", "--instances", "2", "./server.ts"]
```
Tokens:
Raw