Codex Integration

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

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 - 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:

Before you begin, ensure you have:

• Codex CLI installed
• A Capsule Security account with admin access
• A device management tool (Jamf, Intune, Kandji, ...) to deploy files to your fleet

1. Log in to the Capsule Security portal

2. Navigate to Settings > Integrations and locate Codex

3. In the wizard, select your platform to download the managed configuration. Capsule generates it for you, including an embedded authentication token scoped to your organization:

   • Mac / Linux: a single requirements.toml file
   • Windows: a capsule-codex-managed.zip archive containing requirements.toml and the CapsuleCodexHook.ps1 companion script

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

2. 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
• Jamf Pro
• Kandji
• JumpCloud
• Microsoft SCCM
• ManageEngine Endpoint Central
• Tanium

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

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

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

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)

For help with this integration:

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

• Codex Hooks Documentation
• Codex Managed Configuration