# Buggregator: one Go binary for PHP exceptions, mail, dumps and logs

> Buggregator is a debugging server written in Go that speaks the protocols PHP tools already use, so Sentry, Ray, VarDumper, Monolog, an SMTP server, the Inspector protocol and XHProf profiling all land in one web interface instead of five separate tools. It ships as a single binary with an embedded SQLite database, and it needs no PHP runtime.

**buggregator/server** — Buggregator — a single-binary debugging server for PHP. Captures exceptions, dumps, emails, profiling, logs in real-time UI. Sentry, Ray, VarDumper, SMTP, Monolog, Inspector, XHProf and more.

- Repository: https://github.com/buggregator/server
- Website: https://docs.buggregator.dev
- Stars: 1,078 · Forks: 43
- Language: Go
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/buggregator-server

## A complete rewrite that removed the PHP runtime

The current version is a rewrite in Go, and the rewrite is the whole point. The README describes v2.0 as a single self-contained binary with an embedded SQLite database, a web UI and a WebSocket server, and states that there is no PHP runtime, no RoadRunner, no Centrifugo and no external database. Earlier versions of the project were a PHP application, and the README points anyone who wants that to the 1.x branch.

The pitch in one line is that you install nothing in your application. The README says it works with the SDKs you already have, with no cloud account, no code changes and no runtime dependencies. In practice that means the client libraries you have already configured, Sentry or Ray or Monolog, keep pointing at the same endpoints, and only the host changes to localhost.

Two version numbers are given in the README, which is unusual and useful: the server is at v2.0.0 and the frontend is at v1.30.0. The split tells you the UI is versioned separately from the Go service, so a mismatch between what the docs describe and what the interface shows is usually a frontend revision rather than a server one.

## Nine modules, four transports, and the port each one owns

The supported modules table is the heart of the project, and it maps every capture type to a transport and a port. Sentry arrives over HTTP in gzip and envelope format, Ray over HTTP, and the Symfony VarDumper over TCP on port 9912, parsed by an embedded PHP parser. The Inspector protocol comes over HTTP for APM monitoring, and Monolog over TCP on 9913 as newline-delimited JSON.

The rest are the ones that usually mean a separate program on a developer machine. SMTP listens on 1025 and captures email in RFC822 form, including multipart messages and attachments. An SMS gateway capture is exposed over HTTP at the /sms path, with 41 providers supported. A catch-all HTTP request dump server records incoming requests. The XHProf profiler exposes a call graph, a flame chart and a top functions view. Webhooks are outgoing rather than incoming, an HTTP POST notification when events arrive, and they can be filtered by event type.

This table is why the tool saves time. The alternative for a Laravel developer is a Sentry-compatible receiver, a separate SMTP catcher, a Ray or VarDumper target, a Monolog handler and a profiler view, each with its own configuration and its own tab. Here they are ports on one process, and the UI shows them together.

## Running it with Docker or as a downloaded binary

The quick start is a single Docker run that publishes the four ports the modules need:

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

Open http://127.0.0.1:8000 and the interface is up. The bindings are all to 127.0.0.1, which is deliberate: an unauthenticated SMTP catcher and a debugging UI should not be reachable from the network, and the mapping keeps them local.

If you would rather not run Docker, the release artefacts can be fetched directly:

```bash
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-linux-amd64 -o buggregator
chmod +x buggregator
./buggregator
```

The README also names a third option for people who have neither Docker nor the ability to run a binary, Buggregator Trap, described as a lightweight PHP CLI alternative with its own documentation page. The repository is laid out for that workflow too, with a php/ directory at the top level next to the Go code, plus an e2e/ directory and a docker-compose file for end-to-end runs.

## Configuration precedence: flags beat env vars beat file

The server works with zero configuration, but a buggregator.yaml file can override the defaults. The documented order of precedence is CLI flags first, then environment variables, then the config file, then the built-in defaults. The README gives the example of the HTTP listen address as the http-addr flag, the HTTP_ADDR variable and the server addr key in the file, in that order of authority.

The file itself is YAML, and the sections map to the concerns a developer actually has:

```yaml
server:
  addr: ":8000"

database:
  driver: sqlite
  dsn: ":memory:"           # or "data.db" for persistence

tcp:
  smtp:
    addr: ":1025"
  monolog:
    addr: ":9913"
  var-dumper:
    addr: ":9912"
```

The default database DSN is the in-memory SQLite database, which is a sensible default for a debugging session and a trap for anything longer, since the data is gone when the process exits. Switching the dsn to a file name is the whole persistence story, and the environment variable equivalent is DATABASE_DSN. The TCP addresses for SMTP, Monolog and VarDumper are configurable the same way, with SMTP_ADDR and MONOLOG_ADDR named in the environment variable table.

## Authentication, MCP and webhooks are all opt-in

Three capabilities are off by default and each one changes how exposed the server is. Authentication is disabled by default, and the auth block supports auth0, google, github, keycloak, gitlab and a generic oidc provider, with fields for the provider URL, client id, client secret, callback URL, scopes and a JWT signing secret. Enabling it is a matter of switching the block on in the file.

