Self-hosted service
felixmosh/bull-board avatar
felixmosh/bull-board

@bull-board: a dashboard for Bull and BullMQ queues

🎯 Queue background jobs inspector

3,536 stars501 forksTypeScriptMIT

At a glance

What is it?
@bull-board mounts a web UI over your existing Redis-backed Bull or BullMQ queues, either as a library inside your own server or as a standalone CLI and container. It is an inspector, not a supervisor: useful for looking at jobs, thin on operational guarantees.
Who is it for?
Adopt @bull-board if you already run Bull or BullMQ on Redis and need a shared view of queue state, particularly if you want it mounted inside an existing Express, Fastify, Koa, Hapi, NestJS, Hono, H3, Elysia or Bun server rather than as a separate service. Do not adopt it as a scheduler or a replacement for queue-level alerting: the core is stateless and the documentation describes it as an inspector, with long retention only through the opt-in @bull-board/metrics package.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • felixmosh/bull-board3,536 ★ · +47
Star history
Repository2026-09-242026-11-21
felixmosh/bull-board3.5k3.5k

47 Stars in the last 58 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What @bull-board actually inspects

Bull and BullMQ store queue state in Redis. The job data is there, but reading it means either writing throwaway scripts against the queue API or opening a Redis client and decoding keys by hand. @bull-board is the UI layer over that state: you hand it queue instances, it renders them.

The audience is narrow and specific. It is for teams already running Bull or BullMQ who want to see what is waiting, active, completed or failed without building an internal tool. The README frames it plainly as a dashboard UI for the two libraries, and the repository topics list bull, bullmq, bullmq-pro and redis. Nothing in the project suggests it manages queue infrastructure. It reads and, for some operations, mutates jobs inside queues you already own.

That framing matters when you evaluate it. This is an observability surface bolted onto an existing Redis deployment, not a job runner, not a scheduler, and not a monitoring service with its own storage. The core stays stateless and writes nothing unless you opt into the metrics package, a property the README states directly.

How the adapter model works

The architecture splits into three pieces. @bull-board/api holds the queue-facing logic and the board definition. @bull-board/ui is the React front end. A framework adapter, such as @bull-board/express, turns the board into a router your server can mount.

The flow is one-directional and simple. You construct a Queue from bullmq, wrap it in a BullMQAdapter, pass the array of adapters plus a server adapter into createBullBoard, then mount the router at a path. The API layer reads from Redis through the queue objects you supplied. There is no separate database, no agent, and no collector process. If Redis is unreachable, the dashboard has nothing to show.

Because the queue objects come from your application, the dashboard sees exactly the queues you chose to register. That is a deliberate constraint: a queue you forget to pass is invisible in the UI, and there is no discovery mechanism described. The adapter also detects whether a BullMQ v6 queue is backed by Redis or PostgreSQL, so the storage backend needs no configuration on your side. BullMQ >= 5.56.0 and all of v6 are listed as supported.

Installing @bull-board/express and mounting the board

Install the API package plus the adapter for your framework. The README lists @bull-board/fastify, @bull-board/koa, @bull-board/hapi, @bull-board/nestjs, @bull-board/hono, @bull-board/h3, @bull-board/elysia and @bull-board/bun as the alternatives.

bash
npm install @bull-board/api @bull-board/express

The minimal Express example wires a queue, a server adapter and a board together, then mounts the router at a path of your choosing. The base path set on the adapter must match the path you mount it on, otherwise the UI's asset requests go to the wrong place.

js
const { createBullBoard } = require('@bull-board/api');
const { BullMQAdapter } = require('@bull-board/api/bullMQAdapter');
const { ExpressAdapter } = require('@bull-board/express');

const serverAdapter = new ExpressAdapter();
serverAdapter.setBasePath('/admin/queues');

createBullBoard({
  queues: [new BullMQAdapter(emailQueue)],
  serverAdapter,
});

app.use('/admin/queues', serverAdapter.getRouter());

Start the server with Redis running on port 6379 and open http://localhost:3000/admin/queues. If the page loads but shows no queues, the adapter array is the first thing to check.

If you would rather not touch application code, the README gives a one-liner for an existing Redis instance. This is the fastest way to see what the dashboard looks like before committing to an integration.

bash
npx @bull-board/cli -r redis://localhost:6379

There is also a container image, documented at the project's Docker guide, for environments with no Node toolchain. Note the host binding in the example: it publishes to 127.0.0.1 only, which is a sensible default given what the dashboard exposes.

bash
docker run --rm -p 127.0.0.1:3000:3000 ghcr.io/felixmosh/bull-board --redis redis://host.docker.internal:6379

The metrics package and what statelessness costs you

BullMQ keeps only a short ring buffer of per-minute metrics, so the throughput chart cannot look back much beyond an hour. @bull-board/metrics, described in the README as beta, snapshots those metrics into long-retention Redis buckets and feeds them back, adding a Metrics history page and 7, 30 and 90 day ranges per queue chart.

This is opt-in and it changes the deployment's character. Without it, the core writes nothing. With it, you are adding a recorder that persists data into Redis, and the documentation points to a storage panel that tells you what keeping that history costs. The trade is explicit: retention versus writes. Teams that installed the dashboard precisely because it was read-only should read the historical metrics recipe before enabling it.

The CLI and the Docker image already bundle the package, so --history turns it on without an install step. That is convenient, and it also means a container started with that flag is no longer the stateless thing described elsewhere in the README.

bash
npx @bull-board/cli -r redis://localhost:6379 --history

