Skip to content

console.md

Latest commit

 

History

History
139 lines (104 loc) · 5.64 KB

console.md

File metadata and controls

139 lines (104 loc) · 5.64 KB

Bridle operator console — quick start

The console is a local Web UI for the operator. It does what the CLI does, plus shows you the evidence trail (audit rows, would-have counts, canary signals) without forcing you to memorize trace_ids.

Starting it

The console is mounted on the same FastAPI process as the control plane. There is no second service to deploy.

# From the repo root, in your venv:
uvicorn bridle.cp_server.app:app --host 127.0.0.1 --port 8200

# In a browser:
open http://127.0.0.1:8200/console/fleet

If your CP is already running, just visit /console/ and it redirects to the fleet page.

Five-minute walkthrough

The whole console is six pages. Here's the order an operator uses during a real pilot review.

1. Fleet (/console/fleet?tenant_id=t1)

Top of the page: three big numbers — fleet size, audit row count, active bundle version. Below: every agent with mode and shadow signal counts. Click an agent name to drill in. The "auto" badge marks agents that produced audit rows but were never registered — follow up with their owners.

2. Agent detail (/console/agents/{id})

Per-agent metrics + the last 50 audit rows. Each row links to the trace viewer pre-filtered to that trace. Use this when you want to answer "is this agent's traffic representative or weird?" before making a canary call.

3. Pilot decision (/console/reports/pilot-decision?tenant_id=t1)

The page leads with one of four recommendations:

  • expand-shadow — broaden the shadow rollout.
  • enforce-canary — the report names the policy + preferred agent. Copy the suggested CLI line, or click through to the Canaries page.
  • keep-observing — not enough signal yet.
  • stop — something's wrong; fix the underlying issue first.

The Signals card under the recommendation explains why it landed where it did.

4. Canaries (/console/canaries?tenant_id=t1)

Two sections.

The top table lists every active canary override with a side-by-side: the canary agent's enforced + would-have counts vs the average across its siblings. If your canary's would-have count is wildly higher than its siblings', the canary agent is the wrong one and you should rollback.

The bottom form is "Promote a new canary." Type a policy_id and agent_id, pick enforce (or shadow), submit. Enforce requires a browser confirmation. A success banner replaces the form on the server-rendered response.

5. Policies (/console/policies?tenant_id=t1)

The active bundle's metadata, plus every policy with its mode, target spec, and canaries. The dangerous button on this page — "⚠ Promote to enforce (fleet-wide)" — is intentionally labeled and intentionally triggers a confirm() dialog. The canary page is the recommended path for "first enforce." Use this page when you've already validated a canary and want to widen.

6. Trace viewer (/console/trace?tenant_id=t1)

Search by trace_id, session_id, or agent_id. The table is ordered by event time. Every row shows:

  • the observation type (llm_request_intended / tool_call_intended),
  • the matched policies,
  • final_action vs would_have_action,
  • mode_at_evaluation vs mode_configured (so you can spot a FORCE_SHADOW demotion at a glance),
  • the canonical hash of the payload (12-char prefix).

No raw payloads are rendered, ever. Even when the audit row carries a redacted_payload_ref URL, the URL is not inlined into the HTML.

Safety bands

Two amber/red banners can appear at the top of any page:

  • BRIDLE_FORCE_SHADOW is active (amber) — every enforce decision is being demoted at the gateway. Audit rows still record mode_configured, so you can see what would have run — but nothing is actually enforced right now.
  • BRIDLE_BYPASS is active (red) — the plugin is short-circuited. No observation, no decision, no audit. The console may show stale data.

Both banners tell you exactly what to do (turn off the env var on the gateway) to resume normal operation.

What the console deliberately does NOT do

  • No login / accounts / RBAC. This is meant to run on 127.0.0.1 or behind your team's existing VPN, not on the public internet. Treat it as you'd treat kubectl or a Postgres console.
  • No policy editor. Author policies as YAML and run bridle policy compile/publish. The console flips modes and toggles canaries, nothing more.
  • No charts. You get tables and counts. If you need plots, pipe the JSON endpoints into your tool of choice.

Mapping to CLI

Every action has a CLI equivalent. Whichever you use, the same audit trail is produced.

Console page CLI equivalent
Fleet bridle agents list + bridle report fleet
Agent detail bridle agents show + bridle report trace
Policies bridle gateway status + bridle policy compile
Canaries (promote/rollback) bridle policy canary --policy P --agent A --mode M --tenant T
Trace viewer bridle report trace --tenant T --trace-id X
Pilot decision bridle report pilot-decision --tenant T
Fleet report bridle report fleet --tenant T
Pilot report bridle report pilot --tenant T
Shadow report bridle report shadow --tenant T
"Promote to enforce (fleet-wide)" bridle policy mode --policy P --to enforce --tenant T