Skip to content
Guides
/
/
Codex
Last updated

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 EventDescription
SessionStartSession initialization and context with MCP tools definitions
UserPromptSubmitUser prompts before submission to the model
PreToolUseTool execution requests (before execution)
PostToolUseTool execution results (after completion)
StopAgent 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:

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

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

Windows (PowerShell, as Administrator):

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

Codex's 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)
    [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:

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:

    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

Previous page
Next page