Documentation

Everything you need to install, configure, and use BugReel. For the full source and latest updates, see the GitHub repository.

Quick Start

Get BugReel running in under five minutes.

Clone the repository

git clone https://github.com/BugReel/bugreel.git
cd bugreel

Configure environment

cp .env.example .env
# Edit .env — set OPENAI_API_KEY and JWT_SECRET at minimum

Start with Docker Compose
```
docker-compose up -d
```
The server will be available at http://localhost:3000.
Install the Chrome extension
Open chrome://extensions, enable Developer Mode, click "Load unpacked", and select the extension/ directory. Set your server URL in the extension settings.

Configuration

All configuration is done via environment variables in the .env file.

Variable	Description	Required
`OPENAI_API_KEY`	Your OpenAI API key for AI analysis	Yes
`OPENAI_BASE_URL`	Custom OpenAI-compatible endpoint (Azure, Ollama, etc.)	No
`WHISPER_MODEL`	Whisper model for transcription (default: whisper-1)	No
`GPT_MODEL`	GPT model for analysis (default: gpt-4o)	No
`APP_PORT`	Server port (default: 3000)	No
`DB_PATH`	SQLite database path (default: ./data/bugreel.db)	No
`UPLOAD_DIR`	Directory for uploaded recordings (default: ./data/uploads)	No
`JWT_SECRET`	Secret for JWT token signing	Yes
`LICENSE_KEY`	License key for Team/Enterprise features	No
`MAX_RECORDING_MB`	Maximum recording file size in MB (default: 500)	No

API Reference

BugReel exposes a REST API. All endpoints (except auth) require a valid JWT token in the Authorization: Bearer <token> header.

Method	Endpoint	Description
`POST`	`/api/upload`	Upload a screen recording for processing
`GET`	`/api/recordings`	List all recordings with pagination
`GET`	`/api/recordings/:id`	Get a single recording and its analysis
`DELETE`	`/api/recordings/:id`	Delete a recording and its data
`GET`	`/api/cards`	List generated bug report cards
`GET`	`/api/cards/:id`	Get a single bug report card
`POST`	`/api/cards/:id/export`	Export a card to an integration
`POST`	`/api/auth/login`	Authenticate and receive JWT token
`POST`	`/api/auth/register`	Register a new user
`GET`	`/api/auth/me`	Get current authenticated user
`POST`	`/api/license`	Validate and activate a license key
`GET`	`/api/integrations`	List configured integrations
`POST`	`/api/integrations/:type/test`	Test an integration connection

For full request/response schemas, see the GitHub README.

Extension Setup

Open chrome://extensions in any Chromium browser.
Enable Developer Mode (top-right toggle).
Click Load unpacked and select the extension/ folder from the repository.
Click the BugReel icon in the toolbar and open Settings.
Enter your Server URL (e.g. http://localhost:3000 or your production domain).
Log in with your credentials. The extension will store your JWT token locally.

Once configured, click the extension icon and hit Record to capture a bug. The recording is uploaded to your server for AI analysis automatically.

Integrations

BugReel can export bug report cards directly to your issue tracker.

Jira

Requires a Team or Enterprise license. Configure in Settings with your Jira domain, project key, email, and API token. Cards are exported as Jira issues with description, steps, screenshots, and priority.

Linear

Requires a Team or Enterprise license. Add your Linear API key and select a team. Issues are created with labels, priority mapping, and attached screenshots.

GitHub Issues

Available on all plans. Provide a GitHub personal access token and repository. Bug reports become GitHub issues with formatted markdown and image attachments.

YouTrack

Available on all plans. Configure your YouTrack URL, project ID, and permanent token. Cards are exported with full formatting and severity fields.

Webhook

Available on all plans. Send bug report data as JSON to any URL. Use this to integrate with Asana, ClickUp, Notion, Trello, Slack, or any tool with a webhook endpoint.

Self-Hosting Guide

Requirements

Docker and Docker Compose
2 GB RAM minimum (4 GB recommended)
10 GB disk space for recordings (scales with usage)
An OpenAI API key (or compatible endpoint)

Docker Deployment

git clone https://github.com/BugReel/bugreel.git
cd bugreel
cp .env.example .env
# Edit .env with your configuration
docker-compose up -d

Updating

cd bugreel
git pull
docker-compose down
docker-compose up -d --build

Data is persisted in the ./data directory and survives container rebuilds.

Reverse Proxy

For production, place BugReel behind a reverse proxy (nginx, Caddy, Traefik) with HTTPS. Point the proxy to http://localhost:3000 and update the extension's Server URL to your public domain.