# 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 integration is delivered through Codex's [managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) - a `requirements.toml` that registers the Capsule hooks. Because the configuration is managed, the hooks are trusted by policy, apply to every user, and cannot be disabled or removed by users. No per-user trust approval is required.

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
- For the **Cloud** deployment method: admin access to your organization's **ChatGPT admin console**


## Step 1: Choose a Deployment Method

1. Log in to the **Capsule Security** portal
2. Navigate to **Settings > Integrations** and locate **Codex**
3. The setup wizard offers two deployment methods - Capsule generates the managed configuration for you, including an embedded authentication token scoped to your organization:


| Method | How it works | Best for |
|  --- | --- | --- |
| **Cloud (Managed Configuration)** (recommended) | Enforce the Capsule hooks org-wide through ChatGPT's Managed configuration - no files on devices | Organizations on ChatGPT plans with managed configuration |
| **MDM / Managed Deploy** | Download `requirements.toml` and deploy it to managed devices via your MDM (Jamf, Intune, Kandji, …) | Device-managed fleets |


## Step 2: Deploy the Configuration

### Cloud (Managed Configuration)

1. In the wizard, choose **Cloud** and copy the managed configuration TOML
2. In the **ChatGPT admin console**, go to **Settings → Managed configuration** and create or assign a policy with this configuration
3. Confirm the policy is assigned to your organization or group
4. For Windows fleets, download `CapsuleCodexHook.ps1` from the wizard and distribute it to `C:\ProgramData\Capsule\CodexHooks\` - the managed configuration invokes the script from that directory (macOS and Linux hook commands are self-contained and need no companion files)


Codex applies the managed configuration the next time a session starts.

### MDM / Managed Deploy

1. In the wizard, choose **MDM** and select your platform to download the managed configuration:
  - **Mac** / **Linux**: a single `requirements.toml` file
  - **Windows**: a `capsule-codex-managed.zip` archive containing `requirements.toml` and the `CapsuleCodexHook.ps1` companion script
2. Deploy the files to the following locations via your MDM:
| Platform | `requirements.toml` | Companion script |
|  --- | --- | --- |
| macOS / Linux | `/etc/codex/requirements.toml` | Not required |
| Windows | `%ProgramData%\OpenAI\Codex\requirements.toml` | `C:\ProgramData\Capsule\CodexHooks\CapsuleCodexHook.ps1` |
3. On macOS, the configuration can alternatively be delivered as an MDM configuration profile in the `com.openai.codex` preference domain, with the file's content base64-encoded into the `requirements_toml_base64` key


See the platform guides for step-by-step MDM instructions:

- [Microsoft Intune](/guides/mdm-intune)
- [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)


## Step 3: Restart Codex

The managed configuration is 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. Execute a simple task to generate activity:

```
Create a new file called test.txt with the content "Hello World"
```
3. Log in to the **Capsule Security** portal
4. Navigate to **Inventory > Agents** and confirm your Codex agent appears
5. 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 `requirements.toml` is in the correct location** for your platform (see Step 2), and that its content was deployed intact
2. **Run `/hooks` in Codex** - the Capsule hooks should be listed as managed; if nothing is listed, the configuration is not being loaded
3. **Windows: verify the companion script** - `CapsuleCodexHook.ps1` must exist at `C:\ProgramData\Capsule\CodexHooks\`, where the managed configuration invokes it
4. **Check for conflicting managed configuration sources** - Codex resolves managed configuration in precedence order (macOS MDM preference-domain profiles override the `/etc/codex/requirements.toml` file), so another policy may be taking precedence or disabling hooks
5. **Contact Capsule Security support** if issues persist


## Security Considerations

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

1. **Review all hook commands** in the generated configuration
2. **Verify the endpoint URL** matches your organization's Capsule instance
3. **Protect authentication tokens** embedded in the configuration (never commit `requirements.toml` to version control)


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