Skip to main content

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.

The macOS agent captures LLM usage metadata using Apple’s Network Extension framework. It reads only SNI hostnames, byte counts, and request timing from TLS connections — it never decrypts traffic or inspects content.

​
Requirements

  • macOS 13 Ventura or later
  • Apple Developer Team ID (required for system extension signing and MDM deployment)
  • MDM solution: Kandji or Jamf (recommended for fleet deployment)

​
How it works

The agent consists of two components:
  • ToktraAgent — The host application that runs in the system tray, manages device enrollment, and schedules telemetry flushes.
  • ToktraExtension — An NEFilterDataProvider Network Extension that observes outbound TLS connections. It extracts the SNI hostname from the TLS ClientHello to identify LLM provider traffic. It never decrypts the connection or reads request or response bodies.
When the agent detects a connection to a known LLM provider (OpenAI, Anthropic, etc.), it records the SNI hostname, byte counts, and timing. This metadata is batched and transmitted securely to Toktra over mTLS.
The Network Extension operates at the TLS SNI level only. No prompt content, response text, or decrypted traffic ever leaves the device.

​
Installation

​
Device enrollment

On first run, the agent automatically enrolls the device with the Toktra backend:
  1. Generates an Ed25519 key pair on-device.
  2. Sends a Certificate Signing Request (CSR) to the Toktra backend’s PKI enrollment endpoint.
  3. Receives a signed X.509 device certificate from the Toktra Intermediate CA. The certificate is valid for 90 days and stored in the macOS Keychain.
  4. Uses the device certificate for mTLS authentication on every subsequent telemetry transmission.
The certificate renews automatically before expiry. No manual intervention is required.
Device certificates are stored in the system Keychain under the com.toktra.agent service name. They are scoped to the device and cannot be used to authenticate as any user.

​
Configuration

The agent reads its configuration from the ToktraDomain key in UserDefaults. Set this key via an MDM profile (recommended) or manually with defaults write.

​
Via MDM profile

Add a managed preferences payload to your MDM profile targeting com.toktra.agent: 
<dict>
    <key>PayloadType</key>
    <string>com.apple.ManagedClient.preferences</string>
    <key>PayloadContent</key>
    <dict>
        <key>com.toktra.agent</key>
        <dict>
            <key>Forced</key>
            <array>
                <dict>
                    <key>mcx_preference_settings</key>
                    <dict>
                        <key>ToktraDomain</key>
                        <string>your-org.toktra.io</string>
                    </dict>
                </dict>
            </array>
        </dict>
    </dict>
</dict>

​
Via defaults write

For testing or manual configuration, write the ToktraDomain key directly: 
sudo defaults write com.toktra.agent ToktraDomain "your-org.toktra.io"
The agent derives the Toktra API URL and update server URL from this domain at runtime.

​
Privacy hours

Privacy hours let you define a recurring schedule during which the agent pauses monitoring. This is intended for personal use time outside of work hours. Configure privacy hours from the system tray: click the Toktra icon → Privacy Hours → Configure Schedule. You can also configure them via MDM by adding PrivacyHoursStart and PrivacyHoursEnd keys (24-hour format) to the com.toktra.agent managed preferences: 
<key>PrivacyHoursStart</key>
<string>18:00</string>
<key>PrivacyHoursEnd</key>
<string>09:00</string>
During privacy hours, the Network Extension remains loaded but does not record or transmit events.

​
Personal mode (Token Perks)

If your organization has Token Perks enabled, employees can toggle Personal Mode to track personal AI usage separately from corporate usage. Personal usage data is encrypted with a per-user key and never enters the corporate analytics pipeline. Toggle Personal Mode from the system tray: click the Toktra icon → Personal Mode. When Personal Mode is active, a distinct indicator appears in the menu bar icon.

​
Budget enforcement

When department budget hard caps are configured, the agent enforces them with a budget status indicator in the menu bar.
  • The menu bar icon shows remaining budget status at a glance.
  • When a user is over budget, the agent blocks over-budget requests.
  • The status view displays the current period’s spend, remaining allocation, and limit type (soft cap warning vs. hard cap block).
Budget enforcement requires the FF_BUDGET_HARD_CAPS feature flag to be enabled on your Toktra tenant. Contact your Toktra administrator to enable this feature.

​
Logs

The agent writes logs to /var/log/toktra/:
FileContents
/var/log/toktra/agent.logStandard output
/var/log/toktra/agent-error.logStandard error
These paths correspond to the agent’s LaunchDaemon log configuration.