Skip to main content
There are a few ways to get started with Oso depending on your situation. Setting up for yourself: Run the installer on your machine. It configures your coding agents and registers your device in a few minutes. Follow the steps below. Deploying across your organization: Use your MDM to push the Oso agent to all employee devices at once. See Managed Deployment. Monitoring web-based agents: Install the Oso browser extension to capture sessions from Claude.ai, ChatGPT, and Gemini. See Browser Extension.
Get started with Oso by running the installer. It configures your coding agents to route traffic through Oso and registers your device. You will:
  1. Get your Environment ID.
  2. Run the Oso installer to configure your tools and register your device.
  3. See agent activity in your Oso for Agents dashboard.

​
Step 1: Get your Environment ID

  1. Go to ui.osohq.com and log in.
If you are a new user, create an Oso for Agents tenant when prompted.
  1. Click your organization name in the bottom-left corner and select Organization settings.
Organization settings in the Oso UI
  1. In the settings panel, click the Environments tab.
The settings panel
  1. Copy the Environment ID for your environment.
The Environments page showing the Environment ID

​
Step 2: Install and configure

Run the Oso installer in your terminal: 
curl -fsSL https://install.osohq.com/install.sh | sh
To install globally on the device, run with sudo sh instead:
curl -fsSL https://install.osohq.com/install.sh  -o /tmp/install.sh && sudo sh /tmp/install.sh
The installer will prompt you for your Environment ID (from Step 1) and your email address, then automatically configure your tools and register your device with Oso. It also prompts for a device registration key — leave this blank, since Oso Cloud doesn’t require one. 
% curl -fsSL https://install.osohq.com/install.sh | sh
Downloading Oso installer...

✔ Oso environment ID · e_...
✔ Email address · you@example.com
✔ Device registration key (leave blank for Oso Cloud) ·

Verifying environment... done

✔ Tools to configure · Claude Code, Cursor, Codex
  Downloading oso-setup... done
  Downloading oso-hook... done

Configuring Claude Code...
Claude Code configured to route through https://agents.osohq.cloud.
Configuring Cursor...
Cursor hooks installed.
Configuring Codex...
Codex configured to route through https://agents.osohq.cloud.
oso-setup: configuration complete (env: e_...)

Installation complete!

​
What the installer configures

The installer prompts you to select which tools to configure. By default all are selected.
ToolConfig file
Claude Code~/.claude/settings.json
Cursor~/.cursor/hooks.json
Codex~/.codex/config.toml

​
Manual configuration

If you prefer to configure tools by hand, expand the sections below.
Add the following to ~/.claude/settings.json:
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://agents.osohq.cloud",
    "ANTHROPIC_CUSTOM_HEADERS": "OSO_ENVIRONMENT: <your-environment-id>\nX-Identity: |<your-email>"
  }
}
Replace <your-environment-id> with the Environment ID from Step 1. Enter your email into the X-Identity header to allow Oso to correlate sessions with a specific user.
Create a model provider configuration in ~/.codex/config.toml:
model = "gpt-5.4"
model_provider = "oso"

[model_providers.oso]
name = "Oso"
base_url = "https://agents.osohq.cloud"
requires_openai_auth = true

[model_providers.oso.http_headers]
OSO_ENVIRONMENT = "<your-environment-id>"
X-Identity = "|<your-email>"
Replace <your-environment-id> with the Environment ID from Step 1. Enter your email into the X-Identity header to allow Oso to correlate sessions with a specific user.
If you have OPENAI_BASE_URL set as an environment variable, unset it so the model provider configuration takes effect.

​
Step 3: Monitor agent activity in the Oso dashboard

Use your coding agents as normal. Activity will appear in your Oso for Agents dashboard.

​
Next steps

  • Shadow AI: Discover what AI agents are in use across your organization.
  • Session Monitoring: See what agents are doing inside their sessions.
  • Alerts: Set up monitoring for unsanctioned usage and sensitive content.
  • Managed Deployment: Deploy Oso across your organization via MDM or IT policy.
  • Other integrations: Network-level and endpoint-based discovery via EDR or Tailscale Aperture.