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

# Device management

> View enrolled devices, manage certificates, and detect unmanaged devices running AI tools.

Toktra monitors LLM usage on every enrolled endpoint in your fleet. The **Devices** page (`DevicesPage`) gives you a live inventory of agents, their status, and certificate health — and flags unmanaged devices that are using AI tools outside your visibility.

## Viewing enrolled devices

Navigate to **Devices** in the sidebar. The table shows every device the Toktra agent has enrolled against your organization.

| Column        | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| Hostname      | The device's hostname as reported by the agent                       |
| Platform      | Operating system: `macos`, `windows`, or `linux`                     |
| Agent Version | Installed agent version                                              |
| Status        | **Enrolled** (active mTLS cert) or **Pending** (cert not yet issued) |
| Lock          | Whether the device has been locked via an emergency lockout          |
| Last Seen     | Timestamp of the most recent telemetry check-in                      |

<Tip>
  Sort by **Last Seen** to identify devices that have not checked in recently. A device silent for more than 24 hours may have connectivity issues or the agent may need restarting.
</Tip>

## Device status reference

<AccordionGroup>
  <Accordion title="Enrolled">
    The agent holds a valid device certificate and is actively transmitting telemetry. All LLM usage from this device is visible in the Usage dashboard.
  </Accordion>

  <Accordion title="Pending">
    The agent has contacted the enrollment endpoint but the certificate signing request (CSR) has not yet been approved, or the signed certificate has not been delivered to the device. This state usually resolves within a few seconds on first boot.
  </Accordion>

  <Accordion title="Locked">
    A lockout has been applied to this device — either via the Emergency Lockout page or automatically via the Okta or HRIS integration. The agent blocks outbound LLM connections until the lock is manually lifted.
  </Accordion>
</AccordionGroup>

## Device certificate lifecycle

Every enrolled device holds an **X.509 device certificate** issued by the Toktra Intermediate CA. The certificate is stored in the platform Keychain (macOS) or Windows Certificate Store (Windows) and is never written to disk in plain text.

**Key facts:**

* **Validity period:** 90 days from issuance.
* **Auto-renewal:** The agent requests a new certificate when fewer than 14 days remain. Renewal is transparent — telemetry continues uninterrupted.
* **mTLS authentication:** Every telemetry batch is authenticated using the device certificate. A device with an invalid or revoked certificate cannot connect to Toktra.

<Note>
  Toktra uses the Intermediate CA for day-to-day issuance. The Root CA is kept offline. If a certificate chain is compromised, the Intermediate CA can be rotated without reissuing the Root CA.
</Note>

### Revoking a device certificate

Revoke a certificate when a device is decommissioned, lost, or stolen.

<Steps>
  <Step title="Find the device">
    On the **Devices** page, locate the device by hostname. Use the **Last Seen** column to find stale devices.
  </Step>

  <Step title="Open the device detail">
    Click the device row to open the detail panel.
  </Step>

  <Step title="Revoke the certificate">
    Click **Revoke Certificate** and confirm. The certificate is revoked immediately. Toktra stops accepting telemetry from the device on its next connection attempt — typically within seconds.
  </Step>
</Steps>

<Warning>
  Revoking a certificate is immediate. The device must re-enroll to resume telemetry. If you are decommissioning the device permanently, also remove it from your MDM profile to prevent automatic re-enrollment.
</Warning>

### Re-enrolling a device

After a revocation, the agent re-enrolls automatically at startup if the existing certificate is absent or invalid.

<Steps>
  <Step title="Confirm the old certificate is revoked">
    Verify the device row shows **Pending** or is absent from the table.
  </Step>

  <Step title="Restart the agent on the endpoint">
    The agent generates a new key pair, sends a CSR, and receives a new signed certificate. The device returns to **Enrolled** status.
  </Step>

  <Step title="Verify the new enrollment">
    Refresh the **Devices** page. The device should appear with an **Enrolled** status and an updated **Last Seen** timestamp.
  </Step>
</Steps>

## Unmanaged device detection (shadow AI)

Toktra compares usage data received from provider admin APIs against device telemetry. Any provider usage that cannot be attributed to an enrolled, managed device is flagged as **unmanaged**.

This is the **shadow AI** detection signal: it surfaces employees using ChatGPT, Claude, or other LLM tools from personal devices, home networks, or channels that bypass the corporate agent.

**How it works:**

1. Provider pollers (OpenAI, Anthropic, Azure, GCP Vertex AI) pull authoritative token counts from provider admin APIs.
2. Toktra matches those counts against device telemetry by user identity.
3. Residual usage — provider-reported tokens with no corresponding device event — is classified as unmanaged.

You can see the unmanaged usage summary on the **Overview** page under the **Protected** status indicator. To explore it in detail, open **Usage** and filter by **Device: Unmanaged**.

<Info>
  Toktra never inspects prompt content. Unmanaged device detection is based on token count metadata only.
</Info>