proxy-config.example.yaml

# Example configuration for the ethpandaops proxy server.
# The proxy holds datasource credentials and proxies requests from sandbox containers.
#
# Usage:
#   Local dev:  panda-proxy --config proxy-config.yaml
#   Production: Deploy as a K8s service
#
# The server connects to this proxy via a `proxies[].url` entry. The legacy
# single `proxy.url` form is still accepted when used alone.
#
# Environment variables can be substituted using ${VAR_NAME} or ${VAR_NAME:-default} syntax.

server:
  # Address to listen on
  listen_addr: ":18081"

  # HTTP timeouts
  read_timeout: 30s
  write_timeout: 5m
  idle_timeout: 60s

auth:
  # Authentication mode:
  # - "none": No authentication (for local development only - DEFAULT)
  # - "oauth": Embedded GitHub-backed OAuth issuer hosted by panda-proxy
  # - "oidc": External OpenID Connect issuer (Dex, authentik, Keycloak, ...)
  mode: none  # Use 'oauth' or 'oidc' for hosted remote access

  # External URL of the proxy's own issuer, used for OAuth metadata and callbacks.
  # Required (and only used) when mode is "oauth".
  # issuer_url: "https://proxy.example.com"

  # Client identifier advertised to clients for login (mode "oauth").
  # client_id: "panda-proxy"

  # Trusted external OIDC issuers (required when mode is "oidc"). A bearer token
  # is accepted if it verifies against ANY of them, so you can trust e.g. humans
  # on one IdP and CI service accounts on another. The first issuer is advertised
  # to clients for interactive login.
  # issuers:
  #   - issuer_url: "https://dex.example.com"
  #     client_id: "panda-proxy"
  #   - issuer_url: "https://authentik.example.com/application/o/panda-proxy/"
  #     client_id: "panda-eval"

  # GitHub OAuth app config (required when mode is "oauth")
  # github:
  #   client_id: "${GITHUB_CLIENT_ID}"
  #   client_secret: "${GITHUB_CLIENT_SECRET}"

  # Limit remote access to selected GitHub orgs
  # allowed_orgs:
  #   - ethpandaops
  #   - sigp

  # Proxy-issued bearer token signing key
  # tokens:
  #   secret_key: "${PROXY_TOKEN_SECRET}"

  # Proxy-issued token lifetimes
  # access_token_ttl: 1h
  # refresh_token_ttl: 720h

  # Customize the OAuth callback success page shown in the browser.
  # Rules are evaluated in order; the first match wins.
  # success_page:
  #   rules:
  #     - match:
  #         orgs: ["ethpandaops"]
  #         users: ["samcm", "mattevans"]
  #       media:
  #         type: ascii
  #         ascii_art_base64: "base64-encoded-art-here"
  #       tagline: "Enjoy debugging your devnet champ"
  #     - match:
  #         orgs: ["ethpandaops"]
  #       media:
  #         type: gif
  #         url: "https://example.com/cool.gif"
  #       tagline: "Enjoy debugging your devnet champ"
  #   default:
  #     tagline: "You can close this window and return to your terminal."

