Environment variables
Every environment variable the agent reads, with defaults and meaning.
The agent is configured through environment variables. There is no configuration file; this keeps the runtime container immutable and the deployment surface small.
Required
| Variable | Notes |
|---|---|
AGENT_KEY | Authentication key issued by the cloud. Format obs_live_<43 base64url chars>. The cloud stores its hash, never the plaintext. |
CLOUD_SERVER_URL | Base URL of Observer Cloud. Defaults to https://localhost:3000 (development only). Override in every real deployment. |
Required for Prometheus probes
| Variable | Notes |
|---|---|
PROMETHEUS_SERVER_URL | Base URL of the Prometheus the agent should query. Used as the default for every Prometheus metric, overridable per-metric via prometheus_url in the metric's source config. |
Optional Prometheus auth
| Variable | Default | Notes |
|---|---|---|
PROMETHEUS_BASIC_AUTH_ENABLED | true | Set to any value other than true to disable. When enabled, the agent sends Authorization: Basic <encoded> on every Prometheus request. |
PROMETHEUS_USERNAME | admin | Basic auth username. |
PROMETHEUS_PASSWORD | empty | Basic auth password. Treat as a secret. |
Dashboard
| Variable | Default | Notes |
|---|---|---|
ENABLE_DEBUG_DASHBOARD | true | Set to false to disable the local debug dashboard. |
DEBUG_DASHBOARD_HOST | 127.0.0.1 | Bind address for the dashboard HTTP listener. A non-loopback value (for example 0.0.0.0) is downgraded back to 127.0.0.1 unless DEBUG_DASHBOARD_TOKEN is set. |
DEBUG_DASHBOARD_TOKEN | empty | Required to bind the dashboard to a non-loopback address. When set, the dashboard requires this token and the agent honors a non-loopback DEBUG_DASHBOARD_HOST. |
DEBUG_DASHBOARD_PORT | 10101 | Port for the dashboard HTTP listener. |
Logging
| Variable | Default | Notes |
|---|---|---|
BROADCAST_LOGS | false | When true, the agent forwards a subset of its log lines to the cloud for surfacing in the agent detail page. PromQL query strings are always redacted to a SHA-256 prefix and length, regardless of this flag. |
LOG_BROADCAST_LEVEL | WARN | Minimum level forwarded when BROADCAST_LOGS=true. One of DEBUG, INFO, WARN, ERROR. |
VERBOSE | false | Local stdout verbosity. |
Local queue
| Variable | Default | Notes |
|---|---|---|
BUFFER_PATH | ./observer-agent-buffer.db | Path to the agent's local SQLite write-ahead queue file. |
BUFFER_MAX_ROWS | 10000 | Hard cap on queued pushes. When the queue reaches the cap, oldest entries are evicted to admit new ones. |
OpenTelemetry receiver
Read only when at least one metric with source type otlp is
configured. Until then the receiver never starts and no port is
opened. See Receive metrics over OpenTelemetry (OTLP).
| Variable | Default | Notes |
|---|---|---|
OBSERVER_OTLP_LISTEN_ADDR | 127.0.0.1:4318 | Bind address for the OTLP/HTTP receiver. Binding a non-loopback address requires OBSERVER_OTLP_BEARER_TOKEN; the agent refuses to start otherwise. |
OBSERVER_OTLP_BEARER_TOKEN | empty | Bearer token senders must present in the Authorization header. Compared in constant time. |
OBSERVER_OTLP_MAX_BUFFER_POINTS | 1000 | Maximum distinct streams (metric name x attribute fingerprint) held in memory. Past the cap the oldest stream is evicted. |
OBSERVER_OTLP_DISABLE | unset | Set to true to skip the receiver entirely, even when OTLP metrics are configured. |
OBSERVER_OTLP_MAX_BODY_BYTES | 16777216 (16 MB) | Hard cap on a single OTLP request body, so an oversized payload cannot exhaust agent memory. Values below the 1 MB floor are ignored and the default applies. |
Other
| Variable | Default | Notes |
|---|---|---|
SKIP_SSL_VERIFICATION | false | Disables TLS verification on cloud-bound requests. Development only. |
NODE_ENV | unset | Affects log formatting. Set to production in production deployments. |
Sensitive values in the dashboard
Every value the debug dashboard shows is masked, including the
ones that are not secrets. A value shorter than 20 characters is
replaced with **** outright; a longer one keeps a
first-4 … last-2 hint, enough to tell two keys apart and never
enough to recover one.
DEBUG_DASHBOARD_TOKEN is never rendered at all, not even masked:
it is the credential that protects the page.
Variables outside the dashboard's allowlist are omitted entirely. The allowlist is intentionally narrow; everything outside it does not appear regardless of name or value.