# 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](/agent-setup).

### 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:

```bash
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:

```powershell
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.

<details>
<summary>Download the file yourself</summary>

```bash
# 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
```

```powershell
# 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`.

</details>

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

All systems, ports, keeping events after a restart: [Install the binary](/install).

### Only on this computer

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

```bash
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
```

```powershell
$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

```bash
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:

```yaml
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:

```dotenv
# 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](./config/sentry.md), [Ray](./config/ray.md), [Inspector](./config/inspector.md), [HTTP Dumps](./config/http-dumps.md), [XHProf](./config/xhprof.md), [SMS](./config/sms.md) | Web UI + HTTP-based event ingestion. This is the only required port. |
| **1025** | SMTP | [Fake SMTP Server](./config/smtp.md) | Captures outgoing emails. Point your app's SMTP config here. |
| **9912** | TCP | [Symfony VarDumper](./config/var-dumper.md) | Receives `dump()` / `dd()` output. |
| **9913** | TCP | [Monolog](./config/monolog.md) | Receives log records via Monolog's `SocketHandler`. |
| **8080** | HTTP | [HTTP Proxy](./config/http-proxy.md) | Forward proxy that captures request + response pairs. Optional. |
| **9003** | TCP (DBGp) | [Xdebug Proxy](./config/xdebug.md) | 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](./config/mock-server.md) under `/mock/`.

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

```bash
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](./config/helm-chart.md):

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

See the [Helm chart documentation](./config/helm-chart.md) for SSO, Ingress, Prometheus, and more.

Or deploy manually as a `Deployment` + `Service`:

```yaml
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](./config/server.md) for the full reference.

### Quick example with environment variables

```bash
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](./config/sso.md) to restrict access to the UI.