Dashboard

Every decision visible. Every optimization measured. Accessible from anywhere in the world.

Overview

Gold Lapel ships with a built-in web dashboard that starts automatically alongside the proxy. No separate installation, no external dependencies, no configuration required. The dashboard is a single HTML page embedded in the binary — it loads instantly and works offline.

By default, the dashboard listens on http://127.0.0.1:7933. When Gold Lapel starts, the address appears in the startup output:

goldlapel v0.14.0
  :7932 -> localhost:5432 (butler, pool = 20)
  dashboard: http://127.0.0.1:7933
  invalidation: :7934

Open that URL in a browser and you will see everything Gold Lapel is doing: queries observed, matviews created, indexes built, cache hit rates, connection pool status, and the headline metric that ties it all together — time saved.

The dashboard is not a monitoring add-on. It is Gold Lapel's accountability layer. An autonomous proxy that modifies your database should be transparent about every decision it makes, and this is where that transparency lives.

Time saved

The first thing you will notice on the dashboard is a single number: how much time Gold Lapel has saved your application.

This is not an estimate. Gold Lapel measures the original query execution time for every pattern it optimizes — the actual cost before intervention — and compares it against the optimized path. The difference accumulates. When the dashboard reports "GL saved you 4 days this quarter," that is 4 days of wall-clock time your application did not spend waiting for database responses.

The metric is tracked per query pattern, so you can drill down to see exactly which optimizations contributed. A single matview covering your most expensive JOIN might account for the majority of the savings. A cache layer on a hot read pattern might add another significant chunk. The numbers are specific and attributable.

Time saved is exposed everywhere: the dashboard's headline card, the /metrics endpoint as goldlapel_time_saved_seconds_total, the /api/stats JSON response as time_saved_ms, and the CLI's goldlapel status output. It is the single metric that answers the question your team will inevitably ask: "Is this thing actually helping?"

The answer is a number, not an argument.

Show Your Work

The dashboard's second tab is an audit timeline — a chronological record of every autonomous decision Gold Lapel has made. Each entry follows the same three-part structure:

• OBSERVED — what Gold Lapel saw. "Pattern 00b59a81 hit 842 times, avg 187ms."
• ACTION — what Gold Lapel did about it. "Created materialized view on orders JOIN customers."
• IMPACT — the measured result. "71.5% of queries now served from matview (avg 2.1ms)."

This is the full decision chain, in plain language. No black boxes, no "trust us." Every matview creation, every index, every verification pass, every cleanup — logged with context and measured outcomes.

Events are categorized with color-coded badges: observation, matview, index, verification, and cleanup. Impact numbers are enriched at display time with current statistics, so the audit timeline always shows the latest measured effect of past decisions.

The audit log exists because an autonomous system that asks for your trust should earn it by showing its reasoning. If Gold Lapel creates a matview you do not want, the audit timeline tells you exactly why it was created, when, and what it affected — so you can make an informed decision about whether to keep it, exclude the table, or adjust the threshold.

Configuration management

The dashboard provides a dedicated configuration panel where you can view and modify Gold Lapel's settings without restarting the proxy. Every setting shows its current value, where it came from (TOML file, environment variable, flag, or default), and whether it supports live reload.

Changes made through the dashboard take effect immediately for live-reloadable settings — threshold, pool size, refresh interval, and others. Settings that require a restart are clearly marked, and the dashboard will note when a pending restart is needed.

# View current configuration
goldlapel config

# Modify a setting via the dashboard API
curl -X POST http://127.0.0.1:7933/api/config \
  -H "Content-Type: application/json" \
  -d '{"threshold": 5}'

# Or edit goldlapel.toml and reload
goldlapel reload

The same configuration is available through the /api/config endpoint for programmatic access. POST a JSON object with the settings you want to change, and Gold Lapel applies them live. The goldlapel config CLI command displays the running configuration with provenance — so you can see at a glance which settings came from your TOML file, which from environment variables, and which are still at their defaults.

