# JumpCloud Distribution (macOS)

Deploy Capsule Security hooks for AI coding assistants across your macOS fleet using JumpCloud. This guide covers deployment for Cursor, GitHub Copilot, Claude Code, Devin (Windsurf), and Codex using JumpCloud **Commands**, which run a shell script as `root` on bound devices.

## Prerequisites

- A **JumpCloud** administrator account
- The **JumpCloud agent** installed on target devices
- A **Capsule Security** account with admin access
- Target devices running macOS


## Cursor

Deploy the Cursor hooks configuration using a JumpCloud Command.

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

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security Cursor Hooks
  - **Type**: **Mac**
  - **Run As user**: **root** (required for the system-wide path below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `hooks.json` (keep the `CAPSULE_HOOKS_EOF` marker lines unchanged and unindented):

```bash
#!/bin/bash
HOOKS_DIR="/Library/Application Support/Cursor"
mkdir -p "$HOOKS_DIR"
chmod 755 "$HOOKS_DIR"
cat > "$HOOKS_DIR/hooks.json" << 'CAPSULE_HOOKS_EOF'
<PASTE YOUR HOOKS.JSON CONTENT HERE>
CAPSULE_HOOKS_EOF
chmod 644 "$HOOKS_DIR/hooks.json"
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs on the bound devices
4. Review the **Results** tab to confirm the command completed successfully


### Verification

After the command reports success, restart Cursor on target devices, then:

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


## GitHub Copilot

Deploy the GitHub Copilot hooks configuration using a JumpCloud Command. VS Code reads Copilot hooks from each user's `~/Library/Application Support/Code/User/hooks/` directory rather than a system-wide path, so the command runs as root and writes the configuration into every user profile on the device.

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

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security GitHub Copilot Hooks
  - **Type**: **Mac**
  - **Run As user**: **root** (required to write into each user's home directory below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `capsule-hooks.json` (keep the `CAPSULE_HOOKS_EOF` marker lines unchanged and unindented):

```bash
#!/bin/bash

for USER_HOME in /Users/*/; do
    USERNAME=$(basename "$USER_HOME")
    if [ "$USERNAME" = "Shared" ] || [ "$USERNAME" = ".localized" ]; then
        continue
    fi
    HOOKS_DIR="$USER_HOME/Library/Application Support/Code/User/hooks"
    mkdir -p "$HOOKS_DIR"
    cat > "$HOOKS_DIR/capsule-hooks.json" << 'CAPSULE_HOOKS_EOF'
<PASTE YOUR CAPSULE-HOOKS.JSON CONTENT HERE>
CAPSULE_HOOKS_EOF
    chmod 644 "$HOOKS_DIR/capsule-hooks.json"
    chown "$USERNAME" "$HOOKS_DIR" "$HOOKS_DIR/capsule-hooks.json"
done
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs to cover users created later
4. Review the **Results** tab to confirm the command completed successfully


### Verification

After the command reports success, 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


## Claude Code

Deploy the Claude Code managed settings configuration using a JumpCloud Command.

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

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security Claude Code Hooks
  - **Type**: **Mac**
  - **Run As user**: **root** (required for the system-wide path below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `managed-settings.json` (keep the `CAPSULE_HOOKS_EOF` marker lines unchanged and unindented):

```bash
#!/bin/bash
SETTINGS_DIR="/Library/Application Support/ClaudeCode"
mkdir -p "$SETTINGS_DIR"
chmod 755 "$SETTINGS_DIR"
cat > "$SETTINGS_DIR/managed-settings.json" << 'CAPSULE_HOOKS_EOF'
<PASTE YOUR MANAGED-SETTINGS.JSON CONTENT HERE>
CAPSULE_HOOKS_EOF
chmod 644 "$SETTINGS_DIR/managed-settings.json"
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs on the bound devices
4. Review the **Results** tab to confirm the command completed successfully


### Verification

After the command reports success, 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


## Devin (Windsurf)

Deploy the Devin (Windsurf) hooks configuration using a JumpCloud Command. Cascade 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, and they cannot be disabled by end users.

### 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. Select **Mac** as the target platform and download the `hooks.json` file


### Step 2: Create the Command

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security Devin (Windsurf) Hooks
  - **Type**: **Mac**
  - **Run As user**: **root** (required for the system-wide path below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `hooks.json` (keep the `CAPSULE_HOOKS_EOF` marker lines unchanged and unindented):

```bash
#!/bin/bash
HOOKS_DIR="/Library/Application Support/Windsurf"
mkdir -p "$HOOKS_DIR"
chmod 755 "$HOOKS_DIR"
cat > "$HOOKS_DIR/hooks.json" << 'CAPSULE_HOOKS_EOF'
<PASTE YOUR HOOKS.JSON CONTENT HERE>
CAPSULE_HOOKS_EOF
chmod 644 "$HOOKS_DIR/hooks.json"
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs on the bound devices
4. Review the **Results** tab to confirm the command completed successfully


### Verification

Hooks are loaded at application start, so after the command reports success, close Devin Desktop completely on target devices and reopen it, then:

1. Start a **Cascade** session and run a simple task to generate activity
2. In the Capsule portal, navigate to **Inventory > Agents** and confirm the agent appears


## Codex

Deploy the Codex [managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) using a JumpCloud Command. 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.

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

### Step 1: Download the Configuration

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


### Step 2: Create the Command

1. Log in to the **JumpCloud Admin Portal**
2. Navigate to **DEVICE MANAGEMENT > Commands**
3. Click **(+)** and select **Command**
4. On the **Details** tab, configure the command:
  - **Name**: Deploy Capsule Security Codex Managed Configuration
  - **Type**: **Mac**
  - **Run As user**: **root** (required for the system-wide path below)
5. Paste the following into the **Command** field, replacing the placeholder line with the contents of the downloaded `requirements.toml` (keep the `CAPSULE_REQUIREMENTS_EOF` marker lines unchanged and unindented):

```bash
#!/bin/bash
CODEX_DIR="/etc/codex"
mkdir -p "$CODEX_DIR"
chmod 755 "$CODEX_DIR"
cat > "$CODEX_DIR/requirements.toml" << 'CAPSULE_REQUIREMENTS_EOF'
<PASTE YOUR REQUIREMENTS.TOML CONTENT HERE>
CAPSULE_REQUIREMENTS_EOF
chmod 644 "$CODEX_DIR/requirements.toml"
exit 0
```


### Step 3: Bind and Run

1. Select the **Device Groups** tab (or the **Devices** tab) and bind the target device groups or devices
2. Click **Save**
3. On the **Commands** page, click **Run Now** to execute the command, or configure a schedule so it re-runs on the bound devices
4. Review the **Results** tab to confirm the command completed successfully


### Verification

After the command reports success, 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 with session, prompt, response, and tool-invocation events


## Key Considerations

- Commands run as `root`, so they can create the target directories and write the configuration files - including into each user's home for the per-user integrations - without additional privileges
- To update configurations, edit the command's script and re-run it on the bound devices
- Use JumpCloud Device Groups for dynamic targeting and staged rollouts
- All five integrations can be deployed as separate commands and bound independently
- **GitHub Copilot** uses a per-user path (`~/Library/Application Support/Code/User/hooks/capsule-hooks.json`), so a single run only covers user accounts that exist at execution time - schedule the command to re-run so it covers users created later
- **Codex** uses a managed configuration (`/etc/codex/requirements.toml`) enforced by policy - it applies to all users on the device (including users created later) 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 and cannot be disabled by end users
- Restart each application on target devices after deployment for hooks to take effect


## Support

For help with deployment:

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


## References

- [JumpCloud Commands - Get Started](https://jumpcloud.com/support/get-started-commands)
- [JumpCloud - Create a Command](https://jumpcloud.com/support/create-a-command-manually)
- [Codex Hooks](https://developers.openai.com/codex/hooks)
- [Codex Managed Configuration](https://developers.openai.com/codex/enterprise/managed-configuration)