Getting Started

Three steps. That's it.

1. Run one command — start Buggregator with a single command. No installation, no registration, no configuration files.
2. Add one env variable — change one line in your .env file. Your existing Sentry SDK, VarDumper, Monolog, or Ray — they all just work.
3. Open your browser — navigate to http://127.0.0.1:8000 and start debugging. No login required.

Quick Start

Two ways to run it. Both give the same Buggregator.

• Binary: one file, no Docker. Good on your own machine.
• Docker: one container. Good when your app already runs in Docker Compose.

Setting it up with an AI agent? Give it the agent setup page.

Binary

Buggregator is a single binary with no dependencies. One command installs it (from v2.6.0).

Linux and macOS — puts buggregator in ~/.local/bin, no sudo, checks the checksum:

curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
buggregator

Windows (PowerShell) — puts buggregator.exe in %LOCALAPPDATA%\Programs\buggregator, checks the checksum:

irm https://raw.githubusercontent.com/buggregator/server/master/scripts/install.ps1 | iex
& "$env:LOCALAPPDATA\Programs\buggregator\buggregator.exe"

• The script picks the file for your system and CPU (Intel/AMD or ARM).
• Windows: the folder is not added to PATH, so run it by its full path, as above.
• Linux and macOS: if ~/.local/bin is not in your PATH, the script says so. Then run ~/.local/bin/buggregator.
• On Windows, the VarDumper module (port 9912) is not available. Every other module works.

Download the file yourself

# Linux (Intel/AMD). ARM: buggregator-linux-arm64
curl -fsSL -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-linux-amd64
chmod +x buggregator
./buggregator

# macOS (Apple Silicon). Intel: buggregator-darwin-amd64
curl -fsSL -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-arm64
chmod +x buggregator
./buggregator

# Windows (PowerShell). ARM, from v2.6.0: buggregator-windows-arm64.exe
Invoke-WebRequest https://github.com/buggregator/server/releases/latest/download/buggregator-windows-amd64.exe -OutFile buggregator.exe
.\buggregator.exe

Downloaded in a browser instead? These are the usual system prompts:

• macOS blocks the file once. Run xattr -d com.apple.quarantine buggregator, or right-click → Open. curl and the script do not hit this.
• Windows SmartScreen says «Windows protected your PC». Click More info → Run anyway, or run Unblock-File .\buggregator.exe.

Open http://127.0.0.1:8000 in your browser. Done.

All systems, ports, keeping events after a restart: Install the binary.

Only on this computer

The binary listens on all network interfaces, so other machines on your network can reach it. To keep it local:

HTTP_ADDR=127.0.0.1:8000 SMTP_ADDR=127.0.0.1:1025 MONOLOG_ADDR=127.0.0.1:9913 VAR_DUMPER_ADDR=127.0.0.1:9912 PROXY_ADDR=127.0.0.1:8080 buggregator

$env:HTTP_ADDR="127.0.0.1:8000"; $env:SMTP_ADDR="127.0.0.1:1025"; $env:MONOLOG_ADDR="127.0.0.1:9913"; $env:PROXY_ADDR="127.0.0.1:8080"; & "$env:LOCALAPPDATA\Programs\buggregator\buggregator.exe"

The install scripts print the same line after they finish. The Docker samples below already publish on 127.0.0.1 only.

Docker

docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:9912:9912 \
  -p 127.0.0.1:9913:9913 \
  ghcr.io/buggregator/server:latest

Docker Compose

Add Buggregator to your docker-compose.yml alongside your other services:

services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:1025:1025
      - 127.0.0.1:9912:9912
      - 127.0.0.1:9913:9913

No environment configuration needed. Works out of the box.

Just change the address

If Buggregator is part of an existing Docker Compose stack, other services can reach it by its service name. Change your app's .env to point at the container — that's the only change you need:

# Sentry — only the host changed. Your Sentry SDK keeps working exactly the same.
SENTRY_LARAVEL_DSN=http://sentry@buggregator:8000/1

# Ray
RAY_HOST=ray@buggregator
RAY_PORT=8000

# VarDumper
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=buggregator:9912

# Monolog
LOG_CHANNEL=socket
LOG_SOCKET_URL=buggregator:9913

# SMTP — email capture
MAIL_HOST=buggregator
MAIL_PORT=1025

Ports

Each port serves a specific module. You only need to expose the ports for the features you use:

Port	Protocol	Module	What it does
8000	HTTP	Sentry, Ray, Inspector, HTTP Dumps, XHProf, SMS	Web UI + HTTP-based event ingestion. This is the only required port.
1025	SMTP	Fake SMTP Server	Captures outgoing emails. Point your app's SMTP config here.
9912	TCP	Symfony VarDumper	Receives dump() / dd() output.
9913	TCP	Monolog	Receives log records via Monolog's SocketHandler.
8080	HTTP	HTTP Proxy	Forward proxy that captures request + response pairs. Optional.
9003	TCP (DBGp)	Xdebug Proxy	Sits between Xdebug and your IDE. Off by default; listens on 127.0.0.1 unless you change XDEBUG_PROXY_ADDR.

Port 8000 also serves the mock server under /mock/.

If you only need specific features, omit the unused ports. For example, VarDumper only:

docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:9912:9912 \
  ghcr.io/buggregator/server:latest

Kubernetes

The recommended way to deploy Buggregator on Kubernetes is using the Helm chart:

helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator

See the Helm chart documentation for SSO, Ingress, Prometheus, and more.

Or deploy manually as a Deployment + Service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: buggregator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: buggregator
  template:
    metadata:
      labels:
        app: buggregator
    spec:
      containers:
        - name: buggregator
          image: ghcr.io/buggregator/server:latest
          ports:
            - containerPort: 8000
            - containerPort: 1025
            - containerPort: 9912
            - containerPort: 9913
---
apiVersion: v1
kind: Service
metadata:
  name: buggregator
spec:
  selector:
    app: buggregator
  ports:
    - name: http
      port: 8000
    - name: smtp
      port: 1025
    - name: var-dumper
      port: 9912
    - name: monolog
      port: 9913

Configuration

Buggregator can be configured via a YAML config file, environment variables, or CLI flags. The priority order is: CLI flags > Environment variables > Config file > Defaults.

See the server configuration guide for the full reference.

Quick example with environment variables

docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e DATABASE_DSN=/data/buggregator.db \
  -e METRICS_ENABLED=true \
  -v ./data:/data \
  ghcr.io/buggregator/server:latest

Image Tags

Tag	Description
latest	Latest stable release. Recommended.
X (e.g., 2)	Latest release of a major version. Published since v2.6.0.
X.Y (e.g., 2.6)	Latest patch of a minor version.
X.Y.Z (e.g., 2.6.0)	One exact release, pinned.

Security

By default, all ports are bound to 127.0.0.1 (localhost only). This prevents external access. Your debug data never leaves your machine.

Warning: If you remove the 127.0.0.1: prefix (e.g., -p 8000:8000), the port becomes accessible from outside your machine. Only do this if you understand the implications.

For team environments, consider enabling SSO authentication to restrict access to the UI.