Run Bugspray locally

You need repository access, Node.js 22.19 and pnpm 11.1.2. These are the documented exercised versions; the package declares Node >=22.12. macOS local development is exercised. Windows and all other Node majors are not established support targets.

Install from an authorized checkout

git clone https://github.com/SynclyUS/bugspray.git
cd bugspray
pnpm install --frozen-lockfile

Dependencies include tracked vendor/*.tgz archives. Local installation needs no organization package-registry credentials. Their future redistribution rights remain a separate release decision.

Start with private, disposable data

Run from the repository root:

export QA_SUITE_DATA_DIR="$(mktemp -d "${TMPDIR:-/tmp}/bugspray-docs.XXXXXX")"
BUGSPRAY_ENABLE_REPRO_EXECUTION=0 pnpm dev

Open http://127.0.0.1:3737. Stop with Ctrl-C when finished. Keep the value of QA_SUITE_DATA_DIR to reopen this data later. Without it, the app uses the checkout’s data/ directory.If 3737 is occupied, use PORT=3738 BUGSPRAY_ENABLE_REPRO_EXECUTION=0 pnpm dev and substitute that port in the following requests. Do not stop another instance.

Check the local API

In another terminal:

curl --fail-with-body http://127.0.0.1:3737/api/settings
curl --fail-with-body http://127.0.0.1:3737/api/findings/schema

The UI, /api and /mcp share this origin. Ordinary loopback use needs no password, cloud account or provider connection. It trusts processes on your workstation.

Submit your first example

Save the following as finding.json in a scratch directory:

{
  "title": "[Synthetic example] Saved view loses its filters",
  "description": "What happened:\nA saved view reopened without filters.\n\nExpected behavior:\nSaved filters return after reload.\n\nActual behavior:\nThe view shows all items.\n\nUser impact:\nThe user must rebuild the filter.\n\nEvidence:\nSynthetic documentation example; no application was tested.",
  "analysis": "Synthetic API example. No root cause was investigated.",
  "analysisConfidence": "low",
  "url": "https://app.example.com/views",
  "severity": 4,
  "reproSteps": ["Save a filtered view", "Reload the page", "Reopen the view and inspect its filters"],
  "tags": ["synthetic-example"],
  "requiresAuth": false,
  "notifySlack": false
}

curl --fail-with-body http://127.0.0.1:3737/api/findings \
  --form 'metadata=<finding.json'

Open Findings in the app and select the example. This stores metadata without running code or notifying Slack. REST metadata submission is less strict than the agent verified-reporting contract.

Explore the connected workflow

Open Products, create Example Desk, add a Views area and write your first workflow. You can browse and author catalog expectations without a browser runner or provider accounts. Connect an MCP client when you want an agent to read the catalog or report verified findings.

Add browser capabilities when needed

pnpm exec playwright install chromium

Chromium is needed for browser authentication and repros. Local recording/transcoding paths also need ffmpeg; Linux native capture needs Xvfb. These are optional for ordinary browsing and metadata storage. Submitted repros are executable code. Read the execution boundary before enabling them. Store test authentication profiles privately and use dedicated test accounts.

Keep your data

Your data directory contains SQLite, artifacts, temporary uploads and authentication profiles. Do not share it, commit it, reset it for an upgrade or point simultaneous instances at it. See backup and upgrade before using real findings.

Start here

Understand Bugspray

Use Bugspray

Run Bugspray locally

Explore the connected workflow

Add browser capabilities when needed

Keep your data

​Explore the connected workflow

​Add browser capabilities when needed

​Keep your data

Explore the connected workflow

Add browser capabilities when needed

Keep your data