Skip to the content

Govern Codex CLI

Install the Codex pack, add its hooks to Codex's managed requirements.toml on a root install, start Codex through the launcher, and check what is enforced.

Install the Codex policy pack, add AgentGarm's hooks to Codex's managed requirements.toml on a root install, start Codex through the launcher so the sandbox holds whatever its hooks do, and check what is enforced and at what level.

1. Install the Codex pack in audit mode

On a no-root install, agentgarm policy init codex writes the Codex pack into your policy directory, in mode: audit, and never over a file that is already there unless you add --force. A root install normally has it: sudo agentgarmd install writes every default pack, in audit mode, into the system's policy directory before agentgarmd starts, unless that directory already holds a policy, so check that codex.yaml is there (if not, policy init with --dir writes it); policy init with --dir and --force puts back the shipped pack. The launcher picks it for a command named codex. agentgarmd reads the policy directory when it starts, so after policy init restart it as the rollout guide shows, and enforce the pack only after its blast radius on your own history is clear.

Besides the command rules every pack has, it makes Codex's own configuration read-only to file tools: ~/.codex/config.toml, hooks.json, requirements.toml and its installed skills, and the workspace's .codex and .git/hooks. Like every pack, it also keeps your shell startup files, ~/.gitconfig and your per-user login services read-only, so once you enforce it a file-tool write to ~/.zshrc is refused.

agentgarm policy init codex
ls /etc/agentgarm/agents.d                               # Linux
ls "/Library/Application Support/AgentGarm/agents.d"     # macOS
sudo agentgarm policy init codex --dir /etc/agentgarm/agents.d --force
sudo agentgarm policy init codex --dir "/Library/Application Support/AgentGarm/agents.d" --force
schema: agentgarm.com/schemas/agents/v1
name: codex
version: "1.1.0"
mode: audit
profile: interactive
on_internal_error: fail_open_alert

match:
  launcher: true
  binaries: [codex]
  process_tree_root: true
    read_only:
      - "~/.codex/config.toml"
      - "~/.codex/hooks.json"
      - "~/.codex/requirements.toml"
      - "~/.codex/skills"               # installed skills load at the next start, sandboxed or not
      - "${WORKSPACE}/.codex"
      - "${WORKSPACE}/.git/hooks"
      # User persistence: shell startup files, git's global configuration and per-user login
      # services. File tools are refused here; for agents launched through `agentgarm run` each is
      # also a sandbox write deny, and where an OS file sentinel runs it refuses any process's write.
      - "~/.bashrc"
      - "~/.zshrc"
      - "~/.profile"
      - "~/.bash_profile"
      - "~/.zprofile"
      - "~/.gitconfig"
      - "~/Library/LaunchAgents"
      - "~/.config/systemd/user"

Checked by the walk: these commands ran as written on a no-root Linux install and a root install on Linux.

See also

Watch your agent for a week, then enforce

Start a policy in audit mode, see what enforcing it would have blocked in your own history, fix the rules that get in the way, then switch it to enforce.

2. Put AgentGarm's hooks in Codex's managed requirements.toml

On a root install, sudo agentgarmd hooks install codex adds AgentGarm's hooks to the system requirements.toml (/etc/codex/ on Linux and macOS). It merges into a file your organisation may already own: it sets [features] hooks = true, sets hooks.managed_dir only if it is unset, and replaces only its own hook groups, keeping your hooks, keys and comments. allow_managed_hooks_only is left to you. A file that is not valid TOML is refused and left untouched.

[features] hooks = true pins Codex's hooks on; it is not a fail-closed flag, and Codex has none. agentgarmd checks the install every 500 ms: an edited command or features.hooks switched off is rewritten, recorded as a policy-source conflict, and lowers Codex's live tasks to C. A no-root install writes no Codex hooks (a managed source needs root), so there Codex is governed through the launcher alone.

sudo agentgarmd hooks install codex
sudo agentgarmd hooks status codex

Checked by the walk: these commands ran as written on a root install on Linux.

3. Start Codex through agentgarm run

agentgarm run picks the Codex pack from the command name, registers a task, checkpoints the workspace, builds the sandbox from the pack, proves it with the canary and routes the agent through the proxy; any failure refuses the launch. In the sandbox Codex may write its workspace and ~/.codex, and the credential paths stay closed. On macOS it cannot write ~/.codex/config.toml, hooks.json, requirements.toml or the installed skills in ~/.codex/skills, which Codex loads at its next start; on Linux, Landlock cannot carve a file out of a writable directory, so there only Codex's hooks, where installed, guard them. With CODEX_HOME set to an absolute path, that directory takes the place of ~/.codex, with the same denies, and the launch checks the hooks, plugins and MCP servers there as it does the home's.

Codex takes its model endpoint from openai_base_url in its configuration, not from the OPENAI_BASE_URL the launcher sets, so agentgarm run passes it to Codex: the proxy's /openai/v1 route. On macOS it also runs Codex with sandbox_mode="danger-full-access", because Codex's own sandbox cannot start inside AgentGarm's, which is the one that enforces. A -c or -s of your own after codex still wins. Codex sends no task header, so the proxy counts each model call against the task through Codex's process, under the task's budget. The proxy carries no WebSocket: it answers Codex's WebSocket attempt with 426, and Codex goes on over HTTPS.

Sign in with an API key before you launch. A ChatGPT sign-in is never routed: inside the sandbox Codex cannot refresh it, so no model call is made. Switch to the key once, outside agentgarm run. Codex also cannot save a folder's trust from inside the sandbox: when a folder is new to it, agentgarm run prints the entry to add to its config.toml from outside.

printenv OPENAI_API_KEY | codex login --with-api-key
agentgarm run -- codex

4. Know what enforces and what only advises

Codex's hooks fail open: a hook that times out, crashes or answers badly lets the call go ahead. Codex cannot pause for an answer, so a policy's ask is applied as a deny, and it cannot apply a changed call, so a modification is a deny too; a patch is checked file by file, and one protected file denies the whole patch. For these reasons Codex's hooks are rated C (observed) on every host, managed or not (coverage). What enforces is the launcher and the sandbox: a launch that fails a check is refused, and the sandbox's file boundaries (and on macOS its network boundary) hold whatever the hooks do. [features] hooks = false in ~/.codex/config.toml or the workspace's .codex/config.toml is reported as a user off-switch and lowers the task to C.

5. Check the session with status

While Codex runs, agentgarm status shows its task with an assurance level and, under it, each class the policy uses with the layer that enforces it. The level is the weakest of those classes: the pack has command rules, which only Codex's hooks can judge, so a Codex session rates C, while its files class is B from the sandbox wherever the launch's containment check passes. The coverage line for codex gives its hook tier, whether the managed hooks are in force, and a cannot: line for each thing its hooks cannot do. Until agentgarmd is restarted (or sent SIGHUP) after agentgarm policy init codex, the policy line for codex reads NOT LOADED. The adapter is verified against Codex 0.165.0; a Codex past its verified range is flagged as drift by agentgarm agents, and its tasks show it on their lowered: line.

agentgarm status

Checked by the walk: this command ran as written on a no-root Linux install.

See also

Check that protection is on

See whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.