Hosted Governance Dashboard — Operator Runbook
Read-only remote glance of ROADMAP / HANDOVER / document-derived gates via GitHub
(and optional MuseHub) read APIs. Authoritative workflow remains the local
ok CLI / Track Q. This surface never mutates git, muse, GitHub, or MuseHub.
Frozen contract: docs/archive/phases/PHASE-HOSTED-GOVERNANCE-DASHBOARD.md.
What this is / is not
| Is | Is not |
|---|---|
| Org/repo governance glance for operators without a checkout | Track Q (ok app) port or rewrite |
Preview via ok hosted-dashboard (default 127.0.0.1:8766) |
CD / deploy console / live product health probe |
| Bearer viewer auth + separate upstream read token | Write-capable GitHub/MuseHub automation |
Credentials (required)
| Env | Role |
|---|---|
OVERSEER_HOSTED_DASHBOARD_VIEWER_TOKEN |
Viewer Bearer (≥ 128 bits). If unset in preview, an ephemeral token is printed once to stderr at startup. |
OVERSEER_HOSTED_DASHBOARD_TOKEN |
Upstream read credential for GitHub Contents/meta (and optional checks). Synonym: OVERSEER_HOSTED_DASHBOARD_GITHUB_TOKEN. |
OVERSEER_HOSTED_DASHBOARD_SCOPES |
Optional comma-separated introspected scope list. If any write-class token is present, process start refuses with write_scope_refused (exit 2). |
Never commit tokens into the repo, living docs, or version.lock.
Upstream scope policy
Use a read-only credential (fine-grained: Contents read + Metadata read; or classic with the narrowest read access your org allows).
Refuse credentials that advertise write-class scopes such as contents:write,
administration, workflows / workflow, or full classic repo when introspected.
If the host cannot report scopes, you still must provision read-only credentials —
the code path only issues upstream GET/HEAD.
Config block
Optional (default inert) in .overseer/config.yaml:
hosted_dashboard:
enabled: false
allow_non_loopback: false
cors_origins: []
org_allowlist: [] # "owner/repo" or org-only "owner"
sources:
github_contents: true # required baseline (K7)
github_meta: true # required baseline (K7)
github_checks_advisory: false
musehub_read: false
# Optional Muse deepen (finite hosts only — no wildcards):
# musehub_hosts: [musehub.example.com]
# musehub_base_url: https://musehub.example.com
Empty org_allowlist → org summary returns zero repos (fail closed).
Local preview
export OVERSEER_HOSTED_DASHBOARD_TOKEN=<github-read-token>
# optional: export OVERSEER_HOSTED_DASHBOARD_VIEWER_TOKEN=<long-random>
./cli/ok hosted-dashboard --port 8766 --bind 127.0.0.1 --config .overseer/config.yaml
Paste the viewer token into the UI bootstrap once per browser load (JS memory only —
no localStorage / sessionStorage).
| Flag | Default | Notes |
|---|---|---|
--port |
8766 |
Occupied → exit 2 (no silent hop). Distinct from Track Q 8765. |
--bind |
127.0.0.1 |
Non-loopback requires allow_non_loopback: true plus auth; TLS required for non-loopback hosted deploys. |
--config |
cwd .overseer/config.yaml if present |
Path-confined |
--open |
off | Optional browser open |
Exit codes: 0 clean shutdown · 1 usage · 2 config/bind/scope/listen failure.
Upstream hosts (allowlist)
Default: api.github.com, raw.githubusercontent.com.
Optional Muse deepen may add exactly the hostnames listed in musehub_hosts
(finite; no *). Literal IPs and link-local/metadata addresses are always refused
(upstream_host_refused / HTTP 403).
CORS
cors_origins is an allowlist. Missing Origin (same-origin / non-browser) is allowed.
Any non-allowlisted explicit Origin → HTTP 403.
K7 note
No core hosted-dashboard feature may be MuseHub-only. github_contents + github_meta
remain the baseline for git-only orgs. musehub_read is optional deepen only.
Hard stops
- No Track Q rewrite / no teaching
ok appto bind non-loopback for hosting - No kit-owned durable multi-tenant store of consumer governance docs
- No CD/deploy/production product URL probes
- No Tier-3 merge authorization from this surface