DOCSEARCHbyAlgolia
Submit Docs

Workbench Documentation

repository·main·Indexed 19 days ago

https://github.com/pontusab/workbench

An open-source, modern dashboard for BullMQ that allows developers to manage jobs, flows, schedulers, and metrics. It can be deployed as a standalone server, integrated into Node or Bun backends via framework-specific adapters (including Express, Fastify, Elysia, h3, and Astro), or used as a standalone Tauri 2 desktop client for inspecting BullMQ-backed Redis instances.

Tokens
71.1K
Snippets
249
Records
338
Agent score
64%

What's inside Workbench

  1. Overview of Workbench features

    main

    Workbench is an open-source BullMQ dashboard designed to be served from your existing backend. Key features include:

    • Zero extra infrastructure: Can be mounted as a route in your existing app or run as a standalone Docker container.
    • Framework Adapters: Supports 13 frameworks including Hono, Elysia, Express, Fastify, Koa, NestJS, AdonisJS, Next.js, TanStack Start, Astro, Nuxt, Bun.serve, and h3.
    • Queue Management: Inspect queues, jobs, flows (with DAG view), schedulers, and metrics.
    • Built-in Alerting: Manage rules for Slack and webhook contact points directly from the dashboard.
    • MCP Server: Allows driving queues via Model Context Protocol (MCP) clients like Cursor, Claude Desktop, Zed, and Continue.dev.
    • Security: Dark-mode UI that is basic-auth-protected by default.

  2. Explore Workbench Dashboard features

    main

    The Workbench dashboard provides several views for managing and inspecting BullMQ queues:

    Runs

    A virtualized table for inspecting job executions. It includes:

    • Status Filters: Filter by completed, failed, active, waiting, or delayed.
    • Inspection: View full job payloads and stack traces.
    • Developer Integration: Click stack-trace lines to open them directly in Cursor or VS Code.
    • Keyboard Shortcuts: Use keyboard navigation and retry commands.

    Flows

    Visualizes parent/child job relationships using a FlowProducer DAG view, allowing you to inspect multi-step workflows as a directed acyclic graph.

    Schedulers

    A timeline view for managing cron and delayed jobs. You can:

    • Pause, resume, or edit cron expressions live.
    • Trigger a scheduler immediately to verify configuration.

    Metrics & Overview

    • Overview Home: Displays fleet-level KPIs, per-queue health cards, 24h throughput charts, and attention alerts.
    • Metrics: Provides per-queue p50/p95 latency, throughput sparklines, and 24-hour activity buckets.

    Search

    Perform free-text searches across job IDs, names, and any fields exposed via the tags configuration.

  4. Overview of Workbench Desktop Architecture

    main

    Workbench Desktop is a standalone Tauri 2 client designed to inspect BullMQ-backed Redis instances (runs, schedulers, flows, and metrics) without requiring infrastructure deployment or authentication configuration.

    Architecture Model

    • Tauri Webview: A React + Vite frontend that handles onboarding and the main dashboard UI. The dashboard UI is imported from @getworkbench/core/ui.
    • Bun-compiled Sidecar (buildWorkbenchApiApp): An API-only server running on 127.0.0.1. It serves /api/* and /config endpoints via a loopback connection to the webview. Connection switching triggers a restart of this sidecar with a new REDIS_URL.
    • Tauri Rust Core: Manages the application lifecycle, updater, single-instance logic, and secure storage.
    • Communication: The webview communicates with the sidecar via HTTP loopback and with the Rust core via Tauri invoke() calls.
    ┌───────────────────────┐         ┌──────────────────────────┐
│ Tauri webview         │  HTTP   │ Bun-compiled sidecar     │
│   onboarding + ui     │ ──────► │   buildWorkbenchApiApp   │ ──► Redis
│   (React + Vite)     │ loopback│   (API-only, 127.0.0.1)  │
└──────────┬────────────┘         └──────────────────────────┘
           │ invoke()
           ▼
   Tauri Rust core (lifecycle, updater, single-instance, store)

  5. Versioning rules for Workbench packages

    main

    Workbench follows specific versioning patterns to ensure compatibility across its monorepo. Understanding these rules is critical for maintaining a stable ecosystem:

    • Lockstep Versioning: @getworkbench/core and all framework adapters (e.g., hono, express, fastify, next, nestjs, elysia, astro, etc.) must always share the same version number. This is because adapters depend on core via workspace:* protocols, and they must be published with matching version ranges.
    • Independent Versioning: @getworkbench/cli is versioned independently. You should only bump its version when its own code (CLI flags and command logic) changes, as its surface area is distinct from the API packages.
    • Semantic Versioning (SemVer):
      • Minor Bumps (0.x.0): Use for breaking changes, including removing or relocating any export from a package's published surface.
      • Patch Bumps (0.x.Y): Use only for non-breaking fixes.
      • Note: The project is currently in a pre-1.0 phase (e.g., 0.1.0, 0.2.0).

  6. Choose a Workbench framework adapter

    main

    Workbench provides first-party adapters for various Node and Bun frameworks. Each adapter is a thin wrapper around @getworkbench/core, providing the same dashboard and API but tailored for a specific framework's mount surface. If you are migrating from bull-board, use the following mapping to select your Workbench adapter:

    bull-board packageWorkbench adapter
    @bull-board/express@getworkbench/express
    @bull-board/fastify@getworkbench/fastify
    @bull-board/koa@getworkbench/koa
    @bull-board/nestjs@getworkbench/nestjs
    @bull-board/hono@getworkbench/hono
    @bull-board/h3@getworkbench/h3
    @bull-board/elysia@getworkbench/elysia

  7. Integrate Workbench with h3-based runtimes

    main

    The workbench() handler is designed for compatibility with h3-based runtimes. While this example runs on plain node:http via toNodeListener, the same workbench() handler can be used in other frameworks such as:

    • Nitro
    • SolidStart
    • Analog
    • Any other h3-based runtime

  8. Integrate Workbench into Astro via catch-all routes

    main

    To mount the Workbench BullMQ dashboard in an Astro project, use a catch-all route. In this example, the dashboard is mounted at /jobs using the file src/pages/jobs/[...workbench].ts.

    Key configuration requirements for Astro:

    • Output Mode: Must be set to server (server output mode).
    • Adapter: Requires a Node adapter (configured in astro.config.mjs).

  9. Verify application identifier and updater endpoint

    main

    Before your first public release, ensure the following identifiers are correct, as changing them later will orphan user data or break updates.

    App Identifier: Check apps/desktop/src-tauri/tauri.conf.json (identifier) and apps/desktop/src-tauri/src/secrets.rs (SERVICE constant). These must match. The default is dev.getworkbench.desktop.

    Updater Endpoint: Check apps/desktop/src-tauri/tauri.conf.json for the tauri.bundle.updater.endpoint. It currently points to: https://github.com/pontusab/workbench/releases/latest/download/latest.json.

    Note: The updater endpoint will only resolve once you have published your first non-draft GitHub release.

  10. Compare Redis auto-discovery vs. explicit queues

    main

    Use Redis auto-discovery when:

    • You are building Ops dashboards and want every queue in Redis to be visible automatically when new ones appear.
    • You are running Large fleets and want to use maxQueues to cap the discovery cost.

    Pass explicit Queue[] instances when:

    • You want to limit visibility to specific queues for security or noise reduction.
    • Your queue names do not follow standard BullMQ key patterns.
    • You require custom Queue options for specific instances.

  12. Security considerations for Workbench MCP

    main

    When using the Workbench MCP server, follow these security best practices:

    • Authentication: Always run your Workbench dashboard with authentication enabled in any shared environment.
    • Unsupervised Agents: If allowing unsupervised AI agents to use the MCP, configure your dashboard with readonly: true.
    • Local Execution: The MCP server runs locally as an editor subprocess and does not open any network ports, reducing the attack surface.