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

# Agent deployment

> Deploy Toktra agents at scale across your macOS, Windows, and Linux fleet using MDM, Intune, SCCM, or package managers.

The Toktra agent runs on macOS, Windows, and Linux. This page covers deploying agents silently at scale across a managed fleet. For a single-machine install, see the [Quickstart](/quickstart).

<Info>
  Each platform has its own agent page with build requirements, configuration details, and troubleshooting. See [macOS](/agents/macos), [Windows](/agents/windows), and [Linux](/agents/linux).
</Info>

## Deployment overview

Deploying Toktra involves two things:

1. **Pushing the agent package** — the installer or package that puts the agent binary on the device.
2. **Pre-approving system components** — on macOS, the Network Extension requires MDM pre-approval to install silently. On Windows, the WFP driver requires elevation. Linux packages handle this through the package manager.

Once installed, each agent automatically enrolls with Toktra by generating a key pair, submitting a Certificate Signing Request (CSR), and receiving a signed device certificate from Toktra's intermediate CA. No manual configuration is required on the device.

## macOS — Kandji or Jamf

The macOS agent requires a Network Extension, which macOS blocks from installing without user interaction unless an MDM profile pre-approves it.

<Steps>
  <Step title="Build and notarize the package">
    Download the Toktra `.pkg` installer from **Settings → Downloads** in the dashboard, or build it from source if your security policy requires it. The package must be notarized with a valid Apple Developer ID before deployment.
  </Step>

  <Step title="Push the MDM configuration profile">
    Upload `com.toktra.agent.mobileconfig` to your MDM and push it to the target device group. This profile pre-approves the `com.toktra.agent.extension` Network Extension for the Toktra team ID, preventing the user prompt.

    Replace `TOKTRA_TEAM_ID` in the profile with your Apple Developer Team ID before uploading.

    <Tabs>
      <Tab title="Kandji">
        In Kandji, go to **Library → Add → Custom Profile**, upload the `.mobileconfig` file, and assign it to the relevant blueprint.
      </Tab>

      <Tab title="Jamf Pro">
        In Jamf Pro, go to **Computers → Configuration Profiles → New**, upload the `.mobileconfig` file under the **General** payload, and scope it to the relevant computer group.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Deploy the package silently">
    After the profile is applied, deploy the `.pkg` installer via your MDM's software deployment feature. The installer runs silently without user prompts.

    <Tabs>
      <Tab title="Kandji">
        In Kandji, add a **Custom App** under **Library**, upload the `.pkg`, and assign it to the blueprint. Set the install type to **Install Automatically**.
      </Tab>

      <Tab title="Jamf Pro">
        In Jamf Pro, use a **Policy** with a **Packages** payload. Set the execution frequency to **Once per computer** and scope it to the target group.
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Note>
  The macOS agent also ships a LaunchDaemon plist (`com.toktra.agent.plist`) and a watchdog plist (`com.toktra.watchdog.plist`). These are included in the `.pkg` installer and are installed automatically to keep the agent running after reboots.
</Note>

## Windows — Intune or SCCM

The Windows agent ships as an MSI package. It installs a WFP callout driver, a Windows Service, and the Edge browser extension. The driver installation requires administrator privileges.

<Steps>
  <Step title="Obtain the MSI">
    Download the Toktra MSI from **Settings → Downloads** in the dashboard. The installer is built with WiX v4 and is signed with a Sectigo EV certificate.
  </Step>

  <Step title="Deploy via Intune or SCCM">
    <Tabs>
      <Tab title="Microsoft Intune">
        In Intune, go to **Apps → Windows apps → Add**, select **Line-of-business app**, and upload the `.msi`. Set the install command:

        ```powershell theme={null}
        msiexec /i ToktraAgent.msi /qn
        ```

        Assign the app to the relevant device group. Intune deploys it silently on the next sync.
      </Tab>

      <Tab title="SCCM / ConfigMgr">
        In SCCM, create a new **Application**, add a **Windows Installer** deployment type, and set the installation program to:

        ```powershell theme={null}
        msiexec /i ToktraAgent.msi /qn
        ```

        Deploy to the target device collection with the purpose set to **Required**.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify the service is running">
    After deployment, confirm the Toktra Windows Service is running:

    ```powershell theme={null}
    Get-Service -Name ToktraAgent
    ```

    The service status should be `Running`. Configuration is stored in the Windows registry at `HKLM\SOFTWARE\Toktra\Agent`. Device certificates are stored in the Windows Certificate Store, not on the filesystem.
  </Step>
</Steps>

<Warning>
  The WFP callout driver observes network traffic but **never blocks it** — all traffic is permitted. Toktra only records connection metadata. No firewall rules are added.
</Warning>

## Linux — package manager

The Linux agent ships as `.deb` and `.rpm` packages. It runs as a systemd service and uses eBPF for socket-level monitoring. Linux kernel 5.10 or later with BTF support is required.

<Steps>
  <Step title="Add the Toktra package repository">
    <Tabs>
      <Tab title="Debian/Ubuntu">
        ```bash theme={null}
        curl -fsSL https://packages.toktra.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/toktra.gpg
        echo "deb [signed-by=/usr/share/keyrings/toktra.gpg] https://packages.toktra.io/apt stable main" \
          | sudo tee /etc/apt/sources.list.d/toktra.list
        sudo apt update
        ```
      </Tab>

      <Tab title="RHEL/CentOS/Fedora">
        ```bash theme={null}
        sudo rpm --import https://packages.toktra.io/gpg
        sudo tee /etc/yum.repos.d/toktra.repo <<'EOF'
        [toktra]
        name=Toktra
        baseurl=https://packages.toktra.io/rpm
        enabled=1
        gpgcheck=1
        gpgkey=https://packages.toktra.io/gpg
        EOF
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install the agent">
    <Tabs>
      <Tab title="Debian/Ubuntu">
        ```bash theme={null}
        sudo apt install toktra-agent
        ```
      </Tab>

      <Tab title="RHEL/CentOS/Fedora">
        ```bash theme={null}
        sudo dnf install toktra-agent
        ```
      </Tab>
    </Tabs>

    The post-install script enables and starts the `toktra-agent` systemd service automatically.
  </Step>

  <Step title="Verify the daemon is running">
    ```bash theme={null}
    systemctl status toktra-agent
    ```

    Configuration lives at `/etc/toktra/agent.conf` (TOML format). Environment variables override the config file.
  </Step>
</Steps>

<Tip>
  For fleet-scale Linux deployments, Toktra ships an osquery table extension (`toktra_connections`) that lets you query LLM usage data directly from Fleet or Kolide alongside your other device inventory.
</Tip>

## Enrollment overview

When a Toktra agent starts for the first time on a new device, it:

1. Generates an Ed25519 key pair on the device.
2. Submits a Certificate Signing Request (CSR) to the Toktra enrollment endpoint.
3. Receives a signed X.509 device certificate from Toktra's intermediate CA. The certificate is valid for 90 days.
4. Uses that certificate for mutual TLS on all subsequent connections to Toktra.

Certificates are renewed automatically before expiry. You don't need to manage certificate rotation manually.

<AccordionGroup>
  <Accordion title="Where are device certificates stored?">
    On macOS, device certificates are stored in the system Keychain under the Toktra agent's entitlement. On Windows, they are stored in the Windows Certificate Store (not the filesystem). On Linux, they are stored at `/etc/toktra/certs/`.
  </Accordion>

  <Accordion title="What happens if enrollment fails?">
    The agent retries enrollment with exponential backoff. Check that the device has outbound HTTPS access to `ingest.toktra.io`. On macOS, also verify that the Network Extension is approved in **System Settings → Privacy & Security → Extensions**.
  </Accordion>

  <Accordion title="Can I pre-provision certificates for zero-touch enrollment?">
    Yes. Contact your Toktra account team to configure pre-provisioned certificates for environments where devices cannot reach the enrollment endpoint during initial setup.
  </Accordion>
</AccordionGroup>