buggregator.yaml.example

# Buggregator configuration file.
#
# Place as buggregator.yaml next to the binary, or specify with --config flag.
# All values support environment variable substitution: ${VAR} and ${VAR:default}
#
# Every setting has a sensible default — this file is entirely optional.

# HTTP server
server:
  addr: ${HTTP_ADDR::8000}
  cors_origins:                           # Allowed CORS origins. Default: ["*"] (all origins).
    - "*"                                 # Use specific origins to restrict: ["http://localhost:3000"]

# Database
database:
  driver: sqlite                        # Only SQLite supported for now
  dsn: ${DATABASE_DSN::memory:}         # ":memory:" (default), "data.db", or full path
  max_open_conns: ${DATABASE_MAX_OPEN_CONNS:4}  # SQLite connection pool size. 1 serializes the UI with ingestion.
                                        # Needs journal_mode(WAL) in the DSN to be worth anything.

# Attachment storage (SMTP attachments, HTTP dump files)
storage:
  mode: ${STORAGE_MODE:memory}          # "memory" (default, lost on restart) or "filesystem"
  path: ${STORAGE_PATH:./storage}       # Directory for filesystem mode

# UI event lists: how much /api/events and /api/events/preview return
ui:
  default_limit: ${UI_DEFAULT_LIMIT:}       # Events returned when the request has no limit param. Empty or 0 = unlimited
  max_limit: ${UI_MAX_LIMIT:5000}           # Ceiling for an explicit ?limit=. 0 = no ceiling
  default_window: ${UI_DEFAULT_WINDOW:}     # Default time window, e.g. "1h", "24h", "7d". Empty = no window

# Prometheus metrics
metrics:
  enabled: ${METRICS_ENABLED:false}       # Set to true to expose Prometheus metrics
  addr: ${METRICS_ADDR:}                  # Separate metrics server address (e.g., ":9090")
                                          # Leave empty to serve /metrics on the main HTTP server

# Authentication via OAuth2/OIDC providers.
# Supported providers: auth0, google, github, keycloak, gitlab, oidc (generic OIDC).
# For OIDC-compatible providers (auth0, google, keycloak, gitlab, oidc), endpoints are
# auto-discovered from provider_url via .well-known/openid-configuration.
# For GitHub, endpoints are hardcoded (no OIDC support).
# auth:
#   enabled: false
#   provider: ${AUTH_PROVIDER:oidc}               # Provider type
#   provider_url: ${AUTH_PROVIDER_URL:}            # OIDC issuer URL (e.g., https://xxx.us.auth0.com)
#   client_id: ${AUTH_CLIENT_ID:}                  # OAuth2 client ID
#   client_secret: ${AUTH_CLIENT_SECRET:}          # OAuth2 client secret
#   callback_url: ${AUTH_CALLBACK_URL:}            # Callback URL (e.g., http://localhost:8000/auth/sso/callback)
#   scopes: ${AUTH_SCOPES:openid,email,profile}    # Comma-separated scopes
#   jwt_secret: ${AUTH_JWT_SECRET:}                # Secret for signing internal JWT tokens (required)

# TCP servers
tcp:
  smtp:
    addr: ${SMTP_ADDR::1025}
  monolog:
    addr: ${MONOLOG_ADDR::9913}
  var-dumper:
    addr: ${VAR_DUMPER_ADDR::9912}

# MCP server: lets AI agents (Claude Code, Codex, Cursor...) read events, Sentry
# errors, dumps and profiles, and delete events. Off by default.
# transport: socket — a Unix socket on this machine; the agent starts `buggregator mcp`
# as its MCP command, which connects to the socket. No auth: keep the socket local.
# transport: http — remote access on addr; set auth_token, or anyone who can reach
# the port can use the tools.
# mcp:
#   enabled: ${MCP_ENABLED:false}
#   transport: ${MCP_TRANSPORT:socket}                      # socket or http
#   socket_path: ${MCP_SOCKET_PATH:/tmp/buggregator-mcp.sock} # For transport=socket
#   addr: ${MCP_ADDR::8001}                                 # For transport=http (all interfaces)
#   auth_token: ${MCP_AUTH_TOKEN:}                          # Bearer token for transport=http. Empty = no auth
#   mock_write: ${MCP_MOCK_WRITE:true}                       # mock_rule_create/update/delete/from_request, mock_import_openapi, mock_group_delete; false = read and preview only

