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

# Rippling

> Deploy Oso to macOS devices via Rippling MDM.

This page walks through deploying Oso to your organization's macOS devices using Rippling.

* Oso environment ID (find it in **Settings → Environments** in the [Oso dashboard](https://ui.osohq.com))
* Admin access to Rippling IT
* macOS devices enrolled in Rippling MDM

## Step 1: Deploy the configuration profile

The configuration profile writes your Oso environment settings to each device's managed preferences, so the installer and hook can read them without user interaction.

**Prepare the profile:**

Copy the profile below, replace `YOUR_ENVIRONMENT_ID` with your Oso environment ID, and save it as `oso.mobileconfig`.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadIdentifier</key>
            <string>com.osohq.oso.settings.rippling</string>
            <key>PayloadUUID</key>
            <string>7FE3B1A0-9D24-4C8F-B6E1-A0D7E5C42911</string>
            <key>PayloadDisplayName</key>
            <string>Oso Settings</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadContent</key>
            <dict>
                <key>com.osohq.oso</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <key>OSO_ENVIRONMENT</key>
                                <string>YOUR_ENVIRONMENT_ID</string>
                                <key>OSO_PROXY_URL</key>
                                <string>https://agents.osohq.cloud</string>
                                <key>OSO_API_URL</key>
                                <string>https://cloud.osohq.com</string>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configures Oso environment settings for oso-hook and the local proxy.</string>
    <key>PayloadDisplayName</key>
    <string>Oso</string>
    <key>PayloadIdentifier</key>
    <string>com.osohq.oso.profile.rippling</string>
    <key>PayloadOrganization</key>
    <string>Oso Security, Inc.</string>
    <key>PayloadRemovalDisallowed</key>
    <false/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>7FE3B1A0-9D24-4C8F-B6E1-A0D7E5C42910</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>
```

**Upload to Rippling:**

1. Go to **IT → Devices → Policies → macOS** and click **Upload**.
2. Fill in the details:
   * **Name**: `Oso`
   * **Description**: `Configures Oso for AI traffic monitoring`
   * **Platform**: macOS
   * Attach the edited `oso.mobileconfig`
3. Select the devices you want to deploy to.
4. Click **Save & continue**.

## Step 2: Deploy the install script

The install script downloads the Oso binaries and configures tools. It reads `OSO_ENVIRONMENT` from the plist written in Step 1, and resolves the user's email from the Rippling agent JSON on each device.

Copy the script below.

```bash theme={null}
#!/bin/bash
# Oso Rippling Install Script
#
# Downloads and installs Oso non-interactively. Reads OSO_ENVIRONMENT from the
# managed plist written by oso.mobileconfig, and resolves the user email from
# role_name in the Rippling agent JSON, falling back to the device serial number.

set -euo pipefail

PLIST="/Library/Managed Preferences/com.osohq.oso.plist"
RIPPLING_AGENT="/Library/Application Support/Rippling/pangolin_agent.json"

OSO_ENVIRONMENT=$(defaults read "$PLIST" OSO_ENVIRONMENT 2>/dev/null || true)
if [[ -z "$OSO_ENVIRONMENT" ]]; then
    echo "ERROR: OSO_ENVIRONMENT not set. Deploy oso.mobileconfig first." >&2
    exit 1
fi

USER_EMAIL=""
if [[ -f "$RIPPLING_AGENT" ]]; then
    USER_EMAIL=$(plutil -extract role_name raw "$RIPPLING_AGENT" 2>/dev/null || true)
fi
if [[ -z "$USER_EMAIL" ]] && [[ -f "$RIPPLING_AGENT" ]]; then
    USER_EMAIL=$(plutil -extract serial raw "$RIPPLING_AGENT" 2>/dev/null || true)
fi
if [[ -z "$USER_EMAIL" ]]; then
    echo "ERROR: Could not resolve user email from Rippling agent JSON." >&2
    exit 1
fi

echo "Installing Oso for $USER_EMAIL (env: $OSO_ENVIRONMENT)..."

curl -fsSL https://install.osohq.com/install.sh | sh -s -- \
    --env "$OSO_ENVIRONMENT" \
    --email "$USER_EMAIL" \
    --force

echo "Oso installation complete."
```

1. Go to **IT → Devices → Scripts** and click **Upload Script**.
2. Paste the script above, set the name to `Oso Install`, set the frequency to **Once** (or **Recurring** to keep configurations up to date), and choose your target devices.
3. Click **Save**.

The script reads user email from `role_name` in `/Library/Application Support/Rippling/pangolin_agent.json`, falling back to the device serial number if `role_name` is not present.

## Step 3: (Optional) Deploy the Chrome extension profile

To force-install the Oso Chrome extension, copy the profile below, replace `YOUR_ENVIRONMENT_ID` with your Oso environment ID, and save it as `chrome.mobileconfig`. Then upload and deploy it following the same steps as Step 1.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadIdentifier</key>
            <string>com.osohq.oso.chrome.rippling</string>
            <key>PayloadUUID</key>
            <string>7FE3B1A0-9D24-4C8F-B6E1-A0D7E5C42921</string>
            <key>PayloadDisplayName</key>
            <string>Oso Chrome Policy</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadContent</key>
            <dict>
                <key>com.google.Chrome</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <key>ExtensionInstallForcelist</key>
                                <array>
                                    <string>nochaaflecnmeafkagnbiabpgahpledi;https://install.osohq.com/extension/chrome/update_manifest.xml</string>
                                </array>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadIdentifier</key>
            <string>com.osohq.oso.chrome.extension.rippling</string>
            <key>PayloadUUID</key>
            <string>7FE3B1A0-9D24-4C8F-B6E1-A0D7E5C42922</string>
            <key>PayloadDisplayName</key>
            <string>Oso Chrome Extension Managed Storage</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadContent</key>
            <dict>
                <key>com.google.Chrome.extensions.nochaaflecnmeafkagnbiabpgahpledi</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <key>environmentId</key>
                                <string>YOUR_ENVIRONMENT_ID</string>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Force-installs the Oso Chrome extension and configures its environment ID.</string>
    <key>PayloadDisplayName</key>
    <string>Oso Chrome Extension</string>
    <key>PayloadIdentifier</key>
    <string>com.osohq.oso.chrome.profile.rippling</string>
    <key>PayloadOrganization</key>
    <string>Oso Security, Inc.</string>
    <key>PayloadRemovalDisallowed</key>
    <false/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>7FE3B1A0-9D24-4C8F-B6E1-A0D7E5C42920</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>
```

## Verifying deployment

After devices enroll, confirm the installation succeeded:

```bash theme={null}
# Managed preferences written by the configuration profile
defaults read "/Library/Managed Preferences/com.osohq.oso"

# Tool configs written by the installer (system-level)
cat "/Library/Application Support/ClaudeCode/managed-settings.json"
cat "/Library/Application Support/Cursor/hooks.json"
cat "/etc/codex/managed_config.toml"

# Identity registered with Oso
cat "/Library/Application Support/Oso/identity.json"

# Binaries installed
ls -la /usr/local/bin/oso-hook /usr/local/bin/oso-setup
```