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

# Browser Extensions

> Capture LLM usage from browser-based AI tools with the Toktra browser extensions.

Toktra browser extensions capture LLM usage from browser-based AI tools such as ChatGPT, Claude.ai, and others. They observe request metadata via the browser's `webRequest` API — they **never read request or response bodies, and never decrypt TLS traffic**.

## Available extensions

<CardGroup cols={2}>
  <Card title="Chrome" icon="chrome">
    Manifest V3 extension. Available from the Chrome Web Store or force-installed via Chrome policy. Compatible with all Chromium-based browsers.
  </Card>

  <Card title="Edge" icon="microsoft">
    Manifest V3 extension bundled with the Windows agent MSI. Installed automatically alongside the Windows agent.
  </Card>

  <Card title="Safari" icon="safari">
    Safari Web Extension bundled with the macOS agent. Enabled from Safari Settings after the macOS agent is installed.
  </Card>

  <Card title="Firefox" icon="firefox">
    Available as a separate install. Built as a standard Firefox WebExtension.
  </Card>
</CardGroup>

## What data is captured

The extensions use the Chrome `webRequest` API (or equivalent in each browser) to observe LLM API requests. They capture only metadata:

| Field                   | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| Provider                | LLM provider identified by hostname (e.g., `openai`, `anthropic`)                          |
| Endpoint                | API path (e.g., `/v1/chat/completions`)                                                    |
| Estimated input tokens  | Derived from the `Content-Length` request header using per-provider bytes-per-token ratios |
| Estimated output tokens | Derived from the `Content-Length` response header                                          |
| Request duration        | Time from request initiation to completion (milliseconds)                                  |
| Source domain           | Hostname of the browser tab making the request (e.g., `chat.openai.com`)                   |
| Streaming flag          | Whether the response used server-sent events                                               |

<Note>
  Token counts are estimates derived from HTTP `Content-Length` headers. The Toktra backend reconciles these estimates against authoritative provider API data to produce accurate counts.
</Note>

The extensions **never** capture:

* Request bodies (prompt text)
* Response bodies (completion text)
* Cookies or authentication tokens
* Decrypted TLS content

No `requestBody` listener is registered in the Chrome extension by design.

## Monitored providers

The Chrome extension monitors the following LLM API hostnames:

| Hostname                            | Provider      |
| ----------------------------------- | ------------- |
| `api.openai.com`                    | OpenAI        |
| `api.anthropic.com`                 | Anthropic     |
| `generativelanguage.googleapis.com` | Google Gemini |
| `api.cohere.ai` / `api.cohere.com`  | Cohere        |
| `api.mistral.ai`                    | Mistral       |
| `api.groq.com`                      | Groq          |
| `api.together.xyz`                  | Together AI   |
| `api.perplexity.ai`                 | Perplexity    |
| `openrouter.ai`                     | OpenRouter    |
| `api.deepseek.com`                  | DeepSeek      |

Only inference endpoints are monitored (paths starting with `/v1/chat/completions`, `/v1/completions`, `/v1/messages`, `/generateContent`, `/streamGenerateContent`).

## Budget preflight

When department budget hard caps are configured, the Chrome extension performs a budget validation check before each LLM request. The check completes in under 200ms and uses a 30-second cache to avoid repeated API calls.

If the check returns over-budget:

* **Soft cap exceeded**: The request proceeds, and the user receives a Chrome notification warning.
* **Hard cap exceeded**: The user receives a Chrome notification indicating the request is blocked. Server-side enforcement acts as the authoritative gate.

The budget check fails open — if the Toktra backend is unreachable, the extension always permits the request.

## Personal mode (Token Perks)

If your organization has Token Perks enabled, users can switch to Personal Mode from the extension popup. In Personal Mode, LLM usage is recorded against the user's personal token perks budget rather than the corporate allocation.

Toggle Personal Mode:

1. Click the Toktra extension icon in the browser toolbar.
2. Click the **Personal Mode** toggle in the popup.

Personal usage data is encrypted with a per-user key and never enters the corporate analytics pipeline.

## Installation

<Tabs>
  <Tab title="Chrome (IT deployment)">
    Force-install the Chrome extension across your fleet using Chrome policy. This is the recommended approach for managed devices.

    <Steps>
      <Step title="Publish to Chrome Web Store">
        Upload the extension to the Chrome Web Store as a private listing, or host it on an internal update server.
      </Step>

      <Step title="Force-install via Google Workspace Admin">
        In the Google Workspace Admin console, navigate to **Devices → Chrome → Apps & Extensions → Users & Browsers**.

        Add the extension by ID and set the installation policy to **Force install**.
      </Step>

      <Step title="Configure with managed storage">
        Pre-configure the extension using Chrome's managed storage policy. Create a JSON policy with the schema from `extension-chrome/managed_schema.json`:

        ```json theme={null}
        {
          "ingestURL": "https://ingest.your-org.toktra.io",
          "apiKey": "your-org-api-key",
          "orgID": "your-org-id",
          "enabled": true
        }
        ```

        Deploy this policy via **Chrome Management → Policy → ExtensionSettings** or push it through Google Workspace Admin.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Chrome (manual)">
    Install the extension manually for development or evaluation.

    <Steps>
      <Step title="Build the extension">
        ```bash theme={null}
        cd extension-chrome
        npm install
        npm run build
        ```
      </Step>

      <Step title="Load unpacked in Chrome">
        1. Navigate to `chrome://extensions`.
        2. Enable **Developer mode** in the top-right corner.
        3. Click **Load unpacked** and select the `extension-chrome` directory (or `dist/` after building).
      </Step>

      <Step title="Configure the extension">
        Click the Toktra extension icon → **Options** and enter your ingest URL and API key.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Edge">
    The Edge extension is bundled with the Windows agent MSI. It installs automatically when you deploy the Windows agent.

    To verify the extension is active, navigate to `edge://extensions` and confirm **Toktra LLM Usage Monitor** is listed and enabled.

    To configure the extension separately from the Windows agent, use the Edge management policy for extensions, equivalent to the Chrome policy described above.
  </Tab>

  <Tab title="Safari">
    The Safari extension is bundled with the macOS agent. It is enabled from Safari Settings after the macOS agent package is installed.

    <Steps>
      <Step title="Install the macOS agent">
        Follow the [macOS Agent](/agents/macos) installation instructions.
      </Step>

      <Step title="Enable the extension in Safari">
        Open **Safari → Settings → Extensions** and enable **Toktra**.
      </Step>

      <Step title="Grant permissions">
        When prompted, allow the extension access to websites on all domains where you use LLM tools.
      </Step>
    </Steps>

    To build the Safari extension from source:

    ```bash theme={null}
    cd device-agent/extensions/safari
    open ToktraSafari.xcodeproj
    # Build in Xcode, then enable in Safari > Settings > Extensions > Toktra
    ```
  </Tab>

  <Tab title="Firefox">
    The Firefox extension is available as a separate install from the Toktra admin dashboard.

    <Steps>
      <Step title="Build the extension">
        ```bash theme={null}
        cd device-agent/extensions/firefox
        npm install
        npm run build
        ```
      </Step>

      <Step title="Load in Firefox">
        1. Navigate to `about:debugging`.
        2. Click **This Firefox → Load Temporary Add-on**.
        3. Select `dist/manifest.json`.
      </Step>
    </Steps>

    <Warning>
      Temporary add-on installs are removed when Firefox restarts. For persistent installation, the extension must be signed by Mozilla. Contact Toktra support for a signed Firefox extension package.
    </Warning>
  </Tab>
</Tabs>

## Extension configuration reference

The Chrome and Edge extensions read configuration from managed storage (policy-installed mode) with fallback to local storage. The following keys are supported:

| Key         | Type    | Description                                          |
| ----------- | ------- | ---------------------------------------------------- |
| `ingestURL` | string  | Toktra ingest URL (e.g., `https://ingest.toktra.io`) |
| `apiKey`    | string  | Toktra organization API key for authentication       |
| `orgID`     | string  | Toktra organization identifier                       |
| `enabled`   | boolean | Enable or disable monitoring (default: `true`)       |

<Tip>
  In policy-installed mode, the `ingestURL`, `apiKey`, and `orgID` values from managed storage take precedence over anything the user configures in the extension options page.
</Tip>