bunqueue dashboard

The only queue dashboard that also runs the server. Monitor and control queues, jobs, DLQ, cron, webhooks, workers, and a live activity stream for a bunqueue server (a fast, Redis-free, Bun-native background-job queue), plus start / stop / restart of the server process itself, all from one place.

For Bun developers and AI-agent builders running bunqueue who want to operate their queue, not just watch it.

▶ Try the live demo

The full dashboard running on sample data, no server needed.

A quick tour. Try it live →

The Overview page. See every screen in the illustrated guide →

⚠️ Beta. bunqueue dashboard is under active development, interfaces and behavior may change between releases. Review it before relying on it for unattended production use.

📚 Documentation

Full, illustrated docs live at egeominotti.github.io/bunqueue-dashboard/docs.

• Illustrated user guide, one detailed, screenshot-backed page per dashboard section.
• Deployment, Docker (Caddy), Kubernetes, PM2, and hosting platforms (Vercel, Netlify, Cloudflare, Fly.io, Render, Cloud Run).
• Architecture and API mapping, how it fits together and every endpoint it drives.
• llms.txt, the whole site as a single file for LLMs.

Table of contents

• Documentation
• Why
• Features
• Quick start
• Architecture
• Configuration
• Scripts
• Docker
• Deployment
• Testing & quality gate
• Project structure
• Security
• Contributing
• License

Why

bunqueue exposes a rich HTTP API, but operating it by hand (curl, ad-hoc scripts) is slow and error-prone. This dashboard is a complete operator console: everything the API can do, plus the one thing it can't, managing the server process, behind a fast, keyboard-friendly UI.

It talks only to bunqueue's public HTTP API (:6790) and a small local control agent. It never imports or modifies bunqueue itself, so it tracks any bunqueue server you point it at.

Features

| Area | Where | What you can do | | --- | --- | --- | | Home | Overview | Live health banner, throughput, queue health, recent activity | | Server | Control ▸ Server | Start / stop / restart the server process, edit its config, tail process logs | | Enqueue | Control ▸ Add Job | Add jobs (single or bulk) with every option | | Inspect | Control ▸ Job Inspector | Look up any job; promote / retry / discard / cancel / re-prioritize / delay; view data & result | | Queues | Control ▸ Queue Control | Pause / resume / drain / clean / promote / retry-completed, rate-limit, concurrency, stall & DLQ policy | | Cron | Control ▸ Cron Manager | Create (cron or interval) and delete schedules | | DLQ | Control ▸ DLQ | Inspect dead-letter entries, retry one / all, purge | | Webhooks | Control ▸ Webhooks | Create / enable / delete job-event webhooks | | Ops | Control ▸ Diagnostics | Health, ping, storage, memory, connections, totals | | Browse | Queues / Jobs / DLQ / Cron / Metrics / Workers / Logs | Read-only browsing with basic actions |

Every job action is gated by the job's real state (src/lib/jobActions.ts), so the UI never offers an action the server would reject.

Quick start

Prerequisites: Bun ≥ 1.3 and a reachable bunqueue server (or let the control agent start one for you from the Server page).

Run from npm (no clone)

bunx bunqueue-dashboard

One command, zero dependencies (a 543 kB download): serves the prebuilt dashboard on http://127.0.0.1:8080, proxies /api/* to your bunqueue server (BUNQUEUE_URL, default http://localhost:6790), and runs the control agent on 127.0.0.1:6800. Same env knobs as the standalone binaries: PORT · BIND_ADDR · BUNQUEUE_URL · AGENT_PORT · AGENT_ALLOWED_ORIGINS · AGENT_TOKEN · BUNQUEUE_START_CMD.

Install it permanently instead of running via bunx:

bun add -g bunqueue-dashboard   # or: npm i -g bunqueue-dashboard (still runs on Bun)
bunqueue-dashboard

Run from source

git clone https://github.com/egeominotti/bunqueue-dashboard.git
cd bunqueue-dashboard
bun install
bun start

bun start boots both the control agent and the dashboard in one terminal and shuts both down on Ctrl-C:

| Service | URL | Role | | --- | --- | --- | | Dashboard | http://localhost:5273 | The UI (/api/* is proxied to :6790 in dev) | | Control agent | http://127.0.0.1:6800 | Starts / stops / restarts the server process | | bunqueue server | http://localhost:6790 | Your queue server, started from the Server page or run separately |

Prefer separate terminals? The individual commands still exist, see Scripts.

Architecture

flowchart LR
    subgraph Browser
        UI["Dashboard (React 19 SPA)"]
    end
    subgraph Local
        Agent["Control agent (Bun)<br/>127.0.0.1:6800"]
        Server["bunqueue server<br/>:6790 HTTP · :6789 TCP"]
    end
    UI -- "HTTP: queues, jobs, DLQ, cron…" --> Server
    UI -- "SSE: live activity" --> Server
    UI -- "/control/* start·stop·restart" --> Agent
    Agent -- "spawn / kill process" --> Server

• Reads by polling (usePolledData) and a Server-Sent Events stream (useActivityStream).
• Writes through the same HTTP API, with every mutation shape-verified against the live server.
• Process lifecycle, the one thing HTTP can't do, is delegated to the local control agent.

