.env.example

DB_HOST=localhost
DB_PORT=6380
DB_USERNAME=default
DB_PASSWORD=devpassword
DB_TYPE=auto
# Connect to the monitored database over TLS. Set to true for managed providers
# that require encryption (Aiven, ElastiCache Serverless, etc.). Default false.
DB_TLS=false

# SSH Tunnel Configuration
# Directory containing SSH private keys that connections may reference by path
# (the "server file path" key source). A connection's private key path must
# resolve inside this directory. Leave unset to disable server-side key files;
# inline (pasted) keys always work regardless of this setting.
BETTERDB_SSH_KEY_DIR=

# Storage Configuration
STORAGE_TYPE=sqlite
STORAGE_SQLITE_FILEPATH=./data/audit.db
# PostgreSQL TLS: point STORAGE_SSL_CA at a CA cert (file path or trusted https
# URL) to verify the server chain. If your managed provider (e.g. Aiven) presents
# its own CA and injects sslmode=require, set STORAGE_SSL_NO_VERIFY=true to connect
# over TLS without chain verification instead.
# STORAGE_SSL_CA=
# STORAGE_SSL_NO_VERIFY=false
# Turso / libSQL (opt-in, STORAGE_TYPE=turso). STORAGE_AUTH_TOKEN is required for libsql:// URLs.
# A hosted https:// endpoint needs the token too, but startup does not enforce it there:
# an https:// URL with no token starts cleanly and fails on the first query.
# A token on an http:// URL is rejected at startup: it would cross the network
# in cleartext. Use http:// only for an unauthenticated local sqld.
# STORAGE_TYPE=turso
# STORAGE_URL=libsql://your-db.turso.io
# STORAGE_AUTH_TOKEN=

# Audit Trail Configuration
AUDIT_POLL_INTERVAL_MS=60000

# Data Retention (self-hosted)
# Days of monitoring history to keep; a daily sweep deletes older rows. Unset =
# keep forever. Seeds the app setting when the settings row is first created;
# after that, manage it from Settings -> Data Retention in the UI.
# LOCAL_RETENTION_DAYS=30

# Activity log: days to keep recorded mutations, CLI commands and sign-ins
ACTIVITY_RETENTION_DAYS=90

# Cluster node auto-registration: default for cluster connections that have not
# set their own "Auto-register cluster nodes" toggle.
CLUSTER_AUTO_REGISTER_NODES=false

# Sentinel node auto-registration: default for Sentinel connections that have
# not set their own "Auto-register Sentinel nodes" toggle.
SENTINEL_AUTO_REGISTER_NODES=false

# AI Cache & Memory Observability
# Poll interval (ms) for the Valkey-native AI cache/memory stats poller.
AI_OBS_POLL_INTERVAL_MS=15000
# OTLP/HTTP trace ingestion (/v1/traces). Set ENABLED=false (or 0) to disable the endpoint.
OTEL_INGEST_ENABLED=true
# Bearer token for OTLP ingestion. Optional self-hosted; REQUIRED in cloud mode,
# where /v1/traces is the tenant's only ingest credential.
OTEL_INGEST_TOKEN=
# Age (ms) after which a pushed OTLP metric is ignored as stale; min 60000.
# Must exceed the exporter push interval (at least 2x is recommended).
# OTEL_METRICS_STALE_AFTER_MS=300000
# List OTLP pushes from unregistered instances under "discovered via OTLP" in the connection switcher
OTLP_DISCOVER_INSTANCES=true

# OTel metrics export (mirror of the Prometheus /metrics registry over OTLP).
# No-op unless OTEL_EXPORTER_OTLP_ENDPOINT is set. Set ENABLED=false to disable
# even when an endpoint is present.
OTEL_TELEMETRY_ENABLED=true
# Set false to keep the metrics mirror but disable OTLP event/log export
# (needed when the endpoint is a metrics-only receiver like Prometheus).
OTEL_EVENTS_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=
OTEL_METRICS_EXPORT_INTERVAL_MS=15000
# mirror | semconv (default mirror)
OTEL_METRICS_EXPORT_MODE=mirror

# Prometheus /prometheus/metrics scrape endpoint. Set ENABLED=false to disable
# the endpoint (answers 404). Bearer token for the endpoint. Optional
# self-hosted; REQUIRED in cloud mode, where this is the endpoint's only
# credential.
PROMETHEUS_METRICS_ENABLED=true
PROMETHEUS_METRICS_TOKEN=
# Optional second accepted token, meant to be published (e.g. a live demo
# scrape credential). Rotating it does not affect scrapes using the primary.
PROMETHEUS_METRICS_PUBLIC_TOKEN=
# vitals | full (default full)
METRICS_EXPORT_PROFILE=full
# Top N slots by key count for cluster slot stats; 0 disables
METRICS_SLOT_STATS_TOP_N=100
# Top N key patterns by memory for key-size metrics; 0 disables (Pro key analytics)
METRICS_KEY_PATTERNS_TOP_N=100
# Top N largest keys exported per connection (max 50); 0 disables per-key series
METRICS_KEY_DETAILS_TOP_N=10

# CVE Inspection
# Refreshes the advisory corpus (GHSA, NVD, MITRE, CISA KEV, FIRST EPSS) every
# six hours and scans each connection against it. Set to false on egress
# restricted or air-gapped installs: no outbound request is made, /cve/dataset
# reports an empty corpus, and /cve/scan answers 503 rather than a false clear.
CVE_ENABLED=true

