Axonflow Codex Plugin

AxonFlow Plugin for OpenAI Codex

Runtime governance for OpenAI Codex: hard-enforce policy on every terminal command, guide Codex through skills for non-terminal tools, and keep a compliance-grade audit trail — without changing how you use Codex.

[](./LICENSE)

> → Full integration walkthrough: docs.getaxonflow.com/docs/integration/codex — architecture, the hybrid governance model, policy examples, troubleshooting, and the 15 MCP tools the platform exposes.

> Upgrade strongly recommended. AxonFlow ships substantial monthly security and quality hardening; staying on the latest major is the security-supported release line. Latest release · Security advisories

---

Why you'd add this

OpenAI Codex is a cloud-based agentic coding platform with sandboxed execution, MCP server support, and a composable skill system. It's excellent at agent-driven software delivery. It was never designed to be the layer where your security and compliance team lives.

The gaps start surfacing the moment Codex runs anywhere near production:

| Production requirement | Codex alone | With this plugin | |---|---|---| | Policy enforcement on terminal commands | PreToolUse hooks available, no logic | Hard-enforced: dangerous commands blocked with exit code 2 | | Policy checks for non-terminal tools | Not available | Advisory via skills — Codex instructed to call check_policy before Write/Edit/MCP | | PII / secrets in tool outputs | Not addressed | Auto-scan on terminal outputs; skills guide detection on others | | SQL-injection detection on MCP queries | MCP server's problem | 30+ patterns available via check_policy MCP tool | | Compliance-grade audit trail | Execution logs, not compliance-formatted | Every governed terminal call recorded with policies, decision, duration | | Decision explainability after a block | Generic hook failure | decision_id in stderr; explain_decision MCP tool returns the full record | | Self-service, time-bounded exceptions | Not available | create_override with mandatory justification, fully audited |

The unique thing about Codex is that not every tool can be hooked — only terminal commands (exec_command) fire PreToolUse. This plugin is honest about that split, and uses a hybrid model that makes the boundary usable instead of fuzzy.

---

The hybrid governance model

Codex governance has two sides. AxonFlow spans both, but they are enforced differently — being explicit about this is what turns the plugin into something a platform team can reason about instead of a fuzzy "guardrails" story.

| Tool class | Mechanism | Enforcement | |---|---|---| | Bash / exec_command / shell | PreToolUse hook → check_policy | Hard-enforced. Exit code 2 blocks execution before it starts. Cannot be bypassed. | | Write, Edit, MCP tools | Governance skills instruct Codex to call check_policy before acting | Advisory. The skill guides, Codex decides. Skills support implicit activation when the task matches. | | Audit trail | PostToolUse hook (terminal) + skills (others) | Automatic for terminal, skill-guided for everything else |

Both paths converge on the same explainability and override surface — a blocked exec_command and a blocked-by-skill MCP write can both be investigated with explain_decision and unblocked with create_override when policy allows. That's what a senior platform engineer needs to evaluate this: the enforced path and the advisory path share one audit story.

---

How it works

Terminal commands (enforced)

Codex selects exec_command / shell
    │
    ▼
PreToolUse hook fires automatically
    │ → check_policy("codex.exec_command", "curl 169.254.169.254")
    │
    ├─ BLOCKED (exit 2) → command never runs; decision_id in stderr
    │
    └─ ALLOWED (exit 0) → command executes
                      │
                      ▼
                 PostToolUse hook
                      │ → audit_tool_call(tool, input, output)
                      │ → check_output(result for PII/secrets)

Other tools (advisory via skills)

Codex selects Write / Edit / MCP tool
    │
    ▼
Governance skill activates (implicit or explicit via @axonflow)
    │ → Codex calls check_policy("codex.Write", file content)
    │
    ├─ Policy says blocked → Codex is instructed not to proceed
    └─ Policy says allowed → Codex proceeds → audit skill records action

---

Where this kicks in during real use

1. The dangerous-command problem (enforced path)

A developer tells Codex "clean up old test data." Codex selects exec_command and runs a destructive rm. That's the kind of mistake hooks exist for.

With the plugin: PreToolUse fires before exec_command runs, the command is evaluated against 80+ policies (reverse shells, credential access, cloud metadata SSRF, path traversal, SQL-injection patterns), and blocked with exit 2 if it violates policy. The decision ID lands in stderr so Codex can call explain_decision and, if appropriate, create_override.

2. The MCP query that returns too much (advisory path)

Codex queries a database MCP server for "recent orders" and gets back a response with customer emails and phone numbers. Skills-side governance can't force a check, but it can make the check the path of least resistance.

With the plugin: the pii-scan and post-execute-audit skills implicitly activate on MCP-returning tasks. Codex calls check_output against AxonFlow, which returns either a clean pass or PII-match details the model should honor. Every call is also auditable by running search_audit_events later.

3. The converged unblock story

A exec_command is blocked mid-session because a production pattern matched. The developer wants to proceed.

With the plugin: Codex reads the decision ID from stderr, calls explain_decision to surface the policy family, and if the decision allows overrides, calls create_override with justification. The override is time-bounded and fully audited. Same workflow if the block came from an advisory skill path — converged UX, one audit story.

---

Try AxonFlow on a real plugin rollout

We're opening limited Plugin Design Partner slots.

30-minute hook lifecycle review, policy pack scoping, override workflow design, and IDE/CLI rollout pattern walkthrough — for solo developers and small teams putting governance on Codex.

Apply here or email [design-partners@getaxonflow.com](mailto:design-partners@getaxonflow.com). Personal email is fine — solo developers welcome.

See AxonFlow in Action

Three short videos covering different angles of the platform:

• Community Quickstart Demo (Code + Terminal, 2.5 min) — governed calls, PII block, Gateway Mode with LangChain/CrewAI, and MAP from YAML
• Runtime Control Demo (Portal + Workflow, 3 min) — approvals, retry safety, execution state, and the audit viewer
• Architecture Deep Dive (12 min) — how the control plane works, policy enforcement flow, and multi-agent planning

Plugin Evaluation Tier (Free 90-day License)

Outgrown Community on a real plugin install? Evaluation unlocks the capacity and features that matter for plugin users — without moving to Enterprise yet:

| Capability | Community | Evaluation (Free) | Enterprise | |---|---|---|---| | Tenant policies | 20 | 50 | Unlimited | | Org-wide policies | 0 | 5 | Unlimited | | Audit retention | 3 days | 14 days | Up to 10 years | | HITL approval gates | — | 25 pending, 24h expiry | Unlimited, 24h | | Evidence export (CSV/JSON) | — | 5,000 records · 14d window · 3/day | Unlimited | | Policy simulation | — | 300/day | Unlimited | | Session overrides (self-service unblock) | — | — | Enterprise-only |

Org-wide policies and session overrides are Enterprise-only — those are the actual upgrade triggers for plugin users.

Get a free Plugin Evaluation license

---

Privacy notice

Read before installing. AxonFlow Community SaaS at try.getaxonflow.com is the zero-config endpoint the plugin uses if neither AXONFLOW_ENDPOINT nor AXONFLOW_AUTH is configured. In that mode, governed tool inputs (tool name + arguments) and outbound message bodies are checked by AxonFlow's policy enforcement endpoint. Community SaaS is for early exploration only — not for production workloads, regulated environments, real user data, personal data, or any other sensitive information. It is offered "as is" on a best-effort basis with no SLA, no warranties, and no commitment to retention, deletion, or incident-response timelines.

For any serious use, choose one of the following instead:

1. Self-host AxonFlow Community Edition — runs entirely on your infrastructure and keeps data within your boundary. Recommended for any real workload. The in-README quick start is in [Step 1](#step-1-install-the-axonflow-platform) below.
2. Community Edition with an Evaluation License — for production use with real users or clients on the open core; adds production-fit limits and license-gated features. Free 90-day evaluation license.
3. AxonFlow Enterprise — production-grade governance, regulatory-grade controls, SLOs, and contractual commitments suitable for regulated industries. Contact [hello@getaxonflow.com](mailto:hello@getaxonflow.com).

To skip Community SaaS entirely: set AXONFLOW_ENDPOINT to a self-hosted AxonFlow URL. That alone flips the plugin into self-hosted mode — the Community SaaS auto-bootstrap is not attempted, and no env var is required. Get the AxonFlow platform from getaxonflow/axonflow and follow the Getting Started guide for the Docker Compose setup. For air-gapped environments where AxonFlow is not yet reachable but you want to suppress the bootstrap attempt, set AXONFLOW_COMMUNITY_SAAS=0; set AXONFLOW_TELEMETRY=off to also disable the anonymous 7-day heartbeat.

LLM provider keys never leave the user's machine in any mode — Codex makes the LLM calls; AxonFlow only enforces policies and records audit trails.

Mode-specific reference

The recommended self-hosted path is covered in [Install Step 1](#step-1-install-the-axonflow-platform). Two more modes worth knowing about:

Community SaaS — for early exploration only

The plugin's zero-config fallback when neither AXONFLOW_ENDPOINT nor AXONFLOW_AUTH is configured. The plugin registers a tenant with try.getaxonflow.com on first run and persists credentials at ~/.config/axonflow/try-registration.json (mode 0600). Every hook invocation logs a one-line canary on stderr:

[AxonFlow] Connected to AxonFlow at https://try.getaxonflow.com (mode=community-saas)

Use only for early exploration of the plugin's behaviour. Not for production workloads, regulated environments, real user data, personal data, or any other sensitive information.

| What goes to try.getaxonflow.com | What does NOT | |---|---| | Tool name + arguments before each governed call | LLM provider API keys | | Outbound message bodies before delivery (PII/secret scan) | Codex conversation history outside governed tools | | Anonymous 7-day heartbeat (plugin version, OS, runtime) | Files outside the Codex runtime |

The endpoint runs against shared Ollama models, rate-limits at 20 req/min · 500 req/day per tenant, and is offered "as is" on a best-effort basis with no SLA, no warranties, no commitment to retention or deletion timelines, and may be modified or discontinued without notice. Read the Try AxonFlow — Free Trial Server page for the full disclosure, including data retention and registration mechanics.

Air-gapped: zero outbound

For environments where no outbound traffic is permitted at all — air-gapped labs, regulated networks, classified deployments — set both env vars before the Codex process starts:

export AXONFLOW_COMMUNITY_SAAS=0   # disable Community SaaS auto-bootstrap
export AXONFLOW_TELEMETRY=off      # disable the anonymous 7-day heartbeat
export AXONFLOW_ENDPOINT=http://your-internal-axonflow:8080

With both env vars set and AXONFLOW_ENDPOINT pointing at a same-network instance, no traffic leaves your environment.

---

Install

This is a three-step install: stand up the AxonFlow platform, add the plugin to Codex, then point the plugin at the platform. The plugin alone does not enforce policy — its hook scripts are thin clients that talk to an AxonFlow agent gateway. If the platform is not installed and reachable, governed tool calls have nothing to evaluate against. Skipping Step 3 is the most common mistake: the platform is running locally but the plugin still falls back to Community SaaS because no AXONFLOW_ENDPOINT is configured.

Prerequisites

• OpenAI Codex CLI
• jq and curl on PATH

Step 1: install the AxonFlow platform

For any real workload, run AxonFlow on your own infrastructure via Docker Compose:

git clone https://github.com/getaxonflow/axonflow.git
cd axonflow && docker compose up -d

# verify
curl -s http://localhost:8080/health | jq .

Follow the Getting Started guide for prerequisites (Docker Engine or Desktop, Docker Compose v2, 4 GB RAM, 10 GB disk) and the Self-Hosted Deployment Guide for production options. For production with real users or clients, run Community Edition with a free 90-day Evaluation License or AxonFlow Enterprise.

> Skipping Step 1 makes the plugin fall back to the Community SaaS endpoint at try.getaxonflow.com for early exploration only. Do not skip Step 1 for any real workload — see the [Privacy notice](#privacy-notice) above.

Step 2: install the plugin

No LLM provider keys are required — Codex handles every LLM call; AxonFlow only evaluates policies and records audit trails.

2.1 Clone the plugin

git clone https://github.com/getaxonflow/axonflow-codex-plugin.git
cd axonflow-codex-plugin

2.2 Point Codex at the AxonFlow MCP server

Codex reads MCP config from ~/.codex/config.toml (TOML), not from .mcp.json in the plugin directory:

cat >> ~/.codex/config.toml > ~/.codex/config.toml  .agents/plugins/marketplace.json ` line — that's the value Stripe Checkout needs. Copy it. (Same value the v1.4.x output called `tenant_id`; renamed in v1.5.0 for consistency with the rest of AxonFlow's v9 terminology.) Or ask the agent: "what is my AxonFlow client ID?" (both "client ID" and "tenant ID" still work) — the [`pro-tier-status` skill](#agent-skills) will run the script and surface the value.

2. *

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [getaxonflow](https://github.com/getaxonflow)
- **Source:** [getaxonflow/axonflow-codex-plugin](https://github.com/getaxonflow/axonflow-codex-plugin)
- **License:** MIT

Install and usage instructions live in the source repository linked above.