> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 connection

| Variable | Default | Notes |
| - | - | - |
| `CLOUD_SERVER_URL` | `https://use.observer` | Base URL of Observer Cloud. Agents before 1.6.0 default to `https://localhost:3000` and need it set explicitly. |

## Network

Proxy and trust-store settings. The agent's runtime reads these
directly, so they apply to the connection to Observer Cloud,
Prometheus queries and HTTP-based probes alike. See
[Run behind a proxy or in a restricted network](https://docs.use.observer/agent/guides/restricted-networks.md).

| Variable | Default | Notes |
| - | - | - |
| `HTTPS_PROXY` | unset | Proxy URL for HTTPS requests, for example `http://proxy.corp.example:3128`. Credentials, if any, go in the URL. |
| `HTTP_PROXY` | unset | Proxy URL for plain HTTP requests. |
| `NO_PROXY` | unset | Comma-separated hosts and domain suffixes that bypass the proxy, for example `localhost,127.0.0.1,.corp.example`. No CIDR support. List internal probe targets and Prometheus here. |
| `NODE_EXTRA_CA_CERTS` | unset | Path to a PEM file with extra CA certificates to trust, in addition to the built-in store. Use it for a TLS-intercepting proxy or a private CA. Read at startup. |
| `NODE_TLS_REJECT_UNAUTHORIZED` | `1` | Setting `0` disables certificate verification for every HTTPS request the agent makes, including the cloud and all probes. Do not use in production; use `NODE_EXTRA_CA_CERTS` instead. |

## Required for Prometheus probes

| Variable | Notes |
| - | - |
| `PROMETHEUS_SERVER_URL` | Base URL of the Prometheus (or Prometheus-compatible API) the agent should query. Used as the default for every Prometheus metric, overridable per-metric via `prometheus_url` in the metric's source config. Keep any path prefix, for example `https://mimir.example.com/prometheus`; the agent appends `/api/v1/query` to it. Optional: when unset, the agent logs a warning at startup and Prometheus metrics without their own `prometheus_url` report `no_data`. Other probe types are unaffected. |

## Optional Prometheus auth

| Variable | Default | Notes |
| - | - | - |
| `PROMETHEUS_BASIC_AUTH_ENABLED` | `true` | Set to any value other than `true` to disable. When enabled and both `PROMETHEUS_USERNAME` and `PROMETHEUS_PASSWORD` are set, the agent sends `Authorization: Basic <encoded>`. |
| `PROMETHEUS_USERNAME` | `admin` | Basic auth username. |
| `PROMETHEUS_PASSWORD` | empty | Basic auth password. Treat as a secret. |
| `PROMETHEUS_BEARER_TOKEN` | empty | Agent 1.6.2+. Sends `Authorization: Bearer <token>`. Cannot be combined with basic auth: if basic auth is also in effect, the agent logs an error at startup and Prometheus metrics report `no_data` with reason `prometheus_auth_conflict`. Treat as a secret. |
| `PROMETHEUS_TENANT_ID` | empty | Agent 1.6.2+. Sent as the `X-Scope-OrgID` header, the tenant header of Grafana Mimir and Cortex. |
| `PROMETHEUS_HEADERS` | empty | Agent 1.6.2+. Extra request headers for any other need, as a JSON object (`{"X-Api-Key": "..."}`) or a list (`X-Api-Key: ...; X-Other: ...`). It cannot repeat `Authorization` when basic auth or a bearer token is set, nor `X-Scope-OrgID` when `PROMETHEUS_TENANT_ID` is set. An invalid value makes Prometheus metrics report `no_data` with reason `prometheus_headers_invalid`. Header values are never logged. Treat as a secret. |

These apply to every Prometheus metric the agent runs. See
[Grafana Mimir and other Prometheus-compatible backends](https://docs.use.observer/agent/guides/prometheus-source.md#grafana-mimir-and-other-prometheus-compatible-backends)
for examples.

## 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. Without it, a non-loopback `DEBUG_DASHBOARD_HOST` falls back to `127.0.0.1`. The token is enforced only on a non-loopback bind: with the default loopback bind, the dashboard does not ask for it. |
| `DEBUG_DASHBOARD_PORT` | `10101` | Port for the dashboard HTTP listener. |

## Logging

| Variable | Default | Notes |
| - | - | - |
| `BROADCAST_LOGS` | `false` | When `true`, the agent forwards its log lines at or above `LOG_BROADCAST_LEVEL` to the console's live log viewer. 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. |

### Live logs in the console

With `BROADCAST_LOGS=true`, open the agent in the console and select the
**Logs** tab, or use **Logs** on the agent's row in the agents table. Both
show the same live viewer.

* **Live only.** Lines stream while the viewer is open. Nothing is
  stored: lines the agent sends while no viewer is open, or while the
  viewer is disconnected, are not kept. The viewer holds the newest 500
  lines until you leave it.
* **Filters.** Pick a minimum level (all levels, info and above, warn and
  above, error only) and search the lines. **Copy** copies the lines
  shown, or all lines when no filter is set.
* **Controls.** The viewer follows the newest line; scroll up to stop
  following. **Pause** holds new lines until you select **Resume**.
  **Clear** empties the viewer.
* **States.** The viewer shows **Connecting**, **Connected**, **Live**
  while lines arrive, **Reconnecting** with a retry countdown and a
  **Retry now** button when the stream drops, and **Agent offline** with
  the time of the last heartbeat when the agent is not reporting.

An empty viewer on a healthy agent is normal: by default only `WARN` and
`ERROR` lines are forwarded. To see routine activity, set the level to
`INFO` and restart the agent:

```bash theme={null}
BROADCAST_LOGS=true
LOG_BROADCAST_LEVEL=INFO
```

From agent 1.7.2, every check result that resolves to no data is logged at
`WARN` with its [reason code](https://docs.use.observer/agent/reference/reason-codes.md) and how long
the check took, so it reaches the viewer at the default level:

```text theme={null}
no_data: http metric=<metric id> reason=connect_failed elapsed_ms=10003
```

The console stores only the latest reason for each check. These lines
are the history, which helps diagnose a check that fails now and then.

## Local queue

| Variable | Default | Notes |
| - | - | - |
| `BUFFER_PATH` | `./observer-agent-buffer.db` | Path to the agent's local SQLite write-ahead queue file. The heartbeat relay queue sits next to it (`-relay` suffix). In containers use `/data/observer-agent-buffer.db` with a volume on `/data` (the default in agent images 1.6.0 and later). |
| `BUFFER_MAX_ROWS` | `200000` | Hard cap on queued readings (`10000` before agent 1.7.3). When the queue reaches the cap, oldest entries are evicted to admit new ones. One reading is about 300 bytes, so the default uses up to about 60 MB and holds about 33 hours for 50 metrics every 30 seconds. See [Local queue](https://docs.use.observer/agent/concepts/local-queue.md). |

## 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)](https://docs.use.observer/agent/guides/otlp-source.md).

| 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`. Without it the receiver does not start and OTLP metrics report `push_source_init_failed`. |
| `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. |

## Heartbeat relay

Requires agent 1.6.0 or later. The relay is off by default. See
[Heartbeat relay](https://docs.use.observer/agent/guides/heartbeat-relay.md).

| Variable | Default | Notes |
| - | - | - |
| `HEARTBEAT_RELAY_ENABLED` | `false` | Set `true` to start the heartbeat relay for jobs without internet access. |
| `HEARTBEAT_RELAY_HOST` | `127.0.0.1` | Relay bind address. Loopback only by default; set `0.0.0.0` to accept pings from other hosts or pods. |
| `HEARTBEAT_RELAY_PORT` | `10102` | Port the relay listens on. |

## Other

| Variable | Default | Notes |
| - | - | - |
| `SKIP_SSL_VERIFICATION` | `false` | Disables TLS verification on cloud-bound requests. Development only. For a TLS-intercepting proxy, trust its CA with `NODE_EXTRA_CA_CERTS` instead. |
| `NODE_ENV` | unset | Set to `production` in the published image. The agent does not change behavior based on it. |

> [!NOTE]
>
> **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 listed with its value replaced by
> `•hidden•`, never even partially shown: 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.