Two HTTP clients coexist on purpose: src/lib/api.ts (first-generation view pages) and src/lib/bq.ts (the complete, shape-verified client used by every Control ▸ * page). See docs/ for the full, source-verified reference.

Configuration

All dashboard variables are build-time (VITE_*) and can also be changed at runtime from the in-app Settings page. Copy .env.example to .env to set defaults.

| Variable | Purpose | Default | | --- | --- | --- | | VITE_BUNQUEUE_URL | bunqueue server origin | /api (dev proxy → :6790) | | VITE_BUNQUEUE_TOKEN | Bearer token, if the server has AUTH_TOKENS set | none | | VITE_BUNQUEUE_AGENT_URL | Control-agent origin | http://localhost:6800 | | AGENT_PORT | Control-agent port | 6800 | | AGENT_ALLOWED_ORIGINS | Extra browser origins allowed to drive the agent (comma-separated) | dev defaults | | AGENT_TOKEN | Optional bearer token required on state-changing agent requests | none (off) |

Scripts

| Command | Does | | --- | --- | | bun start | Agent + dashboard together (one-command dev) | | bun dev | Dashboard only (Vite dev server) | | bun run agent | Control agent only | | bun run build | Typecheck (tsc --noEmit) + production build → dist/ | | bun run preview | Preview the production build | | bun run check | Biome lint + format (the CI gate) | | bun run check:fix | Biome lint + format with safe fixes applied | | bun test | Unit + agent-lifecycle tests |

Docker

A multi-stage image builds the SPA with Bun and serves it with Caddy (gzip/zstd, SPA history fallback, immutable asset caching). Published to the GitHub Container Registry on every push.

# Pull & run the published image (`edge` tracks main; use `vX.Y.Z`/`latest` after a release)
docker run --rm -p 8080:80 ghcr.io/egeominotti/bunqueue-dashboard:edge
# → http://localhost:8080  (set the server URL from the Settings page)

# …or build locally, optionally baking in a default server origin
docker build --build-arg VITE_BUNQUEUE_URL=https://queue.example.com -t bunqueue-dashboard .
docker run --rm -p 8080:80 bunqueue-dashboard

Tags: latest and vX.Y.Z on releases, edge on main.

Deployment

• Standalone executables, every release ships self-contained binaries for Linux (x64/arm64), macOS (x64/arm64) and Windows (x64): download one file and run it, it serves the dashboard (assets embedded), proxies /api to your bunqueue server (BUNQUEUE_URL, default :6790) and includes the control agent.

  ./bunqueue-dashboard-vX.Y.Z-darwin-arm64        # → http://localhost:8080
  PORT=3000 BUNQUEUE_URL=https://queue.example.com ./bunqueue-dashboard-vX.Y.Z-linux-x64

• GitHub Pages, every push to main builds and publishes the static SPA (.github/workflows/pages.yml). The workflow attempts to auto-provision Pages; if the first run reports Get Pages site failed, enable it once under Settings ▸ Pages ▸ Source → GitHub Actions (the default GITHUB_TOKEN can't create a Pages site on its own). The build sets the correct sub-path base and a 404.html SPA fallback automatically.
• Container, self-host the published ghcr.io image behind any reverse proxy.
• Static host, bun run build emits a plain dist/ you can serve from any CDN or static host.

Because the deployed build is a static shell, point it at a reachable bunqueue server via VITE_BUNQUEUE_URL (build time) or the Settings page (runtime).

Testing & quality gate

Three commands must be green before a change is considered done, the same checks CI runs:

bun run build     # tsc --noEmit + vite build
bun run check     # Biome lint + format (production-grade config)
bun test          # unit + agent-lifecycle tests

CI enforces this on every push and pull request. See Contributing.

Project structure

bunqueue-dashboard/
├── .github/workflows/   # CI, Pages deploy, Docker publish, Release
├── agent/               # Bun control agent (process lifecycle), server.ts, manager.ts, index.ts
├── docker/              # Caddyfile for the container image
├── docs/                # source-verified reference (architecture, pages, API mapping, known issues)
├── scripts/dev.ts       # one-command dev launcher (`bun start`)
├── src/
│   ├── lib/             # api.ts, bq.ts, hooks, formatters, job-action gating
│   ├── components/      # layout shell, UI kit, Zustand stores
│   └── pages/           # view pages + Control ▸ * operator pages
└── test/                # bun test (format, sse, manager, agent lifecycle, s3 store)

Full walkthrough in docs/README.md.

Security

The control agent can spawn processes, so it is hardened by design (agent/server.ts):

• Binds 127.0.0.1 only.
• CORS locked to an allowlist, Access-Control-Allow-Origin is never *.
• Requests carrying a disallowed Origin are rejected (403) before reaching the process manager, blocking drive-by CSRF from a malicious tab.
• Optional AGENT_TOKEN adds a bearer-token gate on state-changing requests.

Keep the agent on loopback (or an equivalently trusted network) and set AGENT_TOKEN for shared machines. See docs/known-issues.md for the honest, verified limitations.

Contributing

1. Keep it additive, prefer new files + minimal glue over rewriting existing ones (see CLAUDE.md).
2. Make the gate green: bun run build && bun run check && bun test.
3. Open a PR, the template walks you through the checklist. CI must pass.

License

MIT © Egeo Minotti