> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Bugspray locally

> Start with an isolated data directory and submit a synthetic finding.

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.

**1. Install from an authorized checkout**

```sh theme={null}
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.

**2. Start with private, disposable data**

Run from the repository root:

```sh theme={null}
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](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.

**3. Check the local API**

In another terminal:

```sh theme={null}
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.

**4. Submit your first example**

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

```json theme={null}
{
  "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
}
```

```sh theme={null}
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](https://docs.bugspray.io/concepts/workflows.md). You can browse and author catalog expectations without a browser runner or provider accounts. Connect an [MCP client](https://docs.bugspray.io/guides/ai-agents.md) when you want an agent to read the catalog or report verified findings.

## Add browser capabilities when needed

```sh theme={null}
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](https://docs.bugspray.io/guides/findings-and-replay.md#enable-execution-deliberately) 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](https://docs.bugspray.io/self-hosting/upgrades.md) before using real findings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.