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:
UserPromptSubmit- Validates prompts before sending to Codex APIStop- Ingests prompt/response pair when Codex finishes generatingPreToolUse- Validates tool requests before execution (blocks if malicious)PostToolUse- Ingests tool input/output after execution (observational only)
Note: Codex currently only supports the
Bashtool forPreToolUseandPostToolUsehooks (both CLI and Desktop).
File Structure
Key Files:
Wrapper scripts (
.sh): Set environment variables, invoke Python scripts⚠️ Contains
AKTO_DATA_INGESTION_URLplaceholder - Must be replaced with your Akto instance URL
Python scripts (
.py): Core validation and ingestion logic, Akto API communicationakto_ingestion_utility.py: Shared validation/ingestion logic imported by every hook script — lives in a different GitHub directory (shared/, notcodex-cli-hooks/), so it needs its own download stepakto_machine_id.py: Generates unique device identifiers for Atlas modehooks.json: Links hooks to wrapper scriptsconfig.toml: Must enable thecodex_hooksfeature 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
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:
Cloud-managed requirements (ChatGPT Business / Enterprise)
macOS managed preferences (MDM)
Local user configuration (
~/.codex/config.toml)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:
Save the configuration.
Push the updated profile to managed devices.
Restart Codex.
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.
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:
Restart Codex.
Execute an action that should trigger a hook.
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
Enable Codex Hooks Feature Flag
Codex hooks are experimental. Enable them in ~/.codex/config.toml (used by both CLI and Desktop):
Create Directories
Download Hook Scripts
Configure Akto Ingestion URL and API Token ⚠️ CRITICAL STEP
All wrapper scripts contain the placeholders {{AKTO_DATA_INGESTION_URL}} and {{AKTO_API_TOKEN}} that must be replaced — the URL with your actual Akto instance URL, and the token with your Akto API token (obtain it from Akto Atlas → Connectors → Setup Guardrail card). If your deployment does not require auth, set the token to an empty string so the placeholder is removed (an unsubstituted {{AKTO_API_TOKEN}} would be sent as an invalid Authorization header).
Automated replacement:
Manual replacement (alternative):
Edit each wrapper script and replace:
With:
Files to update:
akto-validate-prompt-wrapper.shakto-validate-response-wrapper.shakto-validate-pre-tool-wrapper.shakto-validate-post-tool-wrapper.sh
Configure Hooks
Copy hooks.json to ~/.codex/hooks.json:
Note: You can also place
hooks.jsonat<repo>/.codex/hooks.jsonfor repository-level hooks.
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
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
Troubleshooting
Uninstallation
To completely remove Akto hooks from Codex CLI or Codex Desktop:
Enterprise Deployment
Automated Deployment Script
Deploy to developers:
Resources
Support: support@akto.io
Community: https://www.akto.io/community
Last updated