# Kandji Distribution (macOS)

Deploy Capsule Security hooks for AI coding assistants across your macOS fleet using Kandji MDM. This guide covers deployment for Cursor, GitHub Copilot, Claude Code, Devin (Windsurf), and Codex using Custom Apps.

## Prerequisites

- A **Kandji** tenant with administrative access
- A **Capsule Security** account with admin access
- Target devices running macOS


## Cursor

Deploy the Cursor hooks configuration using a Kandji Custom App.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Cursor** integration
4. Download the `hooks.json` file


### Step 2: Create the Custom App

1. Log in to your Kandji tenant
2. Navigate to **Library > Custom Apps**
3. Click **Add New** and select **Custom App**
4. Configure the installation:
  - **Name**: Capsule Security Cursor Hooks
  - **Install Type**: Select **ZIP File (unzip contents into specified directory)**
  - **Unzip Location**: `/Library/Application Support/Cursor/`
5. Configure the **Preinstall Script**:

```bash
#!/bin/bash
mkdir -p "/Library/Application Support/Cursor"
chmod 755 "/Library/Application Support/Cursor"
```
6. Create a ZIP archive containing the `hooks.json` file:

```bash
zip hooks.zip hooks.json
```
7. Upload the **hooks.zip** file to the Custom App
8. Assign the Custom App to the appropriate devices or Smart Groups
9. Deploy the configuration


### Verification

After deployment, restart Cursor on target devices, then:

1. Open Cursor Settings
2. Navigate to the **Hooks** tab
3. Confirm the hooks are listed and enabled


### Uninstall

To remove the configuration from target devices, create a Kandji **Custom Script** library item that deletes the deployed file, then unassign the Custom App from the relevant devices or Smart Groups:

```bash
rm "/Library/Application Support/Cursor/hooks.json"
```

## GitHub Copilot

Deploy the GitHub Copilot hooks configuration using a Kandji Custom App.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **GitHub Copilot** integration
4. Download the `capsule-hooks.json` file


### Step 2: Create the Custom App

1. Log in to your Kandji tenant
2. Navigate to **Library > Custom Apps**
3. Click **Add New** and select **Custom App**
4. Configure the installation:
  - **Name**: Capsule Security GitHub Copilot Hooks
  - **Install Type**: Select **ZIP File (unzip contents into specified directory)**
  - **Unzip Location**: `/Library/Application Support/Code/User/hooks/`
5. Configure the **Preinstall Script**:

```bash
#!/bin/bash
mkdir -p "/Library/Application Support/Code/User/hooks"
chmod 755 "/Library/Application Support/Code/User/hooks"
```
6. Create a ZIP archive containing the `capsule-hooks.json` file:

```bash
zip hooks.zip capsule-hooks.json
```
7. Upload the **hooks.zip** file to the Custom App
8. Assign the Custom App to the appropriate devices or Smart Groups
9. Deploy the configuration


### Verification

After deployment, restart VS Code on target devices, then:

1. Right-click in the **Chat** view and select **Diagnostics**
2. Confirm the hooks are loaded and enabled


### Uninstall

To remove the configuration from target devices, create a Kandji **Custom Script** library item that deletes the deployed file, then unassign the Custom App from the relevant devices or Smart Groups:

```bash
rm "/Library/Application Support/Code/User/hooks/capsule-hooks.json"
```

## Claude Code

Deploy the Claude Code managed settings configuration using a Kandji Custom App.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Claude Code** integration
4. Click **Install** and select **macOS** as the target platform
5. Download the `managed-settings.json` file


### Step 2: Create the Custom App

1. Log in to your Kandji tenant
2. Navigate to **Library > Custom Apps**
3. Click **Add New** and select **Custom App**
4. Configure the installation:
  - **Name**: Capsule Security Claude Code Hooks
  - **Install Type**: Select **ZIP File (unzip contents into specified directory)**
  - **Unzip Location**: `/Library/Application Support/ClaudeCode/`
5. Configure the **Preinstall Script**:

```bash
#!/bin/bash
mkdir -p "/Library/Application Support/ClaudeCode"
chmod 755 "/Library/Application Support/ClaudeCode"
```
6. Create a ZIP archive containing the `managed-settings.json` file:

```bash
zip managed-settings.zip managed-settings.json
```
7. Upload the **managed-settings.zip** file to the Custom App
8. Assign the Custom App to the appropriate devices or Smart Groups
9. Deploy the configuration


### Verification

After deployment, restart Claude Code on target devices, then:

1. Run `/hooks` in Claude Code to confirm all hooks are listed
2. Start a session and verify events appear in the Capsule Security portal


### Uninstall

To remove the configuration from target devices, create a Kandji **Custom Script** library item that deletes the deployed file, then unassign the Custom App from the relevant devices or Smart Groups:

