For the complete documentation index, see llms.txt. This page is also available as Markdown.

Codex CLI Hooks

Akto Guardrails for Codex provides comprehensive security monitoring and validation for both chat interactions and tool executions — and works with both Codex CLI and Codex Desktop. It intercepts prompts before sending to Codex, validates tool calls before execution, blocks risky behavior, and reports all events to your Akto dashboard.

Key Features

  • Zero Installation - No standalone apps to install

  • Transparent Integration - Uses Codex's native hook mechanism (CLI and Desktop)

  • Real-time Protection - Validates every prompt and tool call

  • Centralized Monitoring - All events reported to Akto dashboard

  • Flexible Deployment - Supports Argus and Atlas modes

  • Configurable Behavior - Blocking or observation modes

  • Auto-detected API Host - Automatically resolves Codex API endpoint from environment

How It Works

Codex's hook system (shared by both CLI and Desktop) executes custom scripts at four critical points:

4 Hook Points:

  1. UserPromptSubmit - Validates prompts before sending to Codex API

  2. Stop - Ingests prompt/response pair when Codex finishes generating

  3. PreToolUse - Validates tool requests before execution (blocks if malicious)

  4. PostToolUse - Ingests tool input/output after execution (observational only)

Note: Codex currently only supports the Bash tool for PreToolUse and PostToolUse hooks (both CLI and Desktop).

File Structure

Key Files:

  • Wrapper scripts (.sh): Set environment variables, invoke Python scripts

    • ⚠️ Contains AKTO_DATA_INGESTION_URL placeholder - Must be replaced with your Akto instance URL

  • Python scripts (.py): Core validation and ingestion logic, Akto API communication

  • akto_ingestion_utility.py: Shared validation/ingestion logic imported by every hook script — lives in a different GitHub directory (shared/, not codex-cli-hooks/), so it needs its own download step

  • akto_machine_id.py: Generates unique device identifiers for Atlas mode

  • hooks.json: Links hooks to wrapper scripts

  • config.toml: Must enable the codex_hooks feature flag

Setup Guide

Prerequisites

  • Codex CLI or Codex Desktop installed

  • Akto instance URL

  • Python 3.7+

  • macOS, Linux, or Windows with bash/zsh

Enabling Local Hooks in Managed Environments

This section is only relevant if your machine is managed by an organization (MDM, ChatGPT Business/Enterprise). If you're on a personal or unmanaged device, skip ahead to Installation Steps.

In managed environments, organizational policies may override local Codex hook configuration. This section helps administrators identify and resolve restrictions so that local hooks can execute.

Configuration Precedence

Codex evaluates configuration sources in this order — higher-precedence sources win:

  1. Cloud-managed requirements (ChatGPT Business / Enterprise)

  2. macOS managed preferences (MDM)

  3. Local user configuration (~/.codex/config.toml)

  4. Other defaults

Scenario 1: Cloud-Managed Requirements

Organization administrators should review settings in the ChatGPT administration environment under:

  • Codex Settings → Managed Requirements

  • Policies → Developer Tools Settings

  • Hooks Restrictions / Managed Hooks Configuration

Look for settings that disable hooks globally or restrict execution to organization-managed hooks only:

To allow local hooks, ensure:

Or remove the restriction entirely.

Scenario 2: macOS Managed Preferences (MDM)

MDM-managed Codex configuration is delivered through the preference domain com.openai.codex via platforms such as Jamf Pro, Kandji, Microsoft Intune, Mosyle, or VMware Workspace ONE.

Check current managed configuration on the device:

Locate the requirements_toml_base64 field, decode it, and inspect for restrictions such as:

To allow local hooks, update the MDM profile so that:

Or remove the managed hook restriction entirely. After updating:

  1. Save the configuration.

  2. Push the updated profile to managed devices.

  3. Restart Codex.

  4. Verify hook discovery and execution.

How an Administrator Can Change Codex MDM Configuration

Administrators should modify the source profile in the MDM console rather than editing files on individual devices. The settings visible on a Mac under defaults read /Library/Managed\ Preferences/com.openai.codex are generated from that profile.

Jamf Pro
  1. Log in to Jamf Pro.

  2. Navigate to ComputersConfiguration Profiles.

  3. Locate the profile managing com.openai.codex.

  4. Open the profile and review Application & Custom SettingsCustom Schema / Property List payloads.

  5. Find the key com.openai.codex and inspect requirements_toml_base64.

  6. Decode and modify the TOML configuration as required.

  7. Save the profile and redeploy or wait for device check-in.

Kandji
  1. Open Kandji Admin Portal.

  2. Navigate to LibraryCustom Profiles.

  3. Locate the profile containing com.openai.codex.

  4. Review the payload and modify the requirements_toml_base64 value.

  5. Save and assign the updated profile.

  6. Force a device sync if required.

Microsoft Intune
  1. Open Intune Admin Center.

  2. Navigate to DevicesConfiguration Profiles.

  3. Locate the profile managing Codex and open Custom Settings.

  4. Review the preference domain com.openai.codex.

  5. Update the managed configuration, save, and assign the profile.

  6. Sync target devices.

Mosyle
  1. Open Mosyle Dashboard.

  2. Navigate to ManagementProfiles.

  3. Locate the profile containing com.openai.codex.

  4. Modify the payload, save changes, and push the updated profile.

What settings to change

Inspect the decoded TOML for any hook restrictions, for example:

To permit user-defined local hooks, update or remove the restricting settings:

Validation after deployment

On a managed Mac, confirm the updated configuration is present:

Then restart Codex, ensure local hook files exist under ~/.codex/hooks/ or ~/.codex/hooks.json, and verify hook discovery through Codex logs.

Local User Configuration

Once organizational restrictions are removed, users enable hooks locally:

Hook files can then be placed in ~/.codex/hooks/ or ~/.codex/hooks.json.

Validation

After enabling local hooks:

  1. Restart Codex.

  2. Execute an action that should trigger a hook.

  3. Verify logs show events such as:

If hooks are not discovered, re-check cloud-managed requirements and MDM-managed preferences, as they take precedence over local configuration.

Installation Steps

1

Enable Codex Hooks Feature Flag

Codex hooks are experimental. Enable them in ~/.codex/config.toml (used by both CLI and Desktop):

2

Create Directories

3

Download Hook Scripts

akto_ingestion_utility.py must land in the same directory as the hook scripts — they import it as a plain top-level module, resolved from the script's own directory. Skipping this download makes every hook fail with ModuleNotFoundError: No module named 'akto_ingestion_utility'.

4

Configure Akto Ingestion URL and API Token ⚠️ CRITICAL STEP

Automated replacement:

Manual replacement (alternative):

Edit each wrapper script and replace:

With:

Files to update:

  • akto-validate-prompt-wrapper.sh

  • akto-validate-response-wrapper.sh

  • akto-validate-pre-tool-wrapper.sh

  • akto-validate-post-tool-wrapper.sh

5

Configure Hooks

Copy hooks.json to ~/.codex/hooks.json:

Note: You can also place hooks.json at <repo>/.codex/hooks.json for repository-level hooks.

6

Configure Hook Behavior (Optional)

Edit wrapper scripts to customize:

Mode Options:

  • Argus: Standard validation and reporting

  • Atlas: Includes device-specific metadata

Sync Mode:

  • true: Blocks threats (prompt validation + tool validation)

  • false: Reports but allows execution

7

Verify Installation

Check logs to confirm hooks are working:

Test by running a Codex command:

  • CLI: codex "What is 2+2?"

  • Desktop: Open Codex Desktop and send a message in the chat

You should see log entries indicating validation occurred.

Configuration Reference

Wrapper Script Variables
Environment Variables (Optional)

Override defaults via environment variables in ~/.zshrc or ~/.bashrc:

Then reload your shell:

Codex API Host Auto-Detection

The Codex API host and path are automatically resolved from the same environment variables Codex CLI uses:

Scenario
Host
Path

OPENAI_BASE_URL set

value of OPENAI_BASE_URL

/v1/responses

OPENAI_API_KEY set

api.openai.com

/v1/responses

ChatGPT browser login

chatgpt.com

/backend-api/codex/responses

Hook Input Fields

All hooks receive a common JSON payload on stdin, plus event-specific fields:

Event
Additional Fields

UserPromptSubmit

prompt

Stop

last_assistant_message, stop_hook_active

PreToolUse

tool_name, tool_use_id, tool_input

PostToolUse

tool_name, tool_use_id, tool_input, tool_response

Troubleshooting

ModuleNotFoundError: No module named 'akto_ingestion_utility'

The shared ingestion utility was not downloaded, or landed outside ~/.codex/hooks/. It lives in the shared/ directory on GitHub, not under HOOKS_BASE, so it needs its own curl.

If the file is present and the import still fails, check that PYTHONSAFEPATH is unset — it suppresses the script-directory entry on sys.path that this import relies on.

Hooks Not Executing
Ingestion URL Not Configured
Check Logs for Errors
Events Not in Dashboard
Service Unavailable

If Akto is unreachable:

  • With AKTO_SYNC_MODE=true: hooks fail open and allow execution (fail-safe)

  • With AKTO_SYNC_MODE=false: hooks skip ingestion silently

Uninstallation

To completely remove Akto hooks from Codex CLI or Codex Desktop:

Complete Removal
Selective Removal (Keep Logs)
Backup Before Removal
Verify Removal
Restore Codex to Default

After uninstallation, Codex CLI and Codex Desktop will operate without Akto security monitoring. Test with:

  • CLI: codex "Test message"

  • Desktop: Open Codex Desktop and send a message — no hook logs should appear

Enterprise Deployment

Automated Deployment Script

deploy-codex-cli-hooks.sh

Deploy to developers:

Resources

Last updated