MCP, the model context protocol integration for AI assistants, is also disabled by default and runs either over a socket at a path such as /tmp/buggregator-mcp.sock or over HTTP. A local socket for a debugging tool is a reasonable default for a developer machine, and a questionable one on a shared host, since anything that can reach the socket can drive the tool.

Webhooks are configured as a list of event and url pairs, with optional headers, a verify_ssl switch and a retry flag, and an event name of "*" matching everything. That is the piece to think hardest about, because a webhook on every event turns a local debugger into a source of outbound traffic. Prometheus metrics are available too, on their own address, with the note that an empty address reuses the main HTTP server.

## Where Buggregator is the wrong tool

The first wrong-tool case is production error tracking. Buggregator stores everything in a local SQLite database, by default in memory, and its UI is designed to be looked at while you work. A hosted error tracking service exists to keep data after the session, aggregate it across environments, alert people and support retention policies. This does none of that, and the README is explicit that there is no cloud account and no external database.

The second is a shared environment. Even with authentication switched on, the design assumes one developer and a local machine. A debugging server that captures exceptions, mail and request bodies is a rich target, and the webhooks and MCP features add outbound and inbound paths that need their own review before the tool sits on a shared network.

The third is a project that has already standardised on a hosted vendor. Switching to Buggregator locally is cheap because nothing in the application changes, but the moment a team wants the same data in staging or in a shared dashboard, the two setups diverge, and the README's single-machine model stops fitting. Buggregator Trap, the PHP CLI alternative, is the option for teams that want the same captures without a server process at all.

## v2.4.1 in August 2026, and no licence file in the tree

The project is not archived, and the last push was on 2026-08-17, the same day as the v2.4.1 release. The release list shows v2.4.0 from 2026-07-30 and v2.3.1 from 2026-06-09, so patch-level releases arrive every few weeks and the 2.x line is where the current work happens. The default branch is master, and the Go module is published under the name github.com/buggregator/go-buggregator, which is worth noting if you are pinning dependencies, since the repository path and the module path differ.

The go.mod file shows the dependency choices, and they are mostly small and single-purpose: go-smtp for the mail server, golang-jwt and golang.org/x/oauth2 for the authentication block, the model context protocol Go SDK for the MCP integration, the Prometheus client for metrics, yaml.v3 for configuration, a pure Go SQLite driver, and a WebSocket library for the live UI connection. Nothing in that list suggests a heavy runtime, which matches the single-binary claim.

One gap to raise before you build on it. The top-level file listing contains no LICENSE file, and the README does not state a licence. That is unusual for a project of this size and it matters if you intend to run the binary in a commercial environment or redistribute it, because without a stated grant you have no clear permission to do either. Ask the maintainers, and check the repository again before you decide, since a licence file can appear in any release.

## Conclusion

Adopt Buggregator on a local development machine or a CI container where several PHP debugging tools are currently running side by side, and start with the Docker command so the port mapping stays visible. Do not adopt it as a hosted error-tracking service for a production fleet, as a shared debugging relay for a team, or as a replacement for a real APM product, because it stores data locally and exposes an unauthenticated UI unless you switch authentication on. Before you wire it into a shared environment, read the auth block in buggregator.yaml, set DATABASE_DSN to a file path instead of the in-memory default, and note that the project listing shows no licence file, so check with the authors before you redistribute the binary.

## FAQ

### What does Buggregator capture from a PHP application?

The supported module table lists Sentry, Ray, Symfony VarDumper, Inspector, Monolog, SMTP, SMS, HTTP request dumps, the XHProf profiler and outgoing webhooks. Each module has its own transport, either HTTP or a dedicated TCP port.

### Does Buggregator need PHP or a database installed?

No. The README describes v2.0 as a complete rewrite in Go with a single self-contained binary, an embedded SQLite database, a web UI and a WebSocket server, and no PHP runtime, no RoadRunner, no Centrifugo and no external database.

### How do I make Buggregator keep its data between runs?

The default database DSN is the in-memory SQLite database. Setting the dsn value in buggregator.yaml to a file name, or the DATABASE_DSN environment variable, persists the data instead.

### Is Buggregator's web interface protected by default?

No. Authentication is disabled by default, and the auth block in buggregator.yaml can switch it on with auth0, google, github, keycloak, gitlab or a generic oidc provider. The Docker quick start binds the ports to 127.0.0.1 to keep the server local.

### Can I use Buggregator without Docker?

Yes. The README shows downloading the release binary with curl, making it executable and running it. For people with neither Docker nor a binary, it points to Buggregator Trap, a lightweight PHP CLI alternative.

## Sources

- [buggregator/server on GitHub](https://github.com/buggregator/server)
- [Issues](https://github.com/buggregator/server/issues)
- [Project website](https://docs.buggregator.dev)
- [README](https://github.com/buggregator/server/blob/master/README.md)
- [Releases](https://github.com/buggregator/server/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/buggregator-server