---
title: "Installation"
canonical_url: "https://docs.getdx.com/ai-code-insights/installation/"
md_url: "https://docs.getdx.com/ai-code-insights/installation.md"
last_updated: "2026-05-22"
---

# Installation
Install the AI Code Insights daemon on macOS, Windows, or Linux. For organization-wide deployment, see [MDM installation](https://docs.getdx.com/ai-code-insights/mdm-installation/). If your organization later deploys via MDM, the MDM installation overwrites an individual install cleanly — no conflicts or manual cleanup required.

> **Note**: The daemon must run on the same machine where the code lives. For remote development over SSH or in devcontainers, install the daemon on the remote host, not the developer's local machine.

## Step 1: Enable

Go to **Admin** -> [**AI Code Insights**](https://app.getdx.com/admin/ai-code-insights), click **Enable feature**, and copy your API URL and token.

## Step 2: Configure

Create a config file with the credentials from step 1.

| Platform | Config path                                |
| -------- | ------------------------------------------ |
| macOS    | `~/.aicodemetrics/config.json`             |
| Windows  | `%LOCALAPPDATA%\aicodemetrics\config.json` |
| Linux    | `~/.aicodemetrics/config.json`             |

```json
{
    "api_url": "API_URL",
    "api_key": "API_TOKEN"
}
```

For additional settings, see [Configuration](https://docs.getdx.com/ai-code-insights/configuration/).

## Step 3: Install

Download and run the installer for your platform from **Admin** -> [**AI Code Insights**](https://app.getdx.com/admin/ai-code-insights). All installers are code-signed with an Atlassian certificate. The daemon starts automatically after installation.

| Platform | Installer                            |
| -------- | ------------------------------------ |
| macOS    | `ai-code-metrics-darwin.pkg`         |
| Windows  | `ai-code-metrics-windows-amd64.msi`  |
| Linux    | `ai-code-metrics-linux-amd64.tar.gz` |

On Linux, extract the archive with `tar -xzf` and run `./install.sh`.

> **Note**: On macOS, if repositories are in protected directories (`Desktop`, `Downloads`, `Documents`), grant Full Disk Access to `/usr/local/bin/aicodemetricsd` under **System Settings** -> **Privacy & Security** -> **Full Disk Access**.

> **Note**: If developers use the Codex Mac app, Codex may prompt them to trust the AI Code Insights hook after installation. Trust the hook command that includes `/usr/local/bin/aicodemetricsd hook codex` so Codex session data can be collected.

> **Note**: On Linux, only Debian and Red Hat-based distributions on amd64 are supported. For other distributions or ARM64, contact the DX team.

## Step 4: Verify

After installation, the daemon fetches the list of monitored repositories from your organization's [Data Cloud](https://docs.getdx.com/data-cloud/) and begins observing code changes. Data appears in DX reports after the first push from a monitored repository.

Check the daemon's logs for a successful connection:

| Platform | Log command                                                       |
| -------- | ----------------------------------------------------------------- |
| macOS    | `cat ~/Library/Logs/AI\ Code\ Metrics/aicodemetrics.log`          |
| Windows  | `Get-Content "$env:LOCALAPPDATA\aicodemetrics\aicodemetrics.log"` |
| Linux    | `cat ~/.aicodemetrics/aicodemetrics.log`                          |

A healthy daemon logs:

```terminaloutput
[INFO] Successfully polled repositories: X found
```

If API communication fails:

```terminaloutput
[ERROR] Failed to fetch repositories from API: <error details>
[ERROR] API authentication failed: <error details>
```

## Upgrades

Download the latest installer from **Admin** -> [**AI Code Insights**](https://app.getdx.com/admin/ai-code-insights) and run it. The installer updates the daemon in place — no configuration changes required. See [Upgrades](https://docs.getdx.com/ai-code-insights/configuration/#upgrades) for details.

## Troubleshooting

If the daemon does not start or data is not appearing in DX, see [Troubleshooting](https://docs.getdx.com/ai-code-insights/troubleshooting/).

## Uninstallation

See [Uninstallation](https://docs.getdx.com/ai-code-insights/uninstallation/) for platform-specific removal steps.
---

## Sitemap

[Overview of all docs pages](/llms.txt)