# Codex CLI

Connect Codex CLI to Kastra policies and verify the hook boundary.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/edge/codex

## Prerequisites

[Install Edge](https://docs.kastra.ai/edge/install), install Codex CLI, and sign in to the intended Kastra workspace. Use a test environment for initial policy checks.

## Connect the hook

```sh
kastra-edge login
kastra-edge install-codex --dry-run
kastra-edge install-codex
kastra-edge doctor
```

The installer targets `~/.codex/config.toml (or CODEX_HOME/config.toml)`. Review its proposed change and restart the agent so it loads the new configuration. Keep unrelated hooks intact.

## What is governed

The installer writes a Kastra-managed hook block for PreToolUse, PostToolUse, UserPromptSubmit, and SessionStart. Existing configuration is preserved and the result is validated as TOML.

The hook calls Kastra's service before the supported action. Work outside the hook is not governed. Network or harness failures can allow work to continue under the integration's failure behavior; read [failure handling](https://docs.kastra.ai/reference/failure-behavior).

## Verify the connection

Run a harmless action and inspect the exact decision in the console. Then test a narrow deny rule and a HOLD rule in your test environment. Confirm the actual side effect, not only the banner or notification. [Verification checklist](https://docs.kastra.ai/start/first-workflow).

## Operational notes

For Codex on Windows, confirm compatibility with Kastra before relying on hook enforcement. Check [platform support](https://docs.kastra.ai/start/platform-support). To remove the managed block, use `kastra-edge uninstall-codex`.

If no decision appears, check the hook file, PATH, login, environment, agent restart, and [troubleshooting guide](https://docs.kastra.ai/edge/troubleshooting). Installation detection alone cannot prove that the host invoked the hook.

## Usage telemetry

Setup also writes the managed Codex telemetry configuration when logged in. Re-run setup after a credential change or an older hook-only install, then restart Codex. Review [collection and reporting limits](https://docs.kastra.ai/edge/telemetry).