```bash
rm "/Library/Application Support/ClaudeCode/managed-settings.json"
```

## Devin (Windsurf)

Deploy the Devin (Windsurf) hooks configuration using a Kandji Custom App. The Cascade agent merges hook configurations from the system, user, and workspace levels ([Cascade hooks documentation](https://docs.devin.ai/desktop/cascade/hooks)), so deploying to the system-level path applies the Capsule hooks to every user on the device.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Devin (Windsurf)** integration
4. Choose **MDM** as the deployment method
5. Select **Mac** as the target platform and download the `hooks.json` file


### Step 2: Create the Custom App

1. Log in to your Kandji tenant
2. Navigate to **Library > Custom Apps**
3. Click **Add New** and select **Custom App**
4. Configure the installation:
  - **Name**: Capsule Security Windsurf Hooks
  - **Install Type**: Select **ZIP File (unzip contents into specified directory)**
  - **Unzip Location**: `/Library/Application Support/Windsurf/`
5. Configure the **Preinstall Script**:

```bash
#!/bin/bash
mkdir -p "/Library/Application Support/Windsurf"
chmod 755 "/Library/Application Support/Windsurf"
```
6. Create a ZIP archive containing the `hooks.json` file:

```bash
zip hooks.zip hooks.json
```
7. Upload the **hooks.zip** file to the Custom App
8. Assign the Custom App to the appropriate devices or Smart Groups
9. Deploy the configuration


### Verification

After deployment, restart Devin Desktop on target devices, then:

1. Open Devin Desktop settings
2. Navigate to the **Hooks** tab and confirm the hooks are listed and enabled
3. Start a Cascade session and verify the activity appears in the Capsule Security portal


### Uninstall

To remove the configuration from target devices, create a Kandji **Custom Script** library item that deletes the deployed file, then unassign the Custom App from the relevant devices or Smart Groups:

```bash
rm "/Library/Application Support/Windsurf/hooks.json"
```

## Codex

Deploy the Codex [managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) using a Kandji Custom App. Codex reads a managed `requirements.toml` from the system-wide path `/etc/codex/requirements.toml`; because the configuration is managed, the Capsule hooks are trusted by policy, apply to every user on the device (including users created later), and cannot be overridden or removed by users. No per-user trust approval is required.

### Step 1: Download the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations**
3. Locate the **Codex** integration
4. Choose **MDM** as the deployment method
5. Select **Mac** as the target platform and download the `requirements.toml` file


### Step 2: Create the Custom App

1. Log in to your Kandji tenant
2. Navigate to **Library > Custom Apps**
3. Click **Add New** and select **Custom App**
4. Configure the installation:
  - **Name**: Capsule Security Codex Managed Configuration
  - **Install Type**: Select **ZIP File (unzip contents into specified directory)**
  - **Unzip Location**: `/etc/codex/`
5. Configure the **Preinstall Script**:

```bash
#!/bin/bash
mkdir -p "/etc/codex"
chmod 755 "/etc/codex"
```
6. Create a ZIP archive containing the `requirements.toml` file:

```bash
zip requirements.zip requirements.toml
```
7. Upload the **requirements.zip** file to the Custom App
8. Assign the Custom App to the appropriate devices or Smart Groups
9. Deploy the configuration


Alternatively, Kandji can deliver the same configuration as a **Custom Profile** in the `com.openai.codex` preference domain, with the downloaded file's content base64-encoded into the `requirements_toml_base64` key.

### Verification

After deployment, close any running Codex CLI sessions on target devices, then:

1. Start a new Codex CLI session so the managed configuration is loaded
2. In the Capsule portal, navigate to **Inventory > Agents** and confirm the Codex agent appears


### Uninstall

To remove the configuration from target devices, create a Kandji **Custom Script** library item that deletes the deployed file, then unassign the Custom App from the relevant devices or Smart Groups:

```bash
rm -f /etc/codex/requirements.toml
```

## Key Considerations

- The preinstall scripts ensure target directories exist with proper permissions before file deployment
- Restart each application on target devices after deployment for hooks to take effect
- Updates can be deployed by modifying the Custom App and incrementing the version
- Use Kandji Smart Groups for dynamic targeting and staged rollouts
- All five integrations can be deployed as separate library items and assigned independently
- **Codex** uses a managed configuration (`/etc/codex/requirements.toml`) enforced by policy - it applies to all users on the device and cannot be overridden by user-level configuration
- **Devin (Windsurf)** merges system, user, and workspace hook configurations, so the system-level deployment coexists with any per-user hooks


## Support

For help with deployment:

- **Email**: support@capsule.security
- **Include**: Your organization ID, Kandji tenant details, and any error messages