# Buggregator

> Buggregator is a free, open-source debugging server. Debug everything — install nothing. One docker run (or a single binary) gives you exceptions, dumps, emails, profiling, and logs in a single real-time UI. Written in Go with an embedded SQLite database. Runs beside your app, not inside it.

- Install: `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 ghcr.io/buggregator/server:latest`
- GitHub: https://github.com/buggregator/server
- Lightweight CLI alternative (no Docker): `composer require --dev buggregator/trap`
- JetBrains IDE plugin: https://plugins.jetbrains.com/plugin/26344-buggregator
- Supported integrations: Sentry SDK, Symfony VarDumper, Monolog, Spatie Ray, Inspector, SMTP, HTTP dumps, XHProf, SMS
- Works with: Laravel, Symfony, Spiral, WordPress, Yii, Drupal — and JS, Python, Ruby, Go via Sentry SDK

## Docs

- [Configuration — Database](/config/database.md): Database configuration: SQLite with in-memory (default, data lost on restart) or file-based persistence. Environment variable DATABASE_DSN. Storage modes for attachments: memory or filesystem. Docker volume examples for persistent data.
- [Configuration — Helm Chart](/config/helm-chart.md): Helm chart installation for Kubernetes. Standalone mode (embedded SQLite), SSO (Auth0, Google, GitHub, Keycloak, GitLab, OIDC). Configurable CORS, logging, Ingress, Prometheus ServiceMonitor, PVC storage. Service ports: 8000 HTTP, 1025 SMTP, 9912 VarDumper, 9913 Monolog.
- [HTTP Dumps — Request Inspection](/config/http-dumps.md): HTTP request capture: method, URI, headers, cookies, POST data, uploaded files, auto-generated cURL command. Two trigger methods: HTTP auth (http-dump@host) or X-Buggregator-Event: http-dump header. Use cases: webhook development, API debugging, request replay. For capturing both request and response, see HTTP Proxy on port 8080.
- [HTTP Proxy — Request & Response Capture](/config/http-proxy.md): HTTP forward proxy on port 8080 with MITM for HTTPS. Captures full request+response pairs (method, URL, headers, body, status code, timing) as http-dump events. Clients set proxy URL and disable SSL verification. Works with any language: PHP Guzzle (proxy+verify), Go (http.Transport Proxy+InsecureSkipVerify), JavaScript fetch/axios (https-proxy-agent), Python requests (proxies+verify), curl (-x -k), env vars (HTTP_PROXY/HTTPS_PROXY). UI shows response body with JSON tree view, HTML preview, syntax highlighting.
- [Inspector — Application Monitoring](/config/inspector.md): Inspector.dev SDK compatibility for local APM: transaction name, duration, memory peak, result status, HTTP details, timeline breakdown. Config: INSPECTOR_URL=http://inspector@host:8000, INSPECTOR_API_KEY, INSPECTOR_INGESTION_KEY. Laravel and generic PHP setup. INSPECTOR_SECRET_KEY env for access restriction.
- [Configuration — MCP (Model Context Protocol)](/config/mcp.md): MCP (Model Context Protocol) server for AI assistant integration. Two transports: Unix socket (default) and HTTP/SSE. Available tools: events_list, event_get, event_delete, sentry_event, vardump_get, profiler_summary, profiler_top, profiler_call_graph. Integration with Claude Code, Cursor, and other MCP-compatible clients.
- [Configuration — Metrics](/config/metrics.md): Prometheus metrics: enable via METRICS_ENABLED=true. Serve on main HTTP server at /metrics or on a separate address via METRICS_ADDR. Event counters by type (sentry, monolog, var-dumper, ray, inspector, http-dump, profiler, smtp). HTTP request metrics, WebSocket connection gauges, TCP server status. Grafana integration.
- [Monolog — Logs](/config/monolog.md): Monolog log collection via SocketHandler on TCP port 9913 with JsonFormatter. UI shows channel, message, PSR-3 severity level, timestamp, context JSON, extra fields, source location. Config for Laravel (socket channel in logging.php), Spiral (LoggingBootloader), Symfony (monolog.php handler), generic PHP (monolog/monolog SocketHandler).
- [JetBrains IDE Plugin](/config/phpstorm-plugin.md): JetBrains IDE plugin: embeds Buggregator Trap UI into PhpStorm, IntelliJ IDEA, WebStorm. Requires buggregator/trap Composer package and PHP interpreter. Two views: Web UI (embedded browser) and Terminal. Settings: PHP interpreter, path to Trap binary, Web UI port. Install from JetBrains Marketplace or manual .jar.
- [Configuration — Projects](/config/projects.md): Multi-project support: configured in buggregator.yaml with key/name pairs. Default project key 'default'. Per-project DSN formats for Sentry (http://key@host/project_key), Inspector (inspector:project_key@host), XHProf (profiler:project_key@host), Ray (ray:project_key@host). VarDumper and Monolog do not support projects.
- [Ray — Debug Tool](/config/ray.md): Spatie Ray compatibility: free self-hosted alternative supporting 18 payload types (Log, Caller, Carbon, Trace, Exception, Table, Measure, Query, Eloquent, View, Event, Job, Lock, Mailable, Notify, Origin). Config: RAY_HOST=ray@host, RAY_PORT=8000. Setup for Laravel (ray:publish-config), PHP (ray.php config file), JavaScript, Ruby, Go, Bash SDKs.
- [Sentry — Exceptions](/config/sentry.md): Sentry SDK compatibility: DSN format http://sentry@host:8000/1. Setup for Laravel (SENTRY_LARAVEL_DSN), Spiral, Symfony, Magento 2, WordPress (WP Sentry plugin), JavaScript, Python, and any Sentry SDK. UI shows stack traces, breadcrumbs, request/device/app info, tags, modules.
- [Configuration — Server](/config/server.md): Server configuration via buggregator.yaml, environment variables, and CLI flags. Covers HTTP address, CORS, database (SQLite), storage modes, TCP ports (SMTP, Monolog, VarDumper), module enable/disable, metrics, auth, MCP, webhooks, projects. Priority: CLI flags > env vars > config file > defaults.
- [SMS Gateway Interceptor](/config/sms.md): SMS gateway interceptor: /sms endpoint with auto-detection for 40+ providers (Twilio, Vonage, Plivo, Sinch, Infobip, MessageBird, Telnyx, etc.). Explicit provider URLs (/sms/twilio) for field validation with 422 responses. Symfony Notifier DSN config, Laravel HTTP example, generic curl. Supports JSON and form-urlencoded payloads, project URL segments.
- [SMTP — Email Testing](/config/smtp.md): Fake SMTP server on port 1025: captures outgoing emails with HTML preview (desktop/mobile viewport), plain text, addresses (From/To/CC/BCC), attachments, raw MIME source. Config for Laravel (MAIL_HOST/MAIL_PORT), Spiral (MAILER_DSN), Symfony, Magento 2, WordPress (mu-plugin phpmailer_init hook).
- [Configuration — Single Sign-On (SSO)](/config/sso.md): SSO authentication with OAuth2/OIDC providers: Auth0, Google, GitHub, Keycloak, GitLab, and generic OIDC. Environment variables: AUTH_ENABLED, AUTH_PROVIDER, AUTH_PROVIDER_URL, AUTH_CLIENT_ID, AUTH_CLIENT_SECRET, AUTH_CALLBACK_URL, AUTH_SCOPES, AUTH_JWT_SECRET. OIDC auto-discovery for compatible providers. Callback endpoint /auth/sso/callback.
- [VarDumper — Variable Dumps](/config/var-dumper.md): Symfony VarDumper integration via TCP port 9912: VAR_DUMPER_FORMAT=server, VAR_DUMPER_SERVER=host:9912. UI shows dumped values as interactive tree, source location with IDE click-to-open, variable labels. VAR_DUMPER_PREVIEW_MAX_DEPTH env for performance. Syntax highlighting via trap() context(language:). Buggregator Trap alternative with trap()/tr()/td() helpers.
- [Configuration — Webhooks](/config/webhooks.md): Webhook configuration in buggregator.yaml. Fields: event (type filter or '*' for all), url, headers, verify_ssl, retry. Supported event types: sentry, ray, var-dump, inspector, monolog, smtp, sms, http-dump, profiler, or '*' for all. Retry up to 3 times with exponential backoff. Delivery tracking via API.
- [XHProf — Performance Profiling](/config/xhprof.md): XHProf profiling integration: Call Graph, Flame Graph, Top Functions table, profile comparison. Setup: pecl install xhprof, packages for Laravel (maantje/xhprof-buggregator-laravel), Spiral (spiral/profiler), generic PHP (spiral-packages/profiler). PROFILER_ENDPOINT config, custom client via HTTP auth, X-Buggregator-Event header, or /api/profiler/store endpoint.
- [Getting Started](/getting-started.md): Installation via standalone binary (~30 MB, curl one-liner), Docker run, Docker Compose, and Kubernetes. Port mapping: 8000 (HTTP/Sentry/Ray/Inspector/XHProf/SMS/HTTP Dumps), 1025 (SMTP), 9912 (VarDumper TCP), 9913 (Monolog TCP). Configuration via buggregator.yaml, environment variables, or CLI flags. Image tags: latest, dev, versioned.
- [What is Buggregator?](/index.md): Buggregator overview: self-hosted debugging server via Docker or standalone ~30 MB binary, supports XHProf profiling, Sentry exceptions, fake SMTP email capture, SMS gateway, HTTP request dumps, Monolog logs, Symfony VarDumper, Spatie Ray, Inspector APM. Includes event pinning, screenshots, keyboard shortcuts, IDE integration, multi-project support, webhooks, Prometheus metrics, SSO auth, MCP for AI assistants. Built with Go, Vue 3, SQLite. Free forever, MIT licensed.
- [Using Buggregator docs with AI assistants](/llm.md): LLM-readable documentation endpoints: llms.txt index, llms-full.txt complete docs, per-page .md files. Usage with ChatGPT, Claude, Cursor, Windsurf, and other AI assistants for Buggregator setup and configuration help.
- [Trap — Commands](/trap/commands.md): Trap CLI commands: 'run' (--port/-p, --sender/-s, --ui), 'test' (sends XHProf/dumps/emails/Sentry/binary test data), 'joke'. Default ports: 1025, 8000, 9912, 9913. Senders: console, file, file-body, mail-to-file, server. Environment variables: TRAP_TCP_PORTS, TRAP_TCP_HOST, TRAP_UI_PORT, TRAP_UI_HOST, TRAP_XHPROF_PATH, TRAP_MAIN_LOOP_INTERVAL.
- [Trap — Getting Started](/trap/getting-started.md): Trap installation: standalone binary download (Linux/macOS/Windows amd64/arm64) or Composer (buggregator/trap). Start with 'vendor/bin/trap' or './trap'. trap() function usage: basic dumps, named arguments, ->return(), ->depth(). Web UI via --ui flag on port 8000.
- [Trap — Functions](/trap/usage.md): Trap PHP functions: trap(mixed ...$values) with ->stackTrace(), ->depth(), ->if(), ->once(), ->times(), ->return(), ->context(), ->code() methods. tr() shorthand for trap()->return() and performance ticker (time/memory between calls). td() dump-and-die. Protobuf message support. TrapHandle method chaining API.
- [Trap — What is it?](/trap/what-is-trap.md): Buggregator Trap: lightweight PHP CLI debugging tool, alternative to Symfony VarDumper. Zero-config, standalone binary (Linux/macOS/Windows), no Docker needed. Supports VarDumper, Monolog, Sentry, SMTP, HTTP dumps, Ray handlers. Protobuf debugging. Console and dashboard UI. Cross-project compatible.

## Optional

- [Contributing to Buggregator](/contributing.md): Contributing guide: issue labels (for contributors, c:easy/c:medium/c:difficult), project repositories (Server, Frontend, Trap, Documentation, Site, PHPStorm Plugin). Benefits of contributing to open source.
- [Contributing — Documentation](/contributing/docs.md): Documentation contributing: VitePress-based docs. Setup: git clone buggregator/docs, npm install, npm run docs:dev. Structure: docs/ directory for markdown files, docs/.vitepress/config.mts for site config and navigation.
- [Contributing — Frontend side](/contributing/frontend.md): Frontend contributing: Vue 3, TailwindCSS, Storybook stack. Requirements: Node.js 20+ (22 preferred), Yarn 1.22+. Setup: git clone, yarn install, yarn dev (port 3000). Storybook at port 6006 for component isolation.
- [Contributing — Server side](/contributing/server.md): Server-side contributing: Go 1.26+, SQLite, modular architecture. Build with make build, test with go test ./..., single binary output. Module system for HTTP and TCP event handlers.
- [Cookbook — Dev environment using Docker Compose](/cookbook/docker-install.md): Docker Compose dev environment setup: git clone, make build, make run. Starts Buggregator Go server with example services. Access at localhost:8000. Requires Go 1.26+, Make.
- [Cookbook — Manual Installation](/cookbook/manual-install.md): Manual installation without Docker: download standalone Go binary from GitHub Releases, run directly. Configuration via buggregator.yaml or environment variables. No external dependencies required.