How It Works
Status: Available.
Every request that flows through msh local passes through a pipeline in the daemon's proxy handler. The proxy operates as a transparent HTTPS MITM — AI agents point their CLIs at HTTPS_PROXY=http://127.0.0.1:9443 and the daemon intercepts, classifies, and enforces policy before forwarding traffic to the real upstream.
01. INTERCEPT
The daemon generates its own ECDSA CA and per-host leaf certificates at install time. When a CLI connects, the proxy terminates TLS, presents a leaf cert signed by its CA, then opens a fresh TLS connection to the real upstream host. AI agents see a valid certificate chain because the daemon's CA is trusted in the system keychain. Hosts on the user pinned list (via msh local pin) are spliced through without MITM. Hosts that match no policy inspect route are a transparent tunnel: spliced through untouched, with no audit row or record of any kind.
02. CLASSIFY
The HTTP method, host, and path are dispatched to a protocol-specific classifier. HTTP classifiers cover kubectl, gcloud, aws, github, cloudflare, fly, and generic hosts. Terraform/tofu and helm have CLI classifiers, but no HTTP classifier. Unrecognised hosts that match the generic: inspect list are tiered from the HTTP method, with destructive path segments raised to at least sensitive. The result is one of four risk tiers: observe,modify, sensitive, or break-glass. Unknown or unclassifiable requests fail closed (escalate or deny).
03. POLICY
The classification and request context are evaluated against~/.mezite/local/policy.yaml. Policy is protocol-keyed (kubectl:, gcloud:,fly:, generic:), with scope-sugar blocks (namespaces:, projects:,apps:) that are first-match-wins. Each block resolves to an action:allow, escalate, or deny. If no rule matches, the protocol'sdefault: applies (typically escalate). Policy is hot-reloaded via fsnotify — edits take effect within a second without dropping in-flight requests.
04. APPROVE OR BLOCK
An allow decision forwards the request immediately. A deny returns an error to the AI agent. An escalate decision blocks the AI agent's connection and queues an approval request in the daemon's in-process broker. The desktop app and CLI both surface pending approvals (msh local approval list). A human approves (msh local approval allow <id>) or denies (msh local approval deny <id>) within the configured timeout (default ~30 s). The AI agent's HTTP connection is held open throughout — from the AI agent's perspective, the upstream is simply slow to respond.
05. AUDIT
Inspected requests in enforce mode are appended to ~/.mezite/local/audit.jsonl as best-effort JSONL records, append-only by convention. The local log is not hash-chained or tamper-evident. Request records carry a timestamp_ms, an op, a hash field containing a random 128-bit identifier used only for pagination and deduplication, and a fields map with request context. View them with msh local audit show or msh local audit tail. Enrolled workstations also upload audit events to MezHub; rely on that central record.
Approval flow
When a request is escalated, the daemon's in-process broker holds the AI agent's connection open until a human responds. There is no y/N terminal prompt, no webhook, and no Slack integration — approvals are handled through the desktop app or the msh local approval CLI commands.
AI agent CLI msh local daemon Operator (desktop / CLI)
│ │ │
├── HTTPS request ─────►│ │
│ ├── classify → modify │
│ ├── policy → escalate │
│ (connection held) ├── approval queued ───────►│
│ │ msh local approval list
│ │ msh local approval allow <id>
│ │◄── approved ─────────────┤
│ ├── forward to upstream │
│◄── response ─────────┤ │
│ ├── audit row written │Proxy modes
The daemon operates in one of three modes, switchable at runtime via msh local set-proxy-mode:
| Mode | Behaviour |
|---|---|
off / passthrough | Traffic is spliced through without classification or enforcement. |
observe | Dry-run: classify policy-matched requests and record would-be decisions to the observe log; never block or escalate; the audit log is not written. |
enforce | Full policy evaluation; block on deny, hold on escalate. |
Component architecture
| Component | Purpose |
|---|---|
| MITM Proxy | TLS intercept, cert generation, request routing |
| Classifier Registry | Protocol dispatch to per-CLI classifiers |
| Policy Engine | YAML rule evaluation, hot-reload via fsnotify |
| Approval Broker | In-process hold/resume with timeout |
| Audit Logger | Best-effort JSONL writer, append-only by convention |
| IPC Server | Unix socket server; CLI and desktop connect here |