For a complete list of configuration options, see the Configuration reference.

JSON API: /api/stats

The /api/stats endpoint returns the full proxy state as a single JSON document — the same data that powers the dashboard UI, available for programmatic access. Use it for custom dashboards, health checks, deployment validation, or integration with your existing monitoring infrastructure.

GET http://127.0.0.1:7933/api/stats

{
  "version": "0.14.0",
  "uptime_secs": 86412,
  "mode": "butler",
  "queries_observed": 2847193,
  "queries_rewritten": 1923847,
  "active_connections": 42,
  "matviews": [
    {
      "name": "mv_00b59a8157e6f5ae",
      "tables": ["orders", "customers"],
      "hits": 284719,
      "last_refresh": "2026-03-29T14:23:07Z",
      "immv": true,
      "verified": true
    }
  ],
  "indexes": [
    {
      "name": "idx_a3f1c2d4e5b6a7c8_status",
      "table": "orders",
      "columns": ["status"],
      "type": "btree"
    }
  ],
  "strategy": {
    "matviews_created": 12,
    "matviews_routed": 1923847,
    "cache_hits": 4129381,
    "cache_misses": 892147,
    "rewrites": 1923847,
    "shadow_passes": 12,
    "shadow_failures": 0
  },
  "pool": {
    "active": 8,
    "idle": 12,
    "hits": 3847291,
    "misses": 4281,
    "timeouts": 0
  },
  "time_saved_ms": 345892471,
  "config": {
    "threshold": 3,
    "pool_size": 20,
    "pool_mode": "session",
    "refresh_interval_secs": 60
  }
}

The response includes everything: version, uptime, mode, query counts, the full list of active matviews and indexes with their hit counts and refresh timestamps, strategy counters, pool statistics, time saved, and the current configuration. It is a complete snapshot of the proxy's state at the moment of the request.

The endpoint is lightweight and safe to poll frequently. A common pattern is a health check that verifies mode is "butler" and active_connections is greater than zero after deployment.

JSON API: /api/audit

The /api/audit endpoint returns the audit event log — the same data shown in the dashboard's Show Your Work tab, as structured JSON. Pass a since parameter (epoch milliseconds) for incremental polling.

GET http://127.0.0.1:7933/api/audit?since=1711700000000

{
  "events": [
    {
      "timestamp": 1711700587000,
      "category": "matview",
      "badge": "MATVIEW ROUTED",
      "pattern_hash": "00b59a8157e6f5ae",
      "sections": {
        "observed": "Pattern 00b59a81 hit 842 times, avg 187ms",
        "action": "Routing queries to materialized view mv_00b59a8157e6f5ae",
        "impact": "71.5% of queries now served from matview (avg 2.1ms)"
      }
    },
    {
      "timestamp": 1711699800000,
      "category": "verification",
      "badge": "SHADOW PASS",
      "pattern_hash": "00b59a8157e6f5ae",
      "sections": {
        "observed": "Matview mv_00b59a8157e6f5ae pending verification",
        "action": "Shadow query results matched original query results",
        "impact": "View promoted to active — rewriting enabled"
      }
    },
    {
      "timestamp": 1711699200000,
      "category": "matview",
      "badge": "MATVIEW CREATED",
      "pattern_hash": "00b59a8157e6f5ae",
      "sections": {
        "observed": "Pattern 00b59a81 hit 3 times (threshold reached)",
        "action": "Created materialized view on orders JOIN customers",
        "impact": "Pending — shadow verification in progress"
      }
    }
  ],
  "total": 3,
  "since": 1711700000000
}

Each event includes a timestamp, category, badge text, the pattern hash it relates to, and the three-section structure: observed, action, impact. The since parameter returns only events newer than the given timestamp, which makes it straightforward to poll for new decisions without re-fetching the entire history.

The audit API is useful for feeding Gold Lapel's decisions into your team's Slack channel, incident response tooling, or change management system. An autonomous system that modifies your database schema should notify the humans responsible for that database.

CLI access