# ClickHouse clusters
clickhouse:
  - name: clickhouse-raw
    description: "Raw ClickHouse cluster with raw Ethereum event data"
    host: "${CLICKHOUSE_XATU_HOST}"
    port: 8443
    database: "${CLICKHOUSE_XATU_DATABASE}"
    username: "${CLICKHOUSE_XATU_USERNAME}"
    password: "${CLICKHOUSE_XATU_PASSWORD}"
    secure: true
    skip_verify: false
    timeout: 300
    # Declare the datasets stored in this cluster. `dataset` must match a
    # knowledge pack shipped with the release (see datasets/). `params` are
    # opaque hints the pack interprets. `notes` says what distinguishes THIS
    # copy from the dataset's other copies — nothing else: universal query
    # knowledge belongs in the dataset pack, cluster-wide behavior in the
    # datasource description. The proxy never interprets params or notes.
    contains:
      - dataset: xatu-raw
        params: { database: default }
        notes: "Public networks (mainnet, testnets)."
      - dataset: xatu-raw
        params: { database_pattern: "*" } # per-devnet databases (glamsterdam-devnet-6, …)
        notes: "Devnet networks; one database per devnet."
      - dataset: otel-logs
        params: { database: external }
        notes: "Devnet/testnet node container logs (tracked networks)."
      - dataset: otel-logs
        params: { database: internal }
        notes: "Operator platform/infrastructure logs (k8s clusters, sentries, services)."
    # Restrict access to members of specific GitHub orgs.
    # Omit or leave empty to allow all authenticated users.
    # allowed_orgs:
    #   - ethpandaops

  - name: clickhouse-refined
    description: "Refined ClickHouse cluster with pre-aggregated Ethereum data (distributed: wrap subqueries you JOIN against in GLOBAL)"
    host: "${CLICKHOUSE_REFINED_HOST}"
    port: 8443
    database: "${CLICKHOUSE_REFINED_DATABASE}"
    username: "${CLICKHOUSE_REFINED_USERNAME}"
    password: "${CLICKHOUSE_REFINED_PASSWORD}"
    secure: true
    skip_verify: false
    timeout: 300
    contains:
      - dataset: xatu-cbt
        params: { database_pattern: "*" } # per-network databases (mainnet, holesky, …)
    # allowed_orgs:
    #   - ethpandaops

  # Optional dynamic local datasource. The prober adds it only while /ping
  # returns "Ok." and the configured database exists.
  # - name: local-kurtosis
  #   description: "Local Kurtosis devnet logs (OpenTelemetry, autodiscovered)"
  #   host: localhost
  #   port: 18123
  #   database: otel
  #   autodiscover: true
  #   autodiscover_interval: 10s
  #   contains:
  #     - dataset: otel-logs
  #       params: { database: otel }
  #       notes: "Local Kurtosis devnet logs."

# Prometheus instances
prometheus:
  - name: platform
    description: "Platform Prometheus/VictoriaMetrics instance"
    url: "${PROMETHEUS_PLATFORM_URL}"
    username: "${PROMETHEUS_PLATFORM_USERNAME}"
    password: "${PROMETHEUS_PLATFORM_PASSWORD}"
    # allowed_orgs:
    #   - ethpandaops

  - name: devnets
    description: "Devnets Prometheus instance"
    url: "${PROMETHEUS_DEVNETS_URL}"
    username: "${PROMETHEUS_DEVNETS_USERNAME}"
    password: "${PROMETHEUS_DEVNETS_PASSWORD}"
    # allowed_orgs:
    #   - ethpandaops

# Loki instances
loki:
  - name: primary
    description: "Primary Loki instance"
    url: "${LOKI_URL}"
    username: "${LOKI_USERNAME}"
    password: "${LOKI_PASSWORD}"
    # allowed_orgs:
    #   - ethpandaops

# Benchmarkoor: execution-client benchmark results (read-only API key, bmk_...)
# benchmarkoor:
#   - name: production
#     description: "ethPandaOps execution-client benchmark results"
#     url: "https://benchmarkoor-api.core.ethpandaops.io"
#     ui_url: "https://benchmarkoor.core.ethpandaops.io"
#     api_key: "${BENCHMARKOOR_API_KEY}"
#     # allowed_orgs:
#     #   - ethpandaops

# Compute: ephemeral-sandbox control plane (core ethpandaops members only).
# The proxy verifies the caller's OIDC token, gates access via allowed_orgs, and
# forwards that same token to the backend, which validates it directly and
# derives the user from it. No service token is configured here.
# compute:
#   - name: production
#     description: "ethPandaOps compute sandboxes"
#     url: "${COMPUTE_URL}"
#     allowed_orgs:
#       - ethpandaops:Core

# Workflow engine passthrough (optional). Relays /workflow/* to the workflow
# engine API; SSE streams end-to-end. Two auth modes:
#
#   token       - the proxy injects the api_token below; the caller's bearer
#                 never reaches upstream. api_token is required.
#   passthrough - the proxy re-attaches the caller's own verified bearer
#                 unchanged; the engine validates it directly. api_token must
#                 be empty, and this proxy's auth.mode must be oauth or oidc.
#                 Callers must request the "workflows" scope at login so
#                 Authentik cross-grants the engine audience into their token.
#
# The api_token lives HERE, never on the panda server.
# workflow:
#   url: "${WORKFLOW_ENGINE_URL}"               # bare scheme+host[:port], no path
#   auth_mode: "passthrough"                    # token | passthrough
#   # api_token: "${WORKFLOW_ENGINE_API_TOKEN}" # required for auth_mode: token; omit for passthrough
#   web_url: ""                                 # optional, defaults to url
#   # allowed_orgs gates the engine to members of these orgs/groups: OIDC groups
#   # (e.g. "ethpandaops:Core") in oidc mode, or GitHub orgs in oauth mode. The
#   # proxy filters the advert out of discovery for callers who lack it, so the
#   # panda CLI hides `panda workflow` from them too. Empty leaves it open to all.
#   allowed_orgs:
#     - ethpandaops:Core

# Ethereum node API access (beacon and execution nodes)
# Single credential pair for all bn-*.srv.*.ethpandaops.io and rpc-*.srv.*.ethpandaops.io endpoints
# ethnode:
#   username: "${ETHPANDAOPS_ETHNODE_USERNAME}"
#   password: "${ETHPANDAOPS_ETHNODE_PASSWORD}"
#   allowed_orgs:
#     - ethpandaops

# Embedding API v1 (optional — enables legacy symmetric remote embedding).
# embedding:
#   api_key: "${OPENROUTER_API_KEY}"
#   model: "openai/text-embedding-3-small"
#   api_url: "https://openrouter.ai/api/v1"  # base URL of the embedding API
#   cache:
#     backend: memory  # or "redis"
#     # redis_url: "redis://localhost:6379"
#
# Embedding API v2/v3 (optional — enables fixed-dimensional embedding).
# The model should support asymmetric retrieval embedding (input_type): v3
# requests are task-typed as a search query or an indexed document.
# embedding_v2:
#   api_key: "${OPENROUTER_API_KEY}"
#   model: "google/gemini-embedding-2"
#   api_url: "https://openrouter.ai/api/v1"  # base URL of the embedding API
#   dimensions: 1536                         # fixed output dimensionality
#   cache:
#     backend: memory  # or "redis"
#     # redis_url: "redis://localhost:6379"

# GitHub API (optional — enables triggering GitHub Actions workflows)
# github:
#   token: "${GITHUB_TOKEN}"  # PAT or app token with actions:write permission

# Uploads (optional — the publish target for `panda upload`). Private previews
# stay in the local server; this bucket holds only files the user chose to make
# public. Content-addressed: key is <key_prefix><6-hex-of-sha256>/<filename>.
# Built-in abuse guards: a per-user rate limit, a size cap (max_object_bytes),
# filename sanitization, and forced download (Content-Disposition: attachment)
# for scriptable types (html/svg/js) so a public bucket can't serve them inline.
# Set a 60-day object lifecycle scoped to key_prefix for retention.
#
# render_html serves uploaded text/html inline (so HTML/markdown diagnostics
# render in the browser) instead of downloading. Turn it on ONLY after adding a
# Cloudflare Transform Rule on public_base_url's hostname that sets, on text/html
# responses:
#   Content-Security-Policy: sandbox allow-scripts allow-downloads
# That header pins uploaded HTML to an opaque origin — no cookies, no
# credentialed same-origin requests, cannot impersonate the bucket domain — which
# is what makes rendering shared HTML safe. Use a dedicated bucket/domain that
# shares no auth cookies with any product site. Without the rule, leave this off.
# uploads:
#   bucket: "ethpandaops-panda-uploads"
#   key_prefix: "panda/uploads/"            # namespaces panda uploads in the bucket
#   public_base_url: "https://assets.ethpandaops.io"
#   endpoint: "https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com"
#   access_key_id: "${R2_UPLOADS_ACCESS_KEY_ID}"
#   secret_access_key: "${R2_UPLOADS_SECRET_ACCESS_KEY}"
#   max_object_bytes: 104857600             # 100 MiB (default if omitted)
#   render_html: false                      # true only with the CSP rule above
#   # Optional team tier (`panda upload --team` / the preview's "Share with team"):
#   # same bucket, separate prefix, served from a Cloudflare-Access-protected
#   # domain (GitHub org login) instead of the public one. Set both or neither.
#   team_key_prefix: "panda/team/"
#   team_base_url: "https://panda-notes.example.io"

# Rate limiting
rate_limiting:
  enabled: true
  requests_per_minute: 60
  burst_size: 10

# Audit logging
audit:
  enabled: true
  # Capture the upstream request payload (e.g. the ClickHouse SQL) in each audit
  # entry. The full body is always forwarded upstream; only the audited copy is
  # truncated to max_body_bytes.
  log_request_body: true
  # Capture the upstream response payload. Response bodies can be large (full
  # result sets), so leave this off unless you need it.
  log_response_body: false
  # Cap on stored bytes per captured body (0 = 64KiB default).
  max_body_bytes: 65536

# Prometheus metrics
metrics:
  enabled: true
  listen_addr: "127.0.0.1:9090"
  port: 9090