# Codex Integration

Connect OpenAI Codex to Capsule Security for complete visibility into AI coding assistant activity, including prompts, tool execution, and session lifecycle.

## Overview

This integration uses Codex's hooks system to capture AI coding assistant activity. Hooks are shell commands that execute at specific points in Codex's lifecycle, providing automated workflows and audit capabilities.

The following hooks are configured:

| Hook Event | Description |
|  --- | --- |
| **SessionStart** | Session initialization and context with MCP tools definitions |
| **UserPromptSubmit** | User prompts before submission to the model |
| **PreToolUse** | Tool execution requests (before execution) |
| **PostToolUse** | Tool execution results (after completion) |
| **Stop** | Agent stop events when the agent finished responding |


## Prerequisites

Before you begin, ensure you have:

- **Codex CLI** installed
- A **Capsule Security** account with admin access


## Step 1: Generate the Configuration

1. Log in to the **Capsule Security** portal
2. Navigate to **Integrations** and locate **Codex**
3. Click **Install** — Capsule automatically generates a `hooks.json` file containing:
  - Hook commands for all lifecycle events
  - An embedded authentication token scoped to your organization
4. Select your target platform to download the configuration:
  - **Mac** / **Linux**: a single `hooks.json` file
  - **Windows**: a `capsule-codex-hooks.zip` archive containing `hooks.json` and a `CapsuleCodexHook.ps1` companion script


> On Windows, `hooks.json` invokes `CapsuleCodexHook.ps1` at the path configured in the integration's **Advanced Settings** (default `C:\Program Files\Capsule\CapsuleCodexHook.ps1`), so both files must be deployed. The platform downloads are not interchangeable — use each platform's own `hooks.json`.


## Step 2: Deploy the Configuration

### Configuration Locations

Codex loads hooks from the following locations. Where you place the configuration determines who controls it and how much users can tamper with it:

| Location | Path | Best for |
|  --- | --- | --- |
| **User** | `~/.codex/hooks.json` (macOS/Linux)`%USERPROFILE%\.codex\hooks.json` (Windows) | POVs, pilots, and quick tests |
| **Managed (enterprise)** | Managed hooks directory declared in `requirements.toml` at `/etc/codex/requirements.toml` (macOS/Linux) or `%ProgramData%\OpenAI\Codex\requirements.toml` (Windows) | Production fleets |


User-space configuration is the fastest way to evaluate the integration — a single file copy with no infrastructure. For production, prefer the managed/enterprise location: user-space hooks can be edited or deleted by the user, and Codex [skips non-managed hooks](https://developers.openai.com/codex/hooks) until each user reviews and trusts them via `/hooks`, while managed hooks are trusted by policy and cannot be disabled from the user hook browser.

### User-Level Install (POVs and Quick Tests)

**macOS / Linux:**


```bash
mkdir -p ~/.codex
cp hooks.json ~/.codex/hooks.json
```

**Windows (PowerShell, as Administrator):**


```powershell
New-Item -ItemType Directory -Path "$env:USERPROFILE\.codex" -Force | Out-Null
Copy-Item -Path "hooks.json" -Destination "$env:USERPROFILE\.codex\hooks.json" -Force
New-Item -ItemType Directory -Path "C:\Program Files\Capsule" -Force | Out-Null
Copy-Item -Path "CapsuleCodexHook.ps1" -Destination "C:\Program Files\Capsule\CapsuleCodexHook.ps1" -Force
```

Because user-level hooks are non-managed, each user must review and trust them once via `/hooks` (see Step 4), and trust must be re-granted whenever the configuration changes (for example, a rotated token).

### Managed Configuration (Recommended for Production)

Codex's [managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) lets administrators enforce the Capsule hooks fleet-wide:

1. Use your device management solution to install the Capsule hook configuration into a dedicated directory on each endpoint (Codex does not distribute hook scripts — your MDM delivers the files)
2. Deploy a `requirements.toml` that points Codex at that directory:
  - **macOS / Linux**: `/etc/codex/requirements.toml`
  - **Windows**: `%ProgramData%\OpenAI\Codex\requirements.toml`
  - **macOS via MDM**: a configuration profile in the `com.openai.codex` preference domain (`requirements_toml_base64`)

```toml
[hooks]
managed_dir = "/path/to/managed/hooks"   # macOS/Linux (must exist; absolute path)
windows_managed_dir = 'C:\path\to\managed\hooks'
allow_managed_hooks_only = true
```
3. With `allow_managed_hooks_only = true`, user and project hooks are blocked entirely — only administrator-approved hooks run, and users cannot disable or circumvent the Capsule integration


Hooks from managed sources are trusted by policy: no per-user `/hooks` review is required.

### MDM Distribution to User Paths

If your organization is not ready for managed configuration, you can still automate deployment at scale by having your MDM write the configuration into each user profile. See the platform guides:

- [Microsoft Intune](/guides/mdm-intune) (supports fully automated deployment from the Capsule portal)
- [Jamf Pro](/guides/mdm-jamf)
- [Kandji](/guides/mdm-kandji)
- [JumpCloud](/guides/mdm-jumpcloud)
- [Microsoft SCCM](/guides/mdm-sccm)
- [ManageEngine Endpoint Central](/guides/mdm-manageengine)
- [Tanium](/guides/mdm-tanium)


Note that hooks deployed this way are still user-level (non-managed), so each user must trust them via `/hooks`.

## Step 3: Restart Codex

Hooks are loaded at session start. Exit any running Codex sessions and start a new one for the configuration to take effect.

## Step 4: Verify the Installation

1. Start a new Codex CLI session
2. If Codex warns that hooks require review, run `/hooks`, review the Capsule hooks, and trust them (not required for managed hooks)
3. Execute a simple task to generate activity:

```
Create a new file called test.txt with the content "Hello World"
```
4. Log in to the **Capsule Security** portal
5. Navigate to **Inventory > Agents** and confirm your Codex agent appears
6. Click on the agent and review the audit logs to verify events are captured:
  - Session start event
  - User prompt
  - Tool execution
  - Session activity


### Troubleshooting

If events are not appearing:

1. **Verify `hooks.json` is in the correct location** for your platform (see Step 2) — if the `CODEX_HOME` environment variable is set, Codex reads the configuration from there instead of `~/.codex`
2. **Run `/hooks` in Codex** — if the Capsule hooks are listed but skipped, they have not been trusted yet; if nothing is listed, the file is not being loaded
3. **Verify the file syntax** — ensure the file contains valid JSON:

```bash
cat ~/.codex/hooks.json | python3 -m json.tool
```
4. **Windows: verify the script path** — the path inside `hooks.json` must match where `CapsuleCodexHook.ps1` was actually installed (see the integration's **Advanced Settings**)
5. **Check that hooks are not disabled by policy** — a `requirements.toml` with `[features] hooks = false` turns the hooks feature off entirely
6. **Contact Capsule Security support** if issues persist


## Security Considerations

Codex hooks execute with your current environment credentials. Before deploying hooks:

1. **Review all hook scripts** provided by Capsule Security
2. **Verify the endpoint URL** matches your organization's Capsule instance
3. **Protect authentication tokens** used by hooks (never commit `hooks.json` to version control)
4. Codex records hook trust against a hash of the hook definition — any modification to the deployed configuration revokes trust and requires re-approval, which protects users from silent tampering


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your organization ID, integration status, and any error messages


## References

- [Codex Hooks Documentation](https://developers.openai.com/codex/hooks)
- [Codex Managed Configuration](https://developers.openai.com/codex/enterprise/managed-configuration)