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.

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 | sudo 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. 
% curl -fsSL https://install.osohq.com/install.sh | sh
Downloading Oso installer...

✔ Oso environment ID · e_...
✔ Email address · you@example.com

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.