# Xdebug proxy: PHP/Xdebug -> Buggregator -> IDE, plus MCP tools (xdebug_sessions,
# xdebug_location, xdebug_stack, xdebug_variables, xdebug_property, xdebug_eval) on
# the same paused session; xdebug_eval runs PHP code, only with allow_eval.
# With allow_control an agent also drives a session that has no IDE
# (xdebug_step, xdebug_continue, xdebug_stop), waits for a pause (xdebug_wait) and
# sets breakpoints (xdebug_breakpoint_set, xdebug_breakpoint_remove; listing them,
# xdebug_breakpoints, is always on). Breakpoints are saved in the database and sent
# to every session Buggregator drives; a condition is PHP code and needs allow_eval.
# Off by default. MCP tools need mcp.enabled.
# mode: proxy — relay to the IDE; no IDE = the script runs on without a debugger.
#       auto — relay when the IDE answers, else Buggregator drives the session
#              (step, continue, stop in the UI). standalone — never dial the IDE.
# While an IDE is attached it drives; Buggregator only reads.
# Same host: point Xdebug at addr (xdebug.client_port=9003) and move the IDE's
# debug port to ide_addr (PhpStorm: Settings > PHP > Debug > Debug port 9004).
# xdebug:
#   enabled: ${XDEBUG_PROXY_ENABLED:false}
#   addr: ${XDEBUG_PROXY_ADDR:127.0.0.1:9003}         # Where Xdebug connects
#   ide_addr: ${XDEBUG_PROXY_IDE_ADDR:127.0.0.1:9004} # Where the IDE listens
#   allow_eval: ${XDEBUG_PROXY_ALLOW_EVAL:false}      # Let MCP clients evaluate PHP expressions
#   allow_control: ${XDEBUG_PROXY_ALLOW_CONTROL:true} # MCP step/continue/stop/wait; false = read only
#   mode: ${XDEBUG_PROXY_MODE:auto}                   # proxy, auto or standalone
#   pause_on_first_line: ${XDEBUG_PROXY_PAUSE_ON_FIRST_LINE:false} # With no IDE: stop at the first line
#   idle_timeout: ${XDEBUG_PROXY_IDLE_TIMEOUT:10m}    # With no IDE: release a session paused this long (a Go duration: 90s, 10m); 0 = never

# Enable/disable modules. All enabled by default.
# Set to false to disable a module entirely (TCP port won't bind, events ignored).
# Can also be controlled via CLIENT_SUPPORTED_EVENTS env (comma-separated list).
modules:
  sentry: true
  ray: true
  var-dump: true
  inspector: true
  monolog: true
  smtp: true
  sms: true
  http-dump: true
  profiler: true

# Webhooks — send HTTP POST notifications when events are received.
# Each webhook fires for a specific event type, or "*" for all events.
# Payload: { uuid, type, payload, timestamp, project }
# webhooks:
#   - event: "*"                          # Fire on any event type
#     url: https://slack.example.com/webhook
#     headers:
#       Authorization: "Bearer token123"
#     verify_ssl: false                   # Default: false
#     retry: true                         # Retry up to 3 times with exponential backoff (default: true)
#   - event: sentry                       # Fire only on Sentry events
#     url: https://pagerduty.example.com/alert
#   - event: smtp                         # Fire only on SMTP events
#     url: https://my-app.example.com/email-hook

# Mock server — requests to http://<host>:8000/mock<path> get the response of
# the first matching rule and are captured as HTTP dumps. Rules defined here are
# read-only in the UI and come before the rules made in the UI.
# Path forms: /users/me (exact), /users/{id} (one segment), /files/* (the rest).
# Unmatched requests get 404 with a JSON error and are still captured.
# mocks:
#   - method: GET                  # GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS or ANY (default)
#     path: /users/{id}
#     status: 200                  # default 200
#     headers: { Content-Type: application/json }
#     body: '{"id": 1, "name": "Jane"}'
#     delay: 150ms                 # optional, at most 30s
#     project: default             # optional; empty = every project
#   - method: GET                  # a dynamic response: request values and fake data
#     path: /orders/{id}
#     template: true               # body and header values are Go templates
#     seed: 42                     # optional; not 0 = the same fake data on every request
#     headers: { Content-Type: application/json }
#     body: '{"id": {{ path "id" }}, "customer": {{ fake "name" | json }}, "total": {{ fake "price" 5 500 }}}'

# OpenAPI 3.0/3.1 specs (YAML or JSON) turned into read-only mock rules at start:
# one rule per operation; the spec's example as the body, else a template with
# fake data built from the schema. Paths get servers[0].url's path in front.
# mocks_openapi:
#   - file: ./openapi.yaml
#     project: shop                # optional; empty = every project
#     group: shop-api              # optional; default openapi:<project>:<info.title>
#     base_path: ""                # optional; "" = no prefix

# Pre-defined projects. The "default" project always exists.
# Additional projects can be defined here.
# projects:
#   - key: my-app
#     name: My Application
#   - key: staging
#     name: Staging Environment