# Run dashboard

BeamAgent includes an optional browser dashboard for **active runs on one
node** and sanitized completed-run history when a trace store is configured.
It is disabled by default. Enable it in the consuming application's
configuration:

```elixir
config :beam_agent, :dashboard, port: 4080
```

Restart the application, then open [http://127.0.0.1:4080/](http://127.0.0.1:4080/).
The listener binds only to `127.0.0.1`; this version does not provide remote
access or authentication. To turn it off, remove the setting or set
`config :beam_agent, :dashboard, false` and restart.

In a Phoenix host, put the setting in `config/dev.exs` for local development
and start the application with `mix phx.server`. The dashboard is a separate
HTTP listener at port 4080, not a Phoenix route or Phoenix LiveDashboard page.
No router macro or additional dashboard child is required: BeamAgent owns its
supervision. Runs must execute on the same BEAM node to appear as active.
For a remote deployment, the URL refers to that server's loopback interface;
use a secured tunnel to access it. Public mounting and authentication are not
provided by this version.

Installing BeamAgent does not create database tables. Completed history needs
the explicit migrations, Postgrex connection, and retention configuration
described in [persistent run evidence](persistent-traces.md). Active status
works without that setup. A run that finishes before a browser refresh may
only be visible in completed history when persistence is enabled.

The active table refreshes every two seconds; retained history refreshes every
ten seconds. The active table shows the opaque `run_key`, a
`:running` status, local start time, and elapsed time. The active count covers
all current local registrations, while the table shows at most 200 rows.
Registration is owned by the runner process and disappears when it exits.
A run can finish between two refreshes, so each display is a snapshot.

The dashboard serves a read-only JSON snapshot from
`/api/Elixir.BeamAgent.Dashboard.Endpoint:runs`. It does not expose goals,
prompts, messages, tool arguments or results, model responses, raw errors,
Run/State/Trace structs, or stacktraces. Run keys are correlation identifiers,
not access credentials. The browser inserts values as text rather than HTML.

The completed-runs table reads up to 200 recent sanitized summaries from the
[persistent trace store](persistent-traces.md). It shows the key, outcome,
verification status, token totals, USD cost, evidence completeness, and finish time. Missing usage or prices display as “Unknown”. When storage is
disabled or unavailable, it says history is unavailable. The local Registry
still supplies only active status. The dashboard does not display stored trace
steps or full in-memory Run values.

The dashboard uses OTP `:inets` and adds no third-party web dependency. Its
HTTP server starts under the BeamAgent application only when configured. If
the selected port is unavailable, application startup reports the bind failure.

To try both tables locally, start PostgreSQL, create a disposable
`beam_agent_demo` database, then run from the repository root:

```sh
BEAM_AGENT_DEMO_PG_PORT=5432 mix run --no-start examples/dashboard_demo.exs
```

Set `BEAM_AGENT_DEMO_PG_PORT` to your PostgreSQL port and, if needed,
`BEAM_AGENT_DEMO_PG_DATABASE` to the database name. The script uses the
current `$USER` as the PostgreSQL role and applies the two BeamAgent SQL
migrations. It starts the HTTP dashboard on port 4080, creates one successful
and one verification-failed completed run with reported token usage and demo
prices, then starts a run that stays active for one hour. Open the HTTP URL
printed by the script, rather than the `priv/dashboard/index.html` file. The
active table updates within two seconds; completed history updates within ten.
The demo retains its completed records for 24 hours and stops when you press
Ctrl-C. Run it against a disposable database because it applies migrations and
inserts sample records.

## Example screenshot

See the [dashboard screenshot in the README](../README.md).

Captured from `examples/dashboard_demo.exs` against a disposable PostgreSQL
database. It shows a real running process plus persisted success and
verification-failure results. Usage and prices are supplied by the demo.