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.

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

Deploy the Cursor hooks configuration using a Kandji Custom App.

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

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:

   #!/bin/bash
   mkdir -p "/Library/Application Support/Cursor"
   chmod 755 "/Library/Application Support/Cursor"

6. Create a ZIP archive containing the hooks.json file:

   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

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

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:

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

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

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

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:

   #!/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 hooks.json file:

   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

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

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:

rm "/Library/Application Support/Code/User/hooks/hooks.json"

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

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

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:

   #!/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:

   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

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

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:

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

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), so deploying to the system-level path applies the Capsule hooks to every user on the device.

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

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:

   #!/bin/bash
   mkdir -p "/Library/Application Support/Windsurf"
   chmod 755 "/Library/Application Support/Windsurf"

6. Create a ZIP archive containing the hooks.json file:

   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

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

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:

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

Deploy the Codex 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.

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

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:

   #!/bin/bash
   mkdir -p "/etc/codex"
   chmod 755 "/etc/codex"

6. Create a ZIP archive containing the requirements.toml file:

   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.

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

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:

rm -f /etc/codex/requirements.toml

• 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

For help with deployment:

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