Foreground mode & Docker

By default, pboss 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 pboss daemonizes and exits, the container stops.

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

• No background daemon is spawned.
• The pboss 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#

Usage#

# Foreground — blocks until the process exits
pboss start --no-daemon server.ts

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

Docker#

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

Dockerfile

FROM oven/bun:latest

WORKDIR /app

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

COPY . .

# Install pboss globally
RUN bun add -g pboss

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

The same container on Node.js or Deno#

pboss installs and runs through whatever runtime the image already has — swap the base image and the package manager, keep everything else:

FROM node:22-slim

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .

RUN npm install -g pboss

CMD ["pboss", "start", "--no-daemon", "./server.js"]

Docker logs and log files#

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

CMD ["pboss", "start", "--no-daemon", "--raw", "ecosystem.config.cjs"]

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

With additional options

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

With an ecosystem file

CMD ["pboss", "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#

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

Kubernetes#

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

Behavior differences vs. daemon mode#

Not running a Bun app?#

Foreground mode works for every runtime pboss supports — Node.js or Deno — the container story is the same:

CMD ["pboss", "start", "--no-daemon", "server.js", "--interpreter", "node"]

See Runtimes — first-class Bun, Node.js, and Deno: the same three the pboss daemon itself runs on.