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

# Read the agent dashboard

> How to interpret the panels exposed on the agent's debug HTTP surface.

The agent serves a read-only debug dashboard on port `10101`. By
default it binds to the loopback interface only, so open it from the
agent's own machine at `http://127.0.0.1:10101`. The dashboard polls
the agent's in-process state every five seconds and never mutates
anything.

## Reaching the dashboard

| Where the agent runs | How to open the dashboard |
| - | - |
| Binary, systemd or launchd on a host | `http://127.0.0.1:10101` on that host, or an SSH tunnel: `ssh -L 10101:127.0.0.1:10101 <host>` |
| Kubernetes | `kubectl port-forward deploy/observer-agent 10101:10101`, then `http://localhost:10101` |
| Docker on a bridge network | Publishing the port alone does not work: inside the container the dashboard listens on the container's loopback. Expose it as described below. |

To serve the dashboard on another interface, set
`DEBUG_DASHBOARD_HOST` (for example `0.0.0.0`) **and**
`DEBUG_DASHBOARD_TOKEN` to a long random value. Without a token, a
non-loopback `DEBUG_DASHBOARD_HOST` is ignored and the agent binds
`127.0.0.1` instead, with a warning in its log. With a token, every
request except `/healthz` must send `Authorization: Bearer <token>`;
anything else gets `401`.

## Panels

The page shows six cards under **Agent**, then a **Probes** table
and a **Log** pane. The same state is available as JSON at
`/api/state`; see [Dashboard panels](https://docs.use.observer/agent/reference/dashboard-panels.md)
for its fields.

### Runtime

Identifies the agent: version string, Bun runtime version, process
id, host name, resident-set memory and process uptime. Use this to
confirm the running build matches the version you expected after an
upgrade.

### Cloud link

Reports the host of the configured `CLOUD_SERVER_URL` and the
results and times of the last heartbeat and the last metric push.
Failed recent calls show their error text here.

### Counters

The number of probes loaded, and totals since the agent started:
evaluations, verdicts pushed, errors and dropped readings.

### Queue

Reports the local SQLite queue's current depth against its
capacity, the age of the oldest pending push, and the drain
controller's current backoff in milliseconds. A growing queue
combined with a non-zero backoff is the signature of cloud
unreachability.

### Sources

The source types of the metrics currently assigned to this agent.
Useful when verifying that a configured source type (for example
`database`) has reached the agent.

### Prometheus

Reports the configured `PROMETHEUS_SERVER_URL`, the outcome of the
last Prometheus probe, and when it ran.

### Probes

One row per metric the cloud has assigned to this agent: the metric
id, source type, last status, last value, thresholds, interval and
the time of the last evaluation. Use this to confirm a specific
metric is being collected.

### Log

The 20 most recent log lines, newest first.

### Masked configuration

The `config` field of `/api/state` lists the environment variables
the agent considers relevant to operation, every value masked. A
value shorter than 20 characters shows as `****`; a longer one keeps
its first 4 and last 2 characters (`obs_…9f`), 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. Variables outside the allowlist are not listed
regardless of their name.

## Toggling the dashboard

The dashboard is enabled by default. To disable it set
`ENABLE_DEBUG_DASHBOARD=false` in the agent's environment. To
change the port, set `DEBUG_DASHBOARD_PORT`. To change the bind
address, set `DEBUG_DASHBOARD_HOST`; any address other than
`127.0.0.1`, `::1` or `localhost` also needs `DEBUG_DASHBOARD_TOKEN`.

> [!WARNING]
>
> **Operator-facing only**
>
> The dashboard is intended for the operators who run the agent.
> Do not expose it to the public internet. In Kubernetes, prefer
> `kubectl port-forward`; if you need a Service, use a `ClusterIP`
> Service (with `DEBUG_DASHBOARD_HOST=0.0.0.0` and a
> `DEBUG_DASHBOARD_TOKEN`) rather than a `LoadBalancer` or `Ingress`.


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