Run the governance demo in 15 minutes

An agent proposes a tool call → Vigil returns a verdict → Light Station shows it live. This guide walks through mock mode (no Swift required) and the full live stack.

Light Station repository ↗ Architecture overview →

Prerequisites

Mode	Requires
Mock (UI only)	Node 20+, npm
Live demo	Node 20+, Swift toolchain, Vigil at `~/Developer/Vigil`, Vigil config initialized

Initialize Vigil config once if missing:

cd ~/Developer/Vigil
swift run vigil config init   # creates ~/.vigil/config.yaml

Mock mode (~5 minutes)

No Vigil daemon required. Exercises the UI and Light Station API against the mock client.

1Clone and install: git clone git@github.com:stephen-sweeney/lightstation.git && cd lightstation && npm install
2Copy env: cp .env.example .env — ensure VIGIL_MOCK=true
3Start: npm run dev
4Open http://localhost:5173

Expected: Light Station loads with simulated governance events. Clearance queue shows mock HOLD items. No Swift build required.

Live demo (~15 minutes)

Full governance loop: Vigil daemon + Light Station + deterministic demo agent.

Manual boot (three terminals)

Terminal 1 — Vigil daemon:

cd ~/Developer/Vigil
swift run vigil daemon --port 18820

Terminal 2 — Light Station:

cd ~/Developer/lightstation
export VIGIL_BASE_URL=http://127.0.0.1:18820
export VIGIL_MOCK=false
npm run dev

Terminal 3 — Demo agent:

npm run demo:agent

Expected: Health check passes at curl http://127.0.0.1:18820/health. Demo agent runs five experiments; Lookout streams events via SSE; Clearance shows HOLD after shell experiment.

Five experiments

#	Action	Expected verdict
1	`web_search` (research)	allow
2	`write` to `/workspace/...`	allow
3	`exec` (shell)	escalate → Clearance queue
4	`write` outside sandbox	deny
4b	`write` to `~/.env`	escalate
5	unknown tool	escalate or deny

The agent reasons freely. The state machine governs absolutely.

What to watch

Lookout — live governance events via SSE (GET /events)
Clearance — HOLD items after Experiment 3; approve or reject
Lantern Room — enforcement level and budget posture
Provisions — Normal → Degraded → Gated → Halted ladder under budget stress

Troubleshooting

Symptom	Likely cause	Fix
502 on queue routes	Vigil not running	Start daemon; verify `/health`
Disconnected banner	`VIGIL_BASE_URL` wrong	Set to `http://127.0.0.1:18820`
No events in Lookout	Mock mode or SSE blocked	`VIGIL_MOCK=false`; check browser console
Swift build fails	Missing toolchain	Xcode CLT or Swift 5.9+
deny on workspace write	Sandbox path	Ensure path under `~/workspace` per Vigil config

Verify integration: npm test && npm run typecheck in the Light Station repo.