Web Dashboard & Observability

Cade has a built-in web server for watching a table while it runs. Where the console is the hands-on TUI you drive at the machine, the web server is for headless and remote monitoring — a cabinet running unattended, a CI run, or a second screen on your bench. It serves a live health dashboard, plain health endpoints you can point an uptime monitor at, and an optional event-flow debugger.

Early stage — expect change. The web server works today, but it is one of Cade’s least-settled surfaces and not yet in its intended final state. Endpoint paths, the dashboard layout, the metrics format, and the (currently absent) authentication model are all expected to change. Treat this page as a guide to what’s available now, not a stable contract — and don’t build long-lived automation against the exact paths without expecting to revisit it.

It is off by default. Nothing is served until you turn it on.

Turning it on

The fastest way is the -w flag when you start a table:

cade -d ./my-table -w

Then open http://localhost:8080/ — the root page lists the endpoints that are currently live.

Host, port, and which endpoint groups are enabled are all configurable. Set them with flags, environment variables, or the web block in your runtime config — whichever fits your workflow:

cade -w --web-port 9090 --debug-enabled        # custom port, turn on the debugger
CADE_WEB_ENABLED=true CADE_WEB_PORT=9090 cade   # via environment

web {
  enabled = true
  host    = "127.0.0.1"
  port    = 8080
  health { enabled = true }
  debug  { enabled = false }
}

For the full flag list see the CLI Reference; for the web block, its defaults, and config precedence see Runtime Configuration.

What’s served

The endpoints fall into three groups. The root discovery page (GET /) always reflects what’s actually enabled.

The health dashboard

Open http://localhost:8080/dashboard for an at-a-glance view of a running table. It shows:

• Overall status — a color-coded indicator (healthy / degraded / unhealthy / critical).
• Components — how many subsystems are reporting, broken down by status.
• System metrics — uptime, availability, and response time.
• Active alerts — anything currently raised, with a refresh control.

The page refreshes itself periodically, so you can leave it open on a second monitor while you play.

Health endpoints for monitoring

For an uptime monitor, load balancer, or a systemd health check, hit the JSON endpoints directly. The key one is /health/status — its HTTP status code reflects the table’s state, so most monitoring tools can consume it with no parsing:

# Poll from a monitor or a cron job
curl -fsS http://localhost:8080/health/status | jq .status

The full set:

All return JSON. (There is no Prometheus scrape endpoint — metrics are served as JSON on /health/metrics.)

Alerts

When a check trips, it raises an alert. These are surfaced both on the dashboard and as JSON:

The event-flow debugger

Start Cade with --debug-enabled and open http://localhost:8080/debug/visualization for a deeper view aimed at working out why a table did something. It charts event traces as they flow through the runtime: a statistics panel (total traces, successes, failures, average duration, throughput, error rate), a list of recent traces color-coded by outcome, a flow diagram, a timeline, and an error-analysis panel.

Filter the trace queries by event type, status, or time range:

curl "http://localhost:8080/debug/visualization/traces?status=FAILED&time_range=1h"

This group is heavier than the health endpoints and is meant for development and troubleshooting rather than always-on production monitoring — leave it off (the default) on a machine that’s just playing.

Security

The web server has no authentication — anything that can reach the host and port can read every endpoint. Two consequences for how you run it:

• Keep it bound to localhost unless you have a reason not to. The default host is localhost; setting host = "0.0.0.0" exposes it on every interface.
• Don’t put it on an untrusted network in the open. If you need to reach a cabinet’s dashboard remotely, front it with a reverse proxy that adds authentication, or reach it over a VPN — don’t bind 0.0.0.0 on a public network.

A good production default is health endpoints on, debug off, bound to localhost, and reached through whatever secure channel you already use to manage the machine.