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.

# 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

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 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 ​

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.