> ## 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.

# Windows Agent

> Install and configure the Toktra Windows agent for enterprise LLM usage monitoring.

The Windows agent captures LLM usage metadata using a Windows Filtering Platform (WFP) kernel-mode callout driver. It observes outbound TLS connections by extracting SNI hostnames — it **never blocks traffic and never inspects content**.

## Requirements

* Windows 10 (version 1809 / build 17763) or later, 64-bit
* Administrator privileges for installation
* Intune, SCCM, or local `msiexec` for deployment

## How it works

The agent has three components that work together:

* **WFP callout driver (`toktra-wfp.sys`)** — A KMDF kernel-mode driver that registers WFP callouts at the `FWPM_LAYER_ALE_AUTH_CONNECT_V4` and V6 layers. When an outbound TLS connection is established, the `sni_inspector` extracts the SNI hostname from the TLS ClientHello. The driver **always permits** the connection — it only observes and records. Traffic is never blocked or modified.
* **Windows Service (`ToktraAgent.exe`)** — A user-mode Windows Service that polls the driver, batches events, and transmits telemetry securely to Toktra over mTLS.
* **Edge extension** — A Manifest V3 browser extension included with the MSI installer that captures browser-based LLM usage. See [Browser Extensions](/agents/browser-extensions) for details.

<Note>
  The WFP driver operates in observe-only mode. It calls `FwpsCompleteOperation` with `FWP_ACTION_PERMIT` on every connection — traffic is never delayed, blocked, or modified.
</Note>

## Installation

<Tabs>
  <Tab title="Intune (recommended)">
    Deploy the MSI silently via Microsoft Intune for managed fleet rollout.

    <Steps>
      <Step title="Upload the MSI to Intune">
        In the Intune admin center, navigate to **Apps → Windows → Add → Line-of-business app** and upload `ToktraAgent.msi`.
      </Step>

      <Step title="Configure install command">
        Set the install command to pass your ingest URL and organization ID:

        ```bat theme={null}
        msiexec /i ToktraAgent.msi /quiet ^
          INGEST_URL="https://ingest.your-org.toktra.io" ^
          ORG_ID="your-org-id"
        ```
      </Step>

      <Step title="Assign to device groups">
        Assign the app to your target device groups and set the assignment type to **Required**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="SCCM">
    Deploy the MSI via System Center Configuration Manager.

    <Steps>
      <Step title="Create an application">
        In the SCCM console, go to **Software Library → Application Management → Applications** and create a new application using the MSI detection method.
      </Step>

      <Step title="Set deployment type">
        Set the installation program to:

        ```bat theme={null}
        msiexec /i ToktraAgent.msi /quiet INGEST_URL="https://ingest.your-org.toktra.io" ORG_ID="your-org-id"
        ```

        Set the uninstall program to:

        ```bat theme={null}
        msiexec /x ToktraAgent.msi /quiet
        ```
      </Step>

      <Step title="Deploy to collection">
        Deploy the application to your target device collection with **Purpose: Required**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual (msiexec)">
    Install directly on a single machine for evaluation or testing.

    ```bat theme={null}
    msiexec /i ToktraAgent.msi /quiet ^
      INGEST_URL="https://ingest.your-org.toktra.io" ^
      ORG_ID="your-org-id"
    ```

    To install with a UI:

    ```bat theme={null}
    msiexec /i ToktraAgent.msi ^
      INGEST_URL="https://ingest.your-org.toktra.io" ^
      ORG_ID="your-org-id"
    ```
  </Tab>
</Tabs>

### MSI properties

The following properties can be passed on the `msiexec` command line or set via Intune app configuration:

| Property       | Description                                             | Default                    |
| -------------- | ------------------------------------------------------- | -------------------------- |
| `INGEST_URL`   | Toktra ingest URL                                       | `https://ingest.toktra.io` |
| `ORG_ID`       | Toktra organization identifier                          | —                          |
| `DEVICE_ID`    | Device identifier (auto-generated if omitted)           | —                          |
| `CERT_SUBJECT` | Certificate CN for mTLS client certificate lookup       | `Toktra Device`            |
| `LOG_LEVEL`    | Log verbosity: `0`=Error, `1`=Warn, `2`=Info, `3`=Debug | `2`                        |

The MSI installs:

* `ToktraAgent.exe` and supporting libraries to `%ProgramFiles%\Toktra\Agent\`
* `toktra-wfp.sys` to `%SystemRoot%\System32\drivers\`
* Registry configuration at `HKLM\SOFTWARE\Toktra\Agent`

## Configuration

All agent configuration is stored in the Windows Registry at `HKLM\SOFTWARE\Toktra\Agent`. The MSI writes initial values during installation. You can update them with `reg add` or via Group Policy / Intune registry CSP.

```
HKLM\SOFTWARE\Toktra\Agent
├── IngestUrl        REG_SZ     https://ingest.toktra.io
├── OrgId            REG_SZ     your-org-id
├── DeviceId         REG_SZ     d-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
├── CertSubject      REG_SZ     Toktra Device
├── LogLevel         REG_DWORD  2
├── EventBatchSize   REG_DWORD  50
├── FlushIntervalMs  REG_DWORD  30000
├── DriverDevicePath REG_SZ     \\.\ToktraWFP
└── Version          REG_SZ     1.0.0
```

Update a value from an elevated command prompt:

```bat theme={null}
reg add "HKLM\SOFTWARE\Toktra\Agent" ^
  /v IngestUrl ^
  /t REG_SZ ^
  /d "https://ingest.toktra.io" ^
  /f
```

After changing registry values, restart the service for changes to take effect:

```bat theme={null}
net stop ToktraAgent && net start ToktraAgent
```

## Device certificate (mTLS)

The Windows agent uses the Windows Certificate Store for mTLS client certificates — not the filesystem.

On first run, the Windows Service generates an Ed25519 key pair, sends a CSR to the Toktra enrollment endpoint, and installs the signed device certificate into the **Local Machine** certificate store under the `My` (Personal) container. The certificate subject matches the `CertSubject` registry value. The service looks up the certificate by subject at startup.

Device certificates are valid for 90 days and renew automatically.

## Budget enforcement

When department budget hard caps are enabled, the agent displays native budget status in the system tray. Over-budget requests are reported through the tray icon with a notification. Server-side enforcement acts as the authoritative gate.

## Service management

The `ToktraAgent` Windows Service is installed with `Start=Auto` and `DelayedAutoStart=Yes`. It starts automatically at boot.

```bat theme={null}
# Check service status
sc query ToktraAgent

# Restart the service
net stop ToktraAgent && net start ToktraAgent

# View recent logs (Event Viewer)
eventvwr.msc
```

The service registers events in the Windows Application Event Log under the `ToktraAgent` source.

## Uninstall

To remove the agent:

```bat theme={null}
msiexec /x ToktraAgent.msi /quiet
```

The uninstall sequence stops and removes the WFP driver (`ToktraWFP`), stops and deletes the Windows Service, and removes all files and registry keys created during installation.