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

# Quickstart: Oso for Agents

> Route agent traffic through Oso to see what your AI agents are doing.

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 deploy Oso across all employee devices at once. See [Managed Deployment](https://www.osohq.com/docs/oso-for-agents/integrations/managed-deployment.md).

**Monitoring web-based agents**: Install the Oso browser extension to capture sessions from Claude.ai, ChatGPT, and Gemini. See [Browser Extension](https://www.osohq.com/docs/oso-for-agents/integrations/browser-extension.md).

***

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](https://ui.osohq.com) and log in.

> [!NOTE]
>
> If you are a new user, create an Oso for Agents tenant when prompted.

2. Click your organization name in the bottom-left corner and select **Organization settings**.

![Organization settings in the Oso UI](https://mintcdn.com/osoinc/B5X8MYTL97kWolPz/images/agents-quickstart/settings_panel.png?fit=max\&auto=format\&n=B5X8MYTL97kWolPz\&q=85\&s=62d443c6300bf100f0b62e0108c6a075)

3. In the settings panel, click the **Environments** tab.

![The settings panel](https://mintcdn.com/osoinc/bbSQ8UtDlX3QgKvC/images/agents-quickstart/organization_settings.png?fit=max\&auto=format\&n=bbSQ8UtDlX3QgKvC\&q=85\&s=63c2092457a35bfc702e9908c46c13dc)

4. Copy the **Environment ID** for your environment.

![The Environments page showing the Environment ID](https://mintcdn.com/osoinc/bbSQ8UtDlX3QgKvC/images/agents-quickstart/environment_page.png?fit=max\&auto=format\&n=bbSQ8UtDlX3QgKvC\&q=85\&s=2f5d2935c1c387eca78b1d719e2156c5)

## Step 2: Install and configure

Run the Oso installer in your terminal:

```sh theme={null}
curl -fsSL https://install.osohq.com/install.sh | sh
```

> [!NOTE]
>
> To install globally on the device, run with `sudo sh` instead:
>
> ```sh theme={null}
> 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.

```sh theme={null}
% curl -fsSL https://install.osohq.com/install.sh | sh
Downloading Oso installer...
Installing user-level configurations.

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

  Verifying environment... done

✔ Tools to configure (space to toggle, enter to confirm) · Claude Code, Cursor, Codex, Chrome, Claude Desktop Plugin, Safari
  Downloading oso-setup... done
  Downloading oso-hook... done

Configuring Claude Code...
Configuring Cursor...
Cursor hooks already configured, skipping.
Configuring Codex...
Codex configured to route through https://agents.osohq.cloud.
Configuring Chrome...
Chrome native messaging host installed.
Configuring Claude Desktop Plugin...

Claude Desktop plugin packaged at /Users/jordansinger/oso.plugin.

To install:
  1. Open Claude Desktop → Customize → Plugins
  2. Upload /Users/jordansinger/oso.plugin

Configuring Safari...

Installation complete!
```

### What the installer configures

The installer prompts you to select which tools to configure. By default all are selected.

| Tool | Config file |
| - | - |
| Claude Code | `~/.claude/settings.json` |
| Cursor | `~/.cursor/hooks.json` |
| Codex | `~/.codex/config.toml` |
| Chrome | `~/Library/Google/Chrome/NativeMessagingHosts/com.osohq.oso` |
| Github Copilot | `~/.copilot/hooks/oso.json` |

### Manual configuration

If you prefer to configure tools by hand, expand the sections below.

> [accordion] Claude Code
>
> Add the following `hooks` block to `~/.claude/settings.json`, replacing `<path-to-home>` with your home directory (e.g. `/home/yourname` or `/Users/yourname`):
>
> ```json theme={null}
> {
>   "hooks": {
>     "UserPromptSubmit":   [{"matcher": "", "hooks": [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook", "timeout": 5}]}],
>     "PreToolUse":         [{"matcher": "", "hooks": [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook", "timeout": 5}]}],
>     "PostToolUse":        [{"matcher": "", "hooks": [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook", "timeout": 5}]}],
>     "PostToolUseFailure": [{"matcher": "", "hooks": [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook", "timeout": 5}]}],
>     "Stop":               [{"matcher": "", "hooks": [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook", "timeout": 5}]}],
>     "SubagentStop":       [{"matcher": "", "hooks": [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook", "timeout": 5}]}]
>   }
> }
> ```
>
> > [!NOTE]
> >
> > If you previously routed Claude Code through the Oso proxy with `ANTHROPIC_BASE_URL`, remove it from your `settings.json` `env` block. Hooks capture the same activity, and keeping both produces duplicate events.

> [accordion] Codex
>
> Create a model provider configuration in `~/.codex/config.toml`:
>
> ```toml theme={null}
> 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.
>
> > [!NOTE]
> >
> > If you have `OPENAI_BASE_URL` set as an environment variable, unset it so the model provider configuration takes effect.

> [accordion] GitHub Copilot
>
> Create `~/.copilot/hooks/oso.json` with the following content, replacing `<path-to-home>` with your home directory (e.g. `/home/yourname` or `/Users/yourname`):
>
> ```json theme={null}
> {
>   "hooks": {
>     "UserPromptSubmit": [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook --agent github-copilot", "timeout": 5}],
>     "PreToolUse":       [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook --agent github-copilot", "timeout": 5}],
>     "PostToolUse":      [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook --agent github-copilot", "timeout": 5}],
>     "PostToolUseFailure": [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook --agent github-copilot", "timeout": 5}],
>     "Stop":             [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook --agent github-copilot", "timeout": 5}],
>     "SubagentStop":     [{"type": "command", "command": "<path-to-home>/.local/bin/oso-hook --agent github-copilot", "timeout": 5}]
>   }
> }
> ```
>
> > [!NOTE]
> >
> > GitHub Copilot hooks can only be installed at the user level. There is no global configuration directory for Copilot, so root/system-wide installation is not supported.

## Step 3: Monitor agent activity in the Oso dashboard

Use your coding agents as normal. Activity will appear in your [Oso for Agents dashboard](https://ui.osohq.com).

## Uninstalling

Run `oso-setup uninstall` the same way you installed - without `sudo` for a user install,
or with `sudo` if you ran the installer as root.

```sh theme={null}
# User install
~/.local/bin/oso-setup uninstall

# Global install (if you ran with sudo)
sudo /usr/local/bin/oso-setup uninstall
```

For shared config files (Claude Code, Cursor, Codex), only Oso's own entries are removed,
while your other settings are left intact. Files that Oso owns outright (Chrome and Firefox
native-messaging manifests, the GitHub Copilot hook, the Claude Desktop plugin, etc.) are removed
entirely. The uninstaller also removes your identity file, debug logs, and the `oso-hook`
and `oso-setup` binaries. It's safe to run more than once.

For the Claude Desktop Plugin, you must separately remove it through
**Claude Desktop → Customize → Plugins**.

Pass `--keep-logs` to retain oso-hook debug logs:

```sh theme={null}
~/.local/bin/oso-setup uninstall --keep-logs
# or
sudo /usr/local/bin/oso-setup uninstall --keep-logs
```

### Next steps

* **[Shadow AI](https://www.osohq.com/docs/oso-for-agents/shadow-ai.md)**: Discover what AI agents are in use across your organization.
* **[Session Monitoring](https://www.osohq.com/docs/oso-for-agents/session-monitoring.md)**: See what agents are doing inside their sessions.
* **[Alerts](https://www.osohq.com/docs/oso-for-agents/alerts.md)**: Set up monitoring for unsanctioned usage and sensitive content.
* **[Managed Deployment](https://www.osohq.com/docs/oso-for-agents/integrations/managed-deployment.md)**: Deploy Oso across your organization via MDM or IT policy.
* **[Other integrations](https://www.osohq.com/docs/oso-for-agents/integrations/edge-proxy.md)**: Network-level and endpoint-based discovery via EDR or Tailscale Aperture.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.