# Optional GitHub token for the GHSA advisory feed. Unauthenticated, GitHub
# allows 60 requests/hour per IP, shared with everything else on that address;
# when that budget is exhausted GHSA drops out of the scan and the page reports
# the result as incomplete. A token raises the limit to 5,000/hour. GHSA is the
# only source that carries fix versions, so a token is worth setting. Needs no
# scopes - it reads public advisory data.
CVE_GITHUB_TOKEN=

# Self-hosted user control. Set to true to run without login, roles or the Team page.
WORKSPACE_DISABLED=false
# better-auth signing secret (min 32 chars). Generated and persisted under BETTERDB_DATA_DIR when unset.
# AUTH_SECRET=
# Public origin of this deployment, e.g. https://monitor.example.com. Inferred from request headers when unset.
# Session cookies are marked Secure only when this starts with https://, so set it on HTTPS installs
# (including behind a TLS-terminating proxy).
# AUTH_PUBLIC_URL=
# Trust X-Forwarded-For/Host/Proto from a reverse proxy: a list of proxy addresses/CIDRs, or true
# when the API is only reachable through the proxy. Hop counts are refused. Leave unset when the
# API is reachable directly.
# TRUST_PROXY=
# Origin of the BetterDB sign-in page for Google and GitHub. Defaults to https://betterdb.com.
# In production this also requires AUTH_PUBLIC_URL to be set before the sign-in buttons turn on.
AUTH_BROKER_URL=
# Turn off Google and GitHub sign-in, e.g. for air-gapped installs. This hides the buttons
# and makes the broker sign-in routes answer 404.
# AUTH_BROKER_DISABLED=false
# PEM public key that verifies Google and GitHub sign-ins. Replaces the embedded key.
# The embedded key ships with the release that turns the feature on. Until then, Google
# and GitHub sign-in stays off unless this is set. Write line breaks as \n to keep the
# key on one line.
# AUTH_BROKER_PUBLIC_KEY=
# Key id for the AUTH_BROKER_PUBLIC_KEY override. Defaults to brk-override.
# AUTH_BROKER_KEY_ID=

# License Configuration
BETTERDB_LICENSE_KEY=
# Air-gapped deployments: paste the offline license token (from
# betterdb.com/account/licenses) directly, or point at a file containing it
# (e.g. a mounted secret). With an offline license and no license key set,
# the monitor never phones home. Default file location: data/license-offline.jwt
BETTERDB_OFFLINE_LICENSE=
BETTERDB_OFFLINE_LICENSE_FILE=
# Paid tiers require a signed entitlement token. Only set this to true when
# talking to a legacy entitlement server that cannot sign (insecure: an
# unsigned grant is indistinguishable from a spoofed ENTITLEMENT_URL).
LICENSE_ALLOW_UNSIGNED=false
# Directory for persisted licensing state (license key, signed-token grace,
# offline license, clock). Mount a volume here in containers so these survive
# restarts/upgrades. Defaults to <workdir>/data (/app/data in the image).
BETTERDB_DATA_DIR=
ENTITLEMENT_URL=https://www.betterdb.com/api/v1/entitlements
RESEND_API_KEY=
RESEND_FROM_EMAIL=Kristiyan <kristiyan@betterdb.com>
CORS_ORIGINS=https://betterdb.com,http://localhost:3001,http://localhost:5173
LICENSE_CACHE_TTL_MS=3600000
LICENSE_MAX_STALE_MS=604800000
LICENSE_TIMEOUT_MS=10000

# Telemetry Configuration
TELEMETRY_PROVIDER=posthog
POSTHOG_API_KEY=
POSTHOG_HOST=https://eu.i.posthog.com
BETTERDB_TELEMETRY=true

# Registration (Vite build-time — baked into the JS bundle by `pnpm --filter web build`)
VITE_REGISTRATION_URL=https://www.betterdb.com/api/register

# Frontend Telemetry (Vite build-time)
VITE_PUBLIC_POSTHOG_PROJECT_TOKEN=
VITE_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com

# Key Analytics Configuration (Pro tier required)
KEY_ANALYTICS_SAMPLE_SIZE=10000
KEY_ANALYTICS_SCAN_BATCH_SIZE=1000
KEY_ANALYTICS_INTERVAL_MS=300000

# MONITOR — server-side value redaction
# When "true", value-position arguments of write commands (SET, HSET, MSET,
# SETEX, LPUSH, SADD, PUBLISH, ...) are replaced with <redacted> before
# captures are persisted to disk and before lines are streamed to the live
# tail. Keys, command verbs, and structural fields stay visible.
# Coverage is the common write surface; complex grammars (XADD, ZADD,
# BITFIELD, BITOP) are not scrubbed — leave the toggle off when those
# payloads are sensitive. Default off.
MONITOR_REDACT_VALUES=

# Test-only override that forces the pre-flight provider detector to a
# specific managed-provider id (e.g. "elasticache", "memorystore",
# "rediscloud", "upstash"). Bypasses host/INFO detection. Leave unset in
# production.
MONITOR_PROVIDER_OVERRIDE=

# Webhook Configuration
# Public base URL of the web UI (e.g. https://monitor.example.com). Used to
# build "View in BetterDB" links in Slack/Discord messages. Leave unset and
# chat messages render without the link.
# FRONTEND_URL=https://monitor.example.com