Architecture Overview
Vigils is a 5-layer control plane (T0 → T4):
T4 — Desktop UI / Browser Extension / CLI
T3 — MCP Hub (server registry, descriptor pinning)
T2 — Action Firewall + Approval Queue + Policy + Audit Ledger
T1 — Privacy Filter + Sandbox Runner (Wasm + native)
T0 — Types + Schemas (vigil-types)
Crate layout
SDK boundary (publishable, 10 crates)
| Layer | Crate |
|---|---|
| T0 | vigil-types |
| T0 | vigil-redaction (hard rules + optional ORT) |
| T0 | vigil-runner-types |
| T2 | vigil-policy / vigil-audit / vigil-lease / vigil-firewall |
| T3 | vigil-ui-protocol / vigil-mcp |
| — | vigil-sdk (facade) |
Internal (not published)
vigil-runnerconcrete (wasmtime + sandbox-linux + vigil-redaction deps)vigil-sandbox-linux(Linux-only, target-gated)vigil-http-auth/vigil-http-transport/vigil-browserapps/desktop/apps/native-host/apps/vigil-hub-cli
Key invariants
- Fail-closed errors → DENY
- No-plaintext audit
DecisionRecordmandatoryinherit_env=false(native) + fuel/epoch dual limit (Wasm) + Landlock (Linux)- preopen allowlist only / per-run independent engine
See the ADR Index for the design rationale behind each layer.
Data flow (typical action)
1. AI agent → MCP request → vigil-hub stdio
2. vigil-hub::descriptor_lookup → drift check
3. vigil-firewall::evaluate → policy + scope + PII
4. (if approval needed) → ApprovalBroker → Desktop UI
5. (on approve) vigil-runner::spawn_native/wasm → sandbox
6. vigil-audit::append → SQLite ledger
7. result → AI agent
Every step is fail-closed: any error → DENY plus a ledger event.