> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kelasa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enroll a device

> Install the Kelasa device agent and connect a machine to AI Usage

The Kelasa device agent is a small background service that reports
[device telemetry](/concepts/device-telemetry) — metadata-only evidence of AI
tool presence and usage. Enrollment ties a device to a person in your
workspace with a one-time code.

<Info>
  Generating enrollment codes and viewing device data requires a workspace
  admin. The agent currently supports macOS.
</Info>

## Enroll

<Steps>
  <Step title="Get a one-time code">
    In the web app, open **AI Usage** in the sidebar, select the person the
    device belongs to, and click **Add this device**. The dialog shows a
    one-time enrollment code with its expiry, plus the exact commands for the
    remaining steps — copy them from there.
  </Step>

  <Step title="Install the agent binary">
    Run the install one-liner from the dialog on the device. It places the
    `kelasa-agent` binary on the machine.
  </Step>

  <Step title="Enroll with the code">
    As your normal user (not sudo), run the enroll command from the dialog:

    ```sh theme={null}
    kelasa-agent enroll <code>
    ```

    This exchanges the one-time code for a device credential stored locally.
    Codes are single-use and expire, so generate a fresh one if it lapses.
  </Step>

  <Step title="Install the background service">
    ```sh theme={null}
    sudo kelasa-agent install
    ```

    This registers the agent as a system service that starts at boot and
    adopts the enrollment from the previous step.
  </Step>

  <Step title="Grant Full Disk Access (macOS)">
    In **System Settings → Privacy & Security → Full Disk Access**, enable
    the `kelasa-agent` binary. Without it the browser and Claude-config
    collectors report "permission denied" coverage instead of data — the agent
    still runs, and the device page shows the gap honestly.
  </Step>
</Steps>

The device appears in **AI Usage** under its owner within about a minute of
the service starting, with its inventory and usage evidence.

## Claude Code usage — configured automatically

The agent runs a local, loopback-only telemetry receiver and merges the five
required telemetry settings into the device's `~/.claude/settings.json`,
leaving every other key untouched. Claude Code usage starts flowing with no
manual setup, and `uninstall` removes exactly those keys again.

## Revoke or remove

* **Revoke** a device from its device page in the web app — its credential
  stops working immediately and it can no longer check in.
* **Uninstall** on the machine itself:

  ```sh theme={null}
  sudo kelasa-agent uninstall
  ```

  This removes the background service and reverts the Claude Code telemetry
  settings the agent added.