Where @bull-board is the wrong tool

The dashboard has no authentication of its own. The Express example mounts serverAdapter.getRouter() at /admin/queues with nothing in front of it, and the repository ships examples named with-express-auth, with-fastify-auth, with-hapi-auth and with-nestjs-fastify-auth, which tells you the project's position: authentication is your problem, handled by your framework's middleware. A dashboard that can retry, promote or remove jobs, exposed on a reachable route, is a real risk. The Docker example's 127.0.0.1 binding is the right instinct.

It is also the wrong tool for anything that needs to run without a human. There is no alerting, no notification, no threshold evaluation described in the project's documentation. If a queue stalls at 3am, the board will show it correctly at 9am. Anything that needs to page someone belongs in a different layer, and pairing this with a metrics or alerting system is a design decision the project leaves to you.

Finally, the version floor is a real constraint. BullMQ >= 5.56.0 and v6 are supported, and the README points to a supported versions page for what CI tests and when the floor moves. If you are pinned to an older BullMQ, check that page before planning an upgrade around the dashboard.

Bull Board against general Redis and queue tooling

The obvious alternative is a general Redis GUI. Those connect to Redis and show you keys, values and memory usage, which is enough to confirm that a queue exists and roughly how large it is. What they cannot do is interpret Bull's data structures as jobs: state, progress, attempts, parent and child relationships. Reading a failed job's payload through a Redis client means knowing the key layout. @bull-board knows it because it uses the queue library itself.

The second alternative is building the view into your own admin panel. That gives you full control over authentication, layout and which operations are exposed. It also means maintaining a UI that tracks BullMQ's internals, which is exactly the maintenance burden this project absorbs for you across its adapter packages.

The third is the queue library's own event stream. Consuming completed and failed events gives you programmatic reaction and is the right foundation for alerting. It gives you no historical view and no way to look at a single job's payload without writing code. The two are complementary rather than competing, and the README's framing of @bull-board as an inspector fits that division.

On the UI side, the project ships light and dark themes together and supports whitelabel theming through design tokens named after the shadcn contract. Setting primary carries through to the focus ring, sidebar and selection states. That is a detail, but it is the difference between embedding a tool that looks foreign and one that does not.

Maintenance, licensing and upgrade cost

The repository is not archived. The last push was on 2026-09-23, and releases v9.10.0 and v9.10.1 landed on 2026-09-10 and 2026-09-12, with v9.9.0 before them on 2026-09-08. Release cadence is brisk, which cuts both ways: fixes arrive quickly, and so do minor version bumps you need to track.

The upgrade surface is larger than a single package. A typical install pulls @bull-board/api plus a framework adapter, and the UI ships as its own package in the workspace. Adapter packages are versioned in lockstep with the root, so a partial upgrade can leave the API and the adapter out of step. The README's supported versions page is where the BullMQ floor is documented, and that floor is the thing most likely to force a coordinated bump of your queue library and your dashboard together.

Licensing is MIT, per the repository's LICENSE file and the licence badge in the README. That is permissive and imposes no copyleft obligation on the surrounding application. It is not legal advice, and if you redistribute the packages inside a product, read the licence text yourself rather than relying on this summary.

The container image is built from node:22-alpine with a BULL_BOARD_VERSION build argument defaulting to latest, and it runs as the node user with a healthcheck against the root path. Pinning that argument to a specific version is the difference between a reproducible image and one that changes under you on the next build.

Editorial conclusion

Adopt @bull-board if you already run Bull or BullMQ on Redis and need a shared view of queue state, particularly if you want it mounted inside an existing Express, Fastify, Koa, Hapi, NestJS, Hono, H3, Elysia or Bun server rather than as a separate service. Do not adopt it as a scheduler or a replacement for queue-level alerting: the core is stateless and the documentation describes it as an inspector, with long retention only through the opt-in @bull-board/metrics package. Before rolling it out, verify which adapter package matches your framework, confirm that your BullMQ version is at or above the 5.56.0 floor the README states, and decide what sits in front of the /admin/queues path, since the Express example mounts the router with no authentication of its own.

Frequently asked questions

What is @bull-board?

It is a dashboard UI for Bull and BullMQ job queues. You plug it into your server or run it standalone against Redis, and it renders the queues you register so you can inspect jobs, schedulers and flows.

What are the alternatives to @bull-board?

A general Redis GUI can show the underlying keys but cannot interpret them as jobs with state, progress and parent-child relationships. Building your own admin panel gives more control over authentication and layout, at the cost of tracking BullMQ's internals yourself.

Can I run @bull-board without writing any code?

Yes. The README gives a CLI command, npx @bull-board/cli -r redis://localhost:6379, and a Docker image at ghcr.io/felixmosh/bull-board, both of which connect to an existing Redis instance with no application changes.

Does @bull-board include authentication?

No. The Express example mounts the router without any auth middleware, and the repository provides separate examples for Express, Fastify, Hapi and NestJS with Fastify that show authentication handled by the surrounding framework.

Which BullMQ versions does @bull-board support?

The README states that BullMQ >= 5.56.0 and all of v6 are supported, including v6 queues stored in PostgreSQL, and that the adapter detects the backend so there is nothing to configure.

Official sources

  1. felixmosh/bull-board on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/felixmosh-bull-board.svg)](https://hysenlabs.com/projects/felixmosh-bull-board)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/felixmosh-bull-board.svg)](https://hysenlabs.com/projects/felixmosh-bull-board)

Was this useful?