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

# How it works

> Toktra captures LLM usage metadata at the device level and delivers it to your dashboard in real time — without decrypting any traffic.

Toktra is built on a simple principle: observe what AI tools are being used, by whom, and how much — without ever reading what's being said. Here's how data moves from a device to your dashboard.

## The data flow

```
Device agent → Toktra cloud → Dashboard
```

At each step, Toktra processes only the metadata it needs and discards everything else.

<Steps>
  <Step title="The agent observes outbound connections">
    When a user on an enrolled device sends a request to an LLM provider — ChatGPT, Claude, Copilot, or any supported service — the Toktra agent sees the outbound TLS connection before it's encrypted.

    The agent reads the **SNI (Server Name Indication)** field from the TLS handshake. SNI is a plain-text extension that tells the server which hostname the client wants to connect to. It's present in every TLS connection and contains only the destination hostname — the agent never sees the encrypted request body or response content.

    The agent also records:

    * Byte counts (request size and response size)
    * Connection timing
    * The local user account making the request

    It classifies the connection as an LLM provider event using a list of known provider hostnames (`api.openai.com`, `api.anthropic.com`, and others), then estimates token counts from the byte counts using provider-specific ratios.
  </Step>

  <Step title="Events are transmitted securely">
    The agent buffers events locally and sends them in encrypted batches to Toktra's cloud over mutual TLS (mTLS).

    Both sides authenticate: Toktra's servers present a certificate, and the agent presents its device certificate — signed by Toktra's certificate authority during enrollment. A device without a valid certificate cannot connect.
  </Step>

  <Step title="Toktra processes and stores events">
    Toktra's cloud backend validates the device certificate, confirms the device belongs to your organization, and enriches each event with user and device metadata before storing it for analytics.

    Events are classified by provider, model, and usage category in real time.
  </Step>

  <Step title="The dashboard shows your data">
    The Toktra dashboard queries the backend API for usage analytics and device and user records. Dashboard data is scoped strictly to your organization — no tenant can access another's data.
  </Step>
</Steps>

## Shadow AI detection

The data flow above covers usage on **managed devices** — machines where you've installed the Toktra agent. But what about employees using AI tools on personal laptops, phones, or via accounts you didn't provision?

Toktra detects this through **provider API reconciliation**.

Toktra polls the admin APIs of supported providers — OpenAI, Anthropic, Azure OpenAI, and Google Cloud Vertex AI — to retrieve your organization's total usage directly from the provider. It then compares that total against the usage your agents reported from managed devices.

If the provider reports more usage than your agents saw, the difference represents activity on **unmanaged devices**. Toktra surfaces this gap in the dashboard so you know shadow AI is happening, even if you can't attribute it to a specific person.

<Info>
  Provider API reconciliation requires API keys for each provider's admin/organization API. You configure these in **Settings → Provider Connections**.
</Info>

## Real-time dashboard updates

Usage data appears in the dashboard within seconds of a request being made. The pipeline is designed for low latency:

* Agent batching window: 50 events or 5 seconds
* Cloud ingestion: sub-second
* Analytics pipeline: near real-time

The dashboard's Overview page shows rolling 30-day totals. The Usage page provides per-user, per-model, and per-period breakdowns with full filtering.

## What Toktra never does

* **Never decrypts TLS traffic.** The SNI hostname is read from the unencrypted TLS handshake header. The encrypted payload is never touched.
* **Never captures prompt content.** The agent records byte counts and timing, not request or response bodies.
* **Never blocks traffic.** The macOS Network Extension and Windows WFP driver are observation-only. All traffic is permitted.
* **Never shares data across tenants.** Every data store is scoped to your organization — cross-tenant access is architecturally prevented.