Skip to main content

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.

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

​
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