> ## Documentation Index
> Fetch the complete documentation index at: https://quintsecurity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How Quint Works

> End-to-end flow from agent action to enforced decision — one page, every layer, every handoff

# How Quint Works

Quint sits between AI agents and the services they touch. It captures every action, enriches it with process-level ground truth, and checks it against the **scope compiled from the agent's stated intent** — allowing, flagging, or blocking it deterministically. The model that reads intent never makes the enforcement decision: it compiles the scope, and a microsecond bitmask + glob check disposes.

## The three tiers

```mermaid theme={null}
flowchart TB
    subgraph EDGE["EDGE (user's machine)"]
        direction LR
        AGENT["AI Agent"] --> PROXY["Forward Proxy<br/>or NE Extension"]
        ES["Endpoint Security<br/>(kernel events)"] --> DAEMON
        PROXY --> DAEMON["Edge Daemon<br/>unisession.Tracker"]
    end

    DAEMON --> CLOUD["Cloud API<br/>ingest + scoring"]

    subgraph CLOUD_STACK["CLOUD"]
        direction LR
        INGEST["Ingestion<br/>(SNS → SQS)"] --> PIPE["Pipeline<br/>(Postgres)"]
        PIPE --> SCORE["Cross-session divergence<br/>+ fleet learning"]
        SCORE --> DASH["Dashboard"]
    end

    CLOUD --> INGEST

    style EDGE fill:#0d1117,stroke:#FF3C22,stroke-width:2px
    style CLOUD_STACK fill:#0d1117,stroke:#58a6ff,stroke-width:2px
```

**Edge (intent + truth):** Two interception paths capture what the agent is trying to do. The [Forward Proxy](/edge/forward-proxy) MITMs HTTPS traffic to get LLM conversations and tool calls. The [Endpoint Security extension](/edge/endpoint-security) watches the kernel for process spawns and file operations. Both feed the [Edge Daemon](/edge/daemon), which unifies them into a single session model via `unisession.Tracker`.

**Enforcement (edge, deterministic):** The compiled scope is enforced on the machine. Local tool calls that fall outside scope are denied by the quint-hook `PreToolUse` check; out-of-scope network egress is denied by the proxy. The Endpoint Security stream is notify-only — it is the agent-unauthorable ground truth, not a blocking surface.

**Cloud (learning + fleet):** The daemon streams structured intent frames (hash-only text by default) to the cloud. [Ingestion](/cloud/ingestion) fans them out; the cloud runs 5-minute **cross-session divergence** analysis and the fleet learning loop. It never scores an individual action on the blocking path, and it never sees conversation content. Results surface in the [Dashboard](/dashboard/overview).

**Intelligence (closing the loop):** Confirmed local determinations feed a federated learning loop — *models ship to the data, only geometry ships back*. The cloud pushes down signed, versioned artifacts (updated intent-model weights, exemplar embeddings, workflow priors, scope templates). The re-aimed GNN that mines cross-org attack shapes lives here, at the global tier, sequenced after Phase 2. See [Intent vs Truth](/concepts/intent-vs-truth).

## A single tool call, end to end

Follow one `Bash` tool call from a Claude Code session:

1. **User types a prompt.** Claude Code sends a streaming POST to `bedrock-runtime.us-east-1.amazonaws.com`.
2. **Interception.** On macOS, the [NE extension](/edge/network-extension) recognizes the Bedrock hostname and relays the flow to the daemon on port 9091. On other OSes, `HTTPS_PROXY` routes it through the forward proxy.
3. **MITM TLS.** The daemon presents a leaf cert signed by the local Quint CA. The client thinks it's talking to Bedrock.
4. **Request parsing.** [llmparse](/edge/forward-proxy#llm-api-parsing) detects Bedrock eventstream format, extracts the model (`claude-opus-4-7`), tools, and messages.
5. **Session stamping.** The daemon looks up the source PID in `unisession.Tracker`. Every audit row for this flow gets `session_id = "{rootPID}-{startUnixMs}"`.
6. **Forward to upstream.** Request is re-signed and sent to real Bedrock. Response streams back as chunked SSE.
7. **Tool call extraction.** When the response produces a `tool_use` block (e.g. `Bash({"command":"ls"})`), the parser extracts it and fires `OnToolCall`.
8. **Local audit.** The tool call, request, and response are persisted to the signed audit log (`quint.db`). Each row is Ed25519-signed and chained via `prev_hash`.
9. **Cloud forward.** A structured `QuintEvent` is enqueued in the cloud forwarder (batched 100 events / 2s, retries 5x with backoff, overflows to disk).
10. **Cloud ingest.** `api.quintai.dev/v1/ingest` stamps `org_id` from the deploy token, publishes to SNS, fans out to SQS.
11. **Scope check.** Before the tool call runs, the edge checks it against the scope compiled from the current turn's intent: a bitmask + glob match (**Gate 0.5**, \~1µs). In-scope actions emit nothing; an out-of-scope action against a sensitive resource is the one block-capable signal (`scope:out_of_scope_sensitive`). The cloud separately runs cross-session divergence analysis in the background — never on this action's blocking path.
12. **Enforcement + dashboard.** If the action is out of scope, it is denied at the edge (local tool calls via the quint-hook `PreToolUse` deny, egress via the proxy). The determination lands in Postgres and SSE pushes it to the [Sessions view](/dashboard/sessions).

## Design principles

**Intent vs. truth.** The proxy sees what the agent *claims* to do. The ES extension sees what the OS *actually* does. Divergence is the key signal — an agent that says "read config.json" but actually opens `~/.ssh/id_rsa` trips a high-confidence alert.

**Local-first enforcement, cloud-first learning.** Every enforcement decision is made on the machine; the cloud never sits on a blocking path. Raw bodies, credentials, and conversation content never leave the machine — only structured intent frames (capability, sensitivity class, resource shape; text hash-only by default) go to the cloud. This lets enterprises keep sensitive content on-device while still getting fleet-wide learning.

**Lossy at the edge, durable in the cloud.** Under backpressure, the NE extension drops events rather than block the user's network. The cloud forwarder retries and overflows to disk. Trade off individual events for availability.

**Zero client changes where possible.** Forward proxy + NE extension means agents don't need SDK integration, env var reconfiguration, or new endpoints. The interception is invisible.

## Where to go next

<CardGroup cols={2}>
  <Card title="Edge Architecture" icon="microchip" href="/edge/daemon">
    How the daemon, proxy, ES, and NE fit together on one machine
  </Card>

  <Card title="Cloud Architecture" icon="cloud" href="/cloud/ingestion">
    Event ingestion, scoring, and fleet aggregation
  </Card>

  <Card title="Intent vs Truth" icon="brain" href="/concepts/intent-vs-truth">
    Scope compilation, QIM, divergence, and the fleet learning loop
  </Card>

  <Card title="Dashboard" icon="chart-line" href="/dashboard/overview">
    What customers see: sessions, alerts, policies, fleet
  </Card>
</CardGroup>