Everything available through the dashboard and APIs is also accessible from the command line. The CLI queries the running instance's dashboard API, so the data is always live.

goldlapel audit

Audit timeline (5 events)

  [2m ago]  MATVIEW ROUTED  mv_00b59a8157e6f5ae
    OBSERVED  Pattern 00b59a81 hit 842 times, avg 187ms
    ACTION    Routing queries to materialized view
    IMPACT    71.5% of queries now served from matview

  [15m ago]  MATVIEW CREATED  mv_00b59a8157e6f5ae
    OBSERVED  Pattern 00b59a81 hit 3 times (threshold reached)
    ACTION    Created materialized view on orders JOIN customers
    IMPACT    Pending — shadow verification in progress

  [22m ago]  INDEX CREATED  idx_a3f1c2d4e5b6a7c8_status
    OBSERVED  Column orders.status appears in 94% of WHERE clauses
    ACTION    Created btree index on orders(status)
    IMPACT    Sequential scan eliminated for 312 queries/min

The relevant commands:

• goldlapel status — summary stats: queries observed, queries rewritten, active matviews, active indexes, time saved. With a connection string, queries the database for authoritative counts.
• goldlapel matviews — list all active materialized views with tables, hit counts, refresh times, IMMV status, and verification state.
• goldlapel indexes — list all indexes Gold Lapel has created, with table and column information.
• goldlapel audit — the full audit timeline, formatted for terminal output.
• goldlapel config — display the running configuration, including which settings came from the TOML file, environment variables, or flags.
• goldlapel export — export the full optimization state as a versioned JSON bundle.
• goldlapel dashboard — open the dashboard in your default browser, or connect to a remote instance with --connect.

All of these commands query http://127.0.0.1:7933 by default. If your dashboard runs on a different port, pass --dashboard-port to override.

Remote access

The goldlapel dashboard command opens the dashboard in your browser. When run without arguments, it opens the local instance. With --connect, it opens a remote instance — and this is where things get interesting.

# Open dashboard in your default browser
goldlapel dashboard

# Connect to a remote instance via encrypted P2P tunnel
goldlapel dashboard --connect <instance-id> --token <secret>

Remote dashboard access uses iroh — the same P2P infrastructure that powers GL Mesh. An encrypted QUIC tunnel is established directly between your local machine and the remote Gold Lapel instance. No port forwarding. No VPN. No SSH session. No exposed HTTP endpoints on your production servers.

The connection is authenticated with a token that the remote instance generates on startup. You need both the instance ID and the token to connect — without them, there is no way to reach the dashboard. The tunnel is end-to-end encrypted, so even if traffic passes through relay nodes, the data remains private.

This means you can check on your production Gold Lapel dashboard from a coffee shop, from your home office, from a different continent — anywhere you have an internet connection. The dashboard renders locally in your browser, and the data streams over the encrypted tunnel. It feels like opening a local page because, from your browser's perspective, it is one.

I should note that the dashboard binds to 127.0.0.1 by default, not 0.0.0.0. It is not accessible from the network unless you explicitly configure it to be. For remote access, the --connect approach is the recommended path — it avoids exposing an HTTP endpoint on your production servers while giving you full dashboard access from anywhere.

Settings

The dashboard requires no configuration to use. It starts automatically and listens on port 7933. If you need to change the port or disable the dashboard entirely, a single setting handles it:

# goldlapel.toml
dashboard_port = 7933   # default — change or set to 0 to disable

The same setting is available as a flag (--dashboard-port 8080), an environment variable (GOLDLAPEL_DASHBOARD_PORT=8080), or a wrapper key in your language SDK. Set the port to 0 to disable the dashboard and /metrics endpoint entirely — though I would gently discourage this. The dashboard is the simplest way to verify that Gold Lapel is working correctly, and the /metrics endpoint costs nothing to leave available.

The dashboard port is live-reloadable. Change it in goldlapel.toml and the dashboard rebinds to the new port without restarting the proxy or interrupting any active connections.