Skip to main content
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)
  • 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 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 runs silently on each device and does two things: it configures your coding agents (Claude Code, Cursor, Codex) to route traffic through Oso for session monitoring, and it registers the device and user with Oso for identity correlation. 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. 
#!/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 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>
Chrome enterprise management requirementChrome (v119+) blocks force-installation of extensions not hosted on the Chrome Web Store unless it detects the device as enterprise managed. Devices enrolled in Rippling MDM via user-approved enrollment do not satisfy this requirement. Chrome requires either DEP/ADE supervision through Apple Business Manager or Chrome Browser Cloud Management (CBCM) enrollment.If chrome://policy shows [BLOCKED] next to the extension entry, enroll Chrome in CBCM:
  1. In the Google Admin Console, go to Devices → Chrome → Connectors → Browser Cloud Management enrollment tokens.
  2. Click Add enrollment token, give it a name, and copy the generated token.
  3. Add the following key to the mcx_preference_settings dict in chrome.mobileconfig, alongside ExtensionInstallForcelist:
<key>CloudManagementEnrollmentToken</key>
<string>YOUR_CBCM_TOKEN</string>
  1. Redeploy the updated profile via Rippling.
  2. Fully quit and relaunch Chrome on the device (⌘Q, then reopen).
After enrollment, chrome://management will show browser management and chrome://policy will show the extension installing without [BLOCKED].

​
Verifying deployment

After devices enroll, confirm the installation succeeded: 
# 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