AI flow coverage

The authoritative coverage matrix: which clients route through the mesh, and how.

This document records which workplace and personal AI flows Skilak Mesh can protect, what must be configured, and where a separate egress-control boundary is required. It describes the current v2 architecture, not a guarantee that every future client or provider protocol is covered.

The coverage rule

Skilak Mesh protects a flow when the complete AI request travels through the gateway in a representation it can fully enumerate. In practice, the client must support a custom API base URL, or the application must be owned by the operator and configured to call the mesh.

The mesh inspects registered OpenAI- and Anthropic-compatible request representations and supported request-contained files/images. Provider responses are relayed unmodified and recorded payload-free, not inspected. A successful POST /files response is bounded and parsed only to mint a file-ID attestation; it is not content-inspected. It can block, redact, warn, or allow according to policy and writes a payload-free audit event. It does not protect local filesystem reads, shell commands, browser automation, direct MCP/tool-server traffic, or any network call that does not pass through the gateway. Those need agent permissions, sandboxing, filesystem controls, and egress enforcement as separate boundaries. It is also not an output filter: it does not moderate, sanitize, or rewrite what a model returns. Query strings on known routes are forwarded unchanged; on unknown routes, the path segments and query string are scanned as request text before forwarding.

Clients address the mesh as /p/<alias>/<provider-path> — for example http://localhost:51737/p/anthropic or http://localhost:51737/p/openai/v1. The alias is the only thing that selects an upstream, and aliases are pinned in config/skilak.yaml. The client keeps and sends its own provider credential; the mesh relays it to the pinned provider and holds none of its own.

Legend:

• Full — the client can route its model traffic through the mesh in a registered representation the gateway fully enumerates.
• Conditional — coverage depends on BYOK, a custom endpoint, or a compatible mode exposed by that particular client/version.
• Blocked alternative — the native vendor app cannot be safely redirected; an egress control can block it, and the user must use an approved routed UI or CLI instead.
• Optional audit — routing is possible, but the target is local and there is no cloud-provider egress to prevent.

Launch-time coverage grades

smesh run <command> gives a new client a zero-code trial by injecting sessionized Anthropic and OpenAI base URLs into that foreground process. It reports two claims independently:

• Path coverage: requests observed at that sessionized mesh URL entered the ordinary mesh enforcement path and are subject to inspection or refusal. This is available to any tool that honors one of the injected base-URL variables.
• Client coverage: all known AI egress for the inventoried client uses the mesh. Claude Code CLI’s normal base-URL mode earns this grade. Cursor never does: its indexing and tab-completion paths use Cursor’s own backend even when a BYOK model request uses the mesh. Unknown tools receive path coverage only.

A positive session count proves only that requests reached that opaque mesh path while the foreground command was active. It does not prove process attribution or absence of direct egress. An exact zero prints launched under smesh; no traffic observed; this tool may not honour base-URL variables. A gateway restart or incomplete finish is reported as unavailable, not zero. Tools can ignore the injection by scrubbing environment variables, choosing a config-file endpoint, using an alternate backend, or hard-coding a URL; managed egress remains the boundary that can rule out those direct paths.

Client inventory and automatic adapters

Client inventory reports six independent states: installed, supported, configured, connected, gateway healthy, and protected now. Installed requires executable, application, or integration evidence. A config file alone is not installation evidence. Configured describes saved routing; connected requires current traffic evidence. Protected now is not verified unless the supported client is configured, the gateway is healthy, and current traffic evidence supports the claim.

Two automatic adapters ship:

• Claude Code CLI — its own settings adapter.
• Shared Codex configuration — ~/.codex/config.toml, which can affect both Codex CLI and Codex in VS Code. Approval names every detected affected surface; the file does not prove either surface is installed.

Gemini CLI, AGY, AnythingLLM Desktop, and other compatible clients have no shipped adapter. Inventory still shows them when installed. Their status is conditional/manual until the exact version and endpoint are verified. Installed unsupported clients such as ChatGPT Desktop, Claude Desktop, and Gemini Desktop are also shown, with the missing rerouting seam and an approved routed alternative instead of being silently omitted.

Saved settings do not update an already-running client. A route change requires a full CLI or app restart; /clear or a new chat is not enough. smesh client disconnect all restores all managed routes atomically. smesh client pause restores direct routes, waits for affected clients to restart or routed traffic to cease, and only then stops the gateway. smesh client resume starts the gateway, proves health, and then reroutes only previously approved clients. Until restart or traffic evidence is available, connected and protected now remain not verified.

Common AI workflows

Supported API boundary

Known model routes such as /v1/chat/completions, /v1/messages, /v1/embeddings, and /v1/responses remain supported under the required /p/<alias>/ prefix. An unknown provider path is admitted when it is bodyless with no unsupported declaration, or when the gateway fully enumerates its body through a registered parser. Every multipart part must be enumerable; an unsupported representation refuses. The gateway also scans the unknown path’s segments and query string as request text.

WebSocket support is narrower than HTTP route support. The default realtime.mode: inspect-text admits only the exact OpenAI /v1/responses transport with the observed responses_websockets=2026-02-06 beta and complete JSON text response.create messages. Each client message traverses the HTTP request inspection and policy path before forward. Provider events are bounded and structurally validated, but not content-inspected; binary, audio, opaque, malformed, and other upgrade traffic fails closed. Operators may select block-upgrade; pass-unscanned is prohibited.

Provider persistence is controlled per canonical prefix. files defaults on; assistants, batches, containers, conversations, fine_tuning, threads, uploads, and vector_stores default off. A disabled category is refused even when its body is enumerable, and the refusal names its provider_storage.<prefix>: true opt-in. Unknown config names fail policy load. Enabling a category does not exempt its requests from representation or content scanning.

On a successful POST /files, the gateway buffers at most the configured metadata bound, accepts one provider file object, and records its alias-scoped ID against the current enforcement revision. Recognized provider-bound JSON file-ID fields fail closed if that approval is missing, stale, expired, from a different alias, or minted under a different revision. Direct file API operations do not consume the approval. This parser is bookkeeping, not response-content inspection; provider downloads remain outside the detection boundary.

The security core has been through 15 adversarial-review rounds plus a realistic accidental-disclosure confirmation. Rounds 2–11 are written up in SECURITY-REVIEW.md — read that file with its 2026-07-28 banner: those rounds reviewed the v1 architecture, and the ones that turned on response inspection or whole-boundary query-string scanning describe code that v2 removed. Stage 1 now scans path/query text only on unknown routes. The later rounds were internal and are summarized by their outcomes here and in LIMITATIONS.md. Their critical/high findings are remediated, and the residual file-parser findings — appended bytes after a ZIP/OOXML end-of-central-directory record or a TAR end-of-archive marker — are documented adversarial-evasion limits in LIMITATIONS.md, not accidental-disclosure misses. Request-contained files and images are enabled for the pilot when their parsers fully enumerate them. Provider files are enabled with revision-bound ID reuse; the other named storage categories remain off unless the operator opts them in. An operator who wants a text-only evaluation can still set SKILAK_DENY_ALL_FILES=1 / SKILAK_DENY_ALL_IMAGES=1. Use fake/non-sensitive data during any beta.

When a vendor app cannot be redirected

The safe mitigation is block the native AI path and provide an approved routed alternative. Do not transparently DNS-redirect a vendor application to Skilak Mesh: TLS hostname validation, certificate pinning, OAuth, proprietary protocols, and request signing make that unreliable and can create a new security failure.

managed device / CI / agent workload
            |
            v
  egress firewall, MDM, or SWG
      |                   |
      | allow             | block
      v                   v
  Skilak Mesh         direct AI providers
      |
      v
approved provider APIs

Recommended enforcement layers:

Maintain both an allow policy for the mesh and a provider/domain inventory for direct-path blocking. Domain lists alone are a secondary layer: providers use changing/shared IPs and domains, clients may use QUIC or encrypted DNS, and an unmanaged device, VPN, personal hotspot, new provider domain, or local model can bypass organization policy.

No honest product claim can say “all AI traffic is protected” on an unmanaged computer. The defensible claim is: the outbound requests of supported traffic routed through Skilak Mesh are inspected and policy-enforced before they are forwarded — while managed egress policy can deny known direct AI paths and force users onto approved routed clients. Two limits are part of that claim, not footnotes to it: the provider’s responses come back relayed and uninspected, and the mesh sees only what a client is configured to send through it.

Source file: docs/AI-FLOW-COVERAGE.md in SkilakLabs/mesh.