# bunqueue dashboard > A web dashboard that fully drives a bunqueue server over its public HTTP API (:6790) plus a small local control agent that manages the server process. Built with React 19, React Router 7, Zustand 5, Vite and Bun. ## Mental model It **reads** from a bunqueue server by polling the HTTP API (`usePolledData`, interval from the connection store) and subscribing to a Server-Sent-Events stream (`useActivityStream`) for live job activity. It **writes** through the same API (pause, add job, retry, rate-limit, and so on), with every job action gated by the job's real current state via `src/lib/jobActions.ts::actionGates` so the UI never offers an action the server would reject. The one thing HTTP cannot do, manage the server **process**, is delegated to a small local **control agent** (`agent/`): loopback-bound (127.0.0.1), CORS-locked to an allowlist, with an optional `AGENT_TOKEN` bearer gate, exposing `/control/*` to start, stop and restart bunqueue, plus a read-only SQLite inspector over `/db/*`. ## Two API clients, by design - `src/lib/api.ts`, the original client, used only by the first-generation **classic** pages (reachable at `*-classic` routes). - `src/lib/bq.ts`, the complete, shape-verified, strict-error-checked client behind every **Pro** control page (`src/pages/control/*`), which own the sidebar. New work uses `bq`. Its `call()` also throws on HTTP-200-with-`{ok:false}` (except `health()`). ## Verified API-shape gotchas - `GET /webhooks`, `/workers`, `/storage`, `/ping` wrap the payload in `{ ok, data: {...} }`; `/queues/:q/dlq`, `/dlq/stats`, `/crons`, `/queues/:q/counts` are flat. - DLQ entries are nested `{ job, enteredAt, reason, error, attempts[] }`, with no top-level `id`/`name`. - Jobs have no `name` field and no embedded `result` (fetch via `GET /jobs/:id/result`); they use `startedAt`/`completedAt` (not `processedOn`/`finishedOn`). For the full per-section walkthrough see the User guide pages; for endpoint shapes see API mapping; for honest current limits see Known issues. ## Table of Contents ### Getting started - [Quickstart](/bunqueue-dashboard/docs/quickstart.md): Get the bunqueue dashboard running in one command, then point it at a bunqueue server or let the control agent start one for you. - [User guide](/bunqueue-dashboard/docs/user-guide.md): An illustrated, section-by-section tour of the bunqueue dashboard, one detailed, screenshot-backed page per dashboard section. - [Development](/bunqueue-dashboard/docs/development.md): Set up, run, build, and test the bunqueue dashboard locally: the one-command dev launcher, the quality gate, and the project layout. ### Deploy - [Deployment](/bunqueue-dashboard/docs/deploy.md): Deploy the bunqueue dashboard as a static site or a single all-in-one server, with Docker, Kubernetes, PM2, or a hosting platform. Two modes, one decision. - [Docker](/bunqueue-dashboard/docs/deploy/docker.md): Run the bunqueue dashboard as a Docker container, served by Caddy. Pull the published image, run with docker or docker compose, or build your own. - [Kubernetes](/bunqueue-dashboard/docs/deploy/kubernetes.md): Deploy the bunqueue dashboard to Kubernetes with a Deployment, Service, and Ingress. Copy-paste manifests, health probes, and TLS notes. - [PM2](/bunqueue-dashboard/docs/deploy/pm2.md): Run the all-in-one bunqueue dashboard server under PM2, with SPA, same-origin API proxy, and the control agent. Ecosystem file, env vars, and startup on boot. - [Hosting platforms](/bunqueue-dashboard/docs/deploy/platforms.md): Deploy the bunqueue dashboard to Vercel, Netlify, Cloudflare Pages, GitHub Pages, Render, Fly.io, Railway, or Google Cloud Run. Copy-paste config for each. ### Guide · Home - [Overview](/bunqueue-dashboard/docs/guide/overview.md): A single screen that shows, at a glance, whether your bunqueue server is healthy and what your queues are doing right now. ### Guide · Queues - [Queues](/bunqueue-dashboard/docs/guide/queues.md): See every queue on your server at a glance, check how each one is doing, and pause or resume any of them in one click. - [Jobs Explorer](/bunqueue-dashboard/docs/guide/jobs.md): Browse the jobs in a queue, open any one to inspect it, and run the right actions, one job at a time or many at once. - [Dead Letter Queue](/bunqueue-dashboard/docs/guide/dlq.md): This screen is where jobs land after they fail and run out of retries, so you can see what broke, send it back to run again, or clear it out. - [Cron Jobs](/bunqueue-dashboard/docs/guide/cron.md): This screen lets you set up jobs that run on a repeating schedule, then see them all in one place. - [Flows](/bunqueue-dashboard/docs/guide/flows.md): Visualize a bunqueue job flow as an interactive DAG in the dashboard, parent, children, and dependency edges, coloured by state. ### Guide · Monitoring - [Metrics](/bunqueue-dashboard/docs/guide/metrics.md): A live, read-only dashboard that shows how well your server is keeping up right now: throughput, backlog trend, error rate, latency, and a per-queue… - [Workers](/bunqueue-dashboard/docs/guide/workers.md): A live registry of every worker connected to your server, so you can confirm your consumers are alive, see how much work each is doing, and evict one… - [Logs](/bunqueue-dashboard/docs/guide/logs.md): Watch job activity across all your queues as it happens, in one live feed. ### Guide · Control - [Server Control](/bunqueue-dashboard/docs/guide/server.md): Server Control is where you start, stop, and restart the bunqueue server, set how it launches, and watch its logs live. - [Add Job](/bunqueue-dashboard/docs/guide/add-job.md): Add Job lets you drop a job straight into any queue, one job or thousands of copies, without writing any code. - [Job Inspector](/bunqueue-dashboard/docs/guide/job-inspector.md): Look up any single job and drive its whole lifecycle from one screen: inspect its data, result, error, logs and history, edit its payload, and run every… - [Queue Control](/bunqueue-dashboard/docs/guide/queue-control.md): Your operations console for a single queue, pick one and pause, drain, clean, throttle, and tune it, all from one screen. - [DLQ Control](/bunqueue-dashboard/docs/guide/dlq-control.md): Pick one queue and deal with the jobs that failed for good, replay them or clear them out, one at a time or all at once. - [Webhooks](/bunqueue-dashboard/docs/guide/webhooks.md): Register HTTP callbacks so bunqueue pushes job events to your own endpoint the moment they happen, no polling on your side. - [Diagnostics](/bunqueue-dashboard/docs/guide/diagnostics.md): A single-glance health check for your bunqueue server, is it up, how long has it been running, is the disk full, what's connected, and how much memory is… - [Benchmark](/bunqueue-dashboard/docs/guide/benchmark.md): Push a controlled flood of jobs at your bunqueue server and watch, in real time, how fast it accepts and clears them. ### Guide · Management - [Database](/bunqueue-dashboard/docs/guide/database.md): Browse and inspect your bunqueue server's underlying SQLite database, read-only, with no risk of changing anything. - [MCP Server](/bunqueue-dashboard/docs/guide/mcp.md): Connect bunqueue to AI agents (Claude Desktop, Claude Code) over the Model Context Protocol, with 73 tools, 5 resources, and 3 prompts, in embedded or TCP mode. - [Copilot (experimental)](/bunqueue-dashboard/docs/guide/copilot.md): An in-dashboard AI copilot for bunqueue. Bring your own model (Claude, ChatGPT, Gemini, GLM, or any OpenAI-compatible endpoint) and inspect or operate your queues by chat. - [Usage](/bunqueue-dashboard/docs/guide/usage.md): A single, read-only snapshot of how hard your bunqueue server is working, lifetime job totals, live queue counts, error rate, memory, uptime, and disk… - [S3 Backup](/bunqueue-dashboard/docs/guide/s3.md): This screen helps you assemble the settings for bunqueue's S3-compatible backups and stores them in your browser for safekeeping. - [Settings](/bunqueue-dashboard/docs/guide/settings.md): Point the dashboard at your bunqueue server and choose how it looks and how often it refreshes. ### Guide · Appendix - [Classic pages](/bunqueue-dashboard/docs/guide/classic.md): The first-generation classic view pages, kept intact per the additive rule, and how each maps to its Pro replacement. ### Architecture & internals - [Architecture](/bunqueue-dashboard/docs/architecture.md): How the bunqueue dashboard fits together: the React SPA, its polling and SSE data flow, the two API clients, and the local control agent. - [Pages & routes](/bunqueue-dashboard/docs/pages.md): The verified route-to-page-to-API-client table for every page in the dashboard, both classic and Pro. - [Components & stores](/bunqueue-dashboard/docs/components.md): The dashboard's UI kit, Zustand stores, and shared lib: what each component and hook does, and how to reuse it. - [Control agent](/bunqueue-dashboard/docs/agent.md): The local control agent that starts, stops, and restarts the bunqueue process: its endpoints, security model, and read-only SQLite inspector. - [API mapping](/bunqueue-dashboard/docs/api-mapping.md): Every bunqueue HTTP endpoint the dashboard drives, with verified request and response shapes and the job-action state table. ### Project - [Known issues](/bunqueue-dashboard/docs/known-issues.md): A verified, non-glossed list of the bunqueue dashboard's current bugs and design constraints, each pointing at the exact file to look at.