A web-based dashboard for monitoring and managing pg-boss job queues.

• Overview: Aggregate statistics, problem queues, and recent warnings at a glance
• Queue Management: View all queues with cached statistics and create new queues
• Job List: View jobs with state and queue filtering
• Job Details: View full job payloads, output data, and metadata
• Job Actions: Create, cancel, retry, resume, or delete jobs directly from the UI
• Warning History: When persistWarnings is enabled, browse through previously emitted warning events.
• Multi-Schema Support: Monitor multiple pg-boss instances from a single dashboard
• Mobile Responsive: Full functionality on mobile devices with collapsible sidebar
• Shareable URLs: Database selection and filters are preserved in URLs for easy sharing

• Node.js 22.12+
• PostgreSQL database with pg-boss schema
• pg-boss 12.11+

npm install @pg-boss/dashboard

For a quick local test:

DATABASE_URL="postgres://user:password@localhost:5432/mydb" npx pg-boss-dashboard

Open http://localhost:3000 in your browser.

The dashboard is configured via environment variables:

To protect the dashboard with basic authentication, set PGBOSS_DASHBOARD_AUTH_USERNAME and PGBOSS_DASHBOARD_AUTH_PASSWORD:

PGBOSS_DASHBOARD_AUTH_USERNAME=admin \
PGBOSS_DASHBOARD_AUTH_PASSWORD=secret \
DATABASE_URL="postgres://localhost/mydb" \
npx pg-boss-dashboard

Both variables must be provided together. If only one is set, the dashboard will throw an error on startup.

To monitor multiple pg-boss instances, separate connection strings with a pipe (|):

DATABASE_URL="postgres://host1/db1|postgres://host2/db2" npx pg-boss-dashboard

You can optionally name each database for better identification in the UI:

DATABASE_URL="Production=postgres://prod/db|Staging=postgres://stage/db" npx pg-boss-dashboard

If your databases use different schemas, specify them with matching pipe separation:

DATABASE_URL="postgres://host1/db1|postgres://host2/db2" \
PGBOSS_SCHEMA="pgboss|jobs" \
npx pg-boss-dashboard

When multiple databases are configured, a database selector appears in the sidebar. The selected database is persisted in the URL via the db query parameter, making it easy to share links to specific database views.

npm install @pg-boss/dashboard

DATABASE_URL="postgres://user:pass@localhost:5432/db" \
  node node_modules/@pg-boss/dashboard/build/server/index.js

FROM node:24
WORKDIR /app
RUN npm install -g @pg-boss/dashboard
ENV PORT=3000
EXPOSE 3000
CMD ["pg-boss-dashboard"]

docker build -t pgboss-dashboard .
docker run -d \
  -e DATABASE_URL="postgres://user:pass@host:5432/db" \
  -p 3000:3000 \
  pgboss-dashboard

services:
  dashboard:
    image: node:24
    working_dir: /app
    command: sh -c "npm install -g @pg-boss/dashboard && pg-boss-dashboard"
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/mydb
      PGBOSS_SCHEMA: pgboss
      PORT: 3000
    ports:
      - "3000:3000"
    depends_on:
      - db

For production, place a reverse proxy in front of any of the above options. Example Nginx configuration:

server {
    listen 80;
    server_name pgboss.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

By default the dashboard is served from the root path (/). To serve it under a sub-path (for example behind a reverse proxy at https://example.com/pgboss/), set PGBOSS_DASHBOARD_BASE_PATH at build time:

PGBOSS_DASHBOARD_BASE_PATH=/pgboss npm run build
PGBOSS_DASHBOARD_BASE_PATH=/pgboss npm start

This sets both the Vite asset base and the React Router basename, so assets, in-app navigation, and action redirects all stay under the prefix. The reverse proxy should forward the prefix unchanged (do not strip it):

location /pgboss/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

The asset base is baked in at build time, so the published npm package (which ships a prebuilt build/) always uses /. To serve under a sub-path, build from source with PGBOSS_DASHBOARD_BASE_PATH set.

The dev server (npm run dev) always serves from the root path; PGBOSS_DASHBOARD_BASE_PATH only affects production builds.

To capture warnings in the dashboard, enable warning persistence in your pg-boss configuration:

const PgBoss = require('pg-boss');

const boss = new PgBoss({
  connectionString: 'postgres://localhost/mydb',
  persistWarnings: true  // Enable warning persistence
});

Warnings correlate to warning events already emitted by pg-boss:

• slow_query: Queries taking longer than expected
• queue_backlog: Queues exceeding their warning threshold
• clock_skew: Database clock drift detection

• Framework: React Router 7 (framework mode)
• Server: Hono via react-router-hono-server
• Styling: Tailwind CSS v4
• Components: Base UI
• Database: pg (PostgreSQL client)
• Testing: Vitest + Testing Library

To work on the dashboard from source:

# Clone the pg-boss repository
git clone https://github.com/timgit/pg-boss.git
cd pg-boss/packages/dashboard

# Install dependencies
npm install

# Initialize local database with pg-boss schema and test queues
npm run dev:init-db

# Start development server with hot reloading
npm run dev

# (Optional) Start a worker to process jobs
# Run this in a separate terminal to see jobs being processed
npm run dev:worker

# Build for production
npm run build

# Run production build
npm start

The dev:init-db script creates the pg-boss schema and populates it with sample queues and jobs for testing. It connects to postgres://postgres:postgres@127.0.0.1:5432/pgboss by default.

The dev:worker script starts a worker that processes jobs from the same pg-boss instance as the dashboard. This is useful for testing the dashboard while jobs are being processed. The worker will stay running until you stop it with Ctrl+C.

# All tests (frontend + server)
npm test

# Full CI test (used by GitHub Actions)
npm run ci

• Verify DATABASE_URL is correct and the database is accessible
• Ensure the pg-boss schema exists (run pg-boss at least once to create it)
• Check PostgreSQL logs for connection errors

• Ensure persistWarnings: true is set in your pg-boss configuration
• Warnings are only recorded after enabling this option

Queue statistics are cached in the queue table by pg-boss's monitoring system. They update based on your monitorStateIntervalSeconds configuration (default: 30 seconds).

MIT