# 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](https://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](https://github.com/getaxonflow/axonflow-codex-plugin/releases/latest) · [Security advisories](https://github.com/getaxonflow/axonflow-codex-plugin/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.
---
## Take a governed plugin rollout into production
Solo developers and self-serve teams can use the free 90-day [Plugin Evaluation License](https://getaxonflow.com/plugins/evaluation-license?utm_source=readme_plugin_codex_eval) to validate hook behavior, policy packs, and override workflows.
Organizations with a dated production requirement, written controls, an executive sponsor, and a technical owner can use AxonFlow's paid [Production Program](https://getaxonflow.com/design-partner?utm_source=readme_plugin_codex). It takes one scoped workflow into production over 60 or 75 days with Enterprise access, founder-led rollout support, upfront conversion pricing, and a fixed decision date.
Public Design Partner pricing starts at $2,000; the Confidential Paid Pilot starts at $4,000. Prices are subject to eligibility and a signed agreement.
### See AxonFlow in Action
Videos covering different angles of the platform:
- **[Product demos: Platform + Fraud & Risk](https://getaxonflow.com/demo/?utm_source=github&utm_medium=readme&utm_campaign=product_demo&utm_content=axonflow-codex-plugin)** - runtime enforcement, HITL approvals, audit evidence, cost visibility, and agentic payment controls
- **[Community Quickstart walkthrough (2 min)](https://youtu.be/BSqU1z0xxCo)** - governed calls, PII blocking, Gateway Mode with LangChain/CrewAI, and MAP from YAML
- **[Architecture deep dive (12 min)](https://youtu.be/Q2CZ1qnquhg)** - 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](https://getaxonflow.com/plugins/evaluation-license?utm_source=readme_plugin_codex_eval)
---
## Privacy notice
**Read before installing.** AxonFlow [Community SaaS](https://docs.getaxonflow.com/docs/deployment/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](https://docs.getaxonflow.com/docs/deployment/self-hosted/)** — 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](https://docs.getaxonflow.com/docs/deployment/evaluation-rollout-guide/)** — 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](https://getaxonflow.com/plugins/evaluation-license).
3. **[AxonFlow Enterprise](https://docs.getaxonflow.com/docs/deployment/community-to-enterprise-migration/)** — 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](https://github.com/getaxonflow/axonflow) and follow the [Getting Started](https://docs.getaxonflow.com/docs/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](https://docs.getaxonflow.com/docs/deployment/community-saas/) page for the full disclosure, including [data retention](https://docs.getaxonflow.com/docs/deployment/community-saas/#limitations-and-disclaimers) and [registration mechanics](https://docs.getaxonflow.com/docs/deployment/community-saas/#registration).
### 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:
```bash
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](https://developers.openai.com/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:
```bash
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](https://docs.getaxonflow.com/docs/getting-started/) guide for prerequisites (Docker Engine or Desktop, Docker Compose v2, 4 GB RAM, 10 GB disk) and the [Self-Hosted Deployment Guide](https://docs.getaxonflow.com/docs/deployment/self-hosted/) for production options. For production with real users or clients, run Community Edition with a free 90-day [Evaluation License](https://docs.getaxonflow.com/docs/deployment/evaluation-rollout-guide/) or [AxonFlow Enterprise](https://docs.getaxonflow.com/docs/deployment/community-to-enterprise-migration/).
> Skipping Step 1 makes the plugin fall back to the [Community SaaS](https://docs.getaxonflow.com/docs/deployment/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
```bash
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 servers from `~/.codex/config.toml` (TOML). A plugin installed through `/plugins` also brings its own `.mcp.json`, which `.codex-plugin/plugin.json` points at. For this manual setup, add the server to `config.toml`:
```bash
cat >> ~/.codex/config.toml << 'EOF'
[mcp_servers.axonflow]
url = "http://localhost:8080/api/v1/mcp-server"
EOF
```
#### 2.3 Enable hooks and install the hook file
```bash
cat >> ~/.codex/config.toml << 'EOF'
[features]
codex_hooks = true
EOF
cp hooks/hooks.json ~/.codex/hooks.json
```
The `hooks.json` file uses relative paths (`./scripts/...`). Update those paths in `~/.codex/hooks.json` to the absolute location of the plugin's `scripts/` directory, or symlink so Codex can resolve them from the plugin checkout.
#### 2.4 Register the plugin in Codex's local marketplace
From the directory where you launch `codex`:
```bash
mkdir -p .agents/plugins
cat > .agents/plugins/marketplace.json << 'EOF'
{
"name": "axonflow-local",
"plugins": [{
"name": "axonflow",
"source": { "source": "local", "path": "./axonflow-codex-plugin" },
"policy": { "installation": "INSTALLED_BY_DEFAULT" },
"category": "Security"
}]
}
EOF
codex # then install via /plugins
```
### Step 3: point the plugin at the platform
Without this step the plugin auto-registers with Community SaaS regardless of whether you ran Step 1 — it does not auto-detect a locally-running AxonFlow. Set `AXONFLOW_ENDPOINT`, and if you have credentials, `AXONFLOW_AUTH` and `AXONFLOW_MCP_AUTHORIZATION`:
```bash
# Self-hosted local agent — that alone flips mode to self-hosted, no other env var needed
export AXONFLOW_ENDPOINT=http://localhost:8080
# Self-hosted remote agent with credentials
export AXONFLOW_ENDPOINT=https://axonflow.your-company.com
export AXONFLOW_AUTH=$(echo -n "your-client-id:your-client-secret" | base64)
export AXONFLOW_MCP_AUTHORIZATION="Basic $AXONFLOW_AUTH"
```
The hooks add `Basic ` to `AXONFLOW_AUTH` themselves. Codex sends an MCP header's variable exactly as it is set and adds no scheme, so the MCP session reads `AXONFLOW_MCP_AUTHORIZATION`, which carries it. With only `AXONFLOW_AUTH` set, the MCP session sends no `Authorization` header: plain Community admits that, and a platform that checks credentials (Community SaaS, Enterprise) refuses it until you export `AXONFLOW_MCP_AUTHORIZATION`. Versions up to 1.8.0 sent the bare value, which such a platform refused as well.
Every hook invocation logs a one-line canary on stderr confirming the active mode:
```
[AxonFlow] Connected to AxonFlow at http://localhost:8080 (mode=self-hosted)
```
If the canary says `mode=community-saas` after you ran Step 1, the plugin is still hitting `try.getaxonflow.com` because Step 3 was skipped or `AXONFLOW_ENDPOINT` is unset. Fix Step 3 and reload.
---
## Configure
[Step 3](#step-3-point-the-plugin-at-the-platform) above covers `AXONFLOW_ENDPOINT`, `AXONFLOW_AUTH` and `AXONFLOW_MCP_AUTHORIZATION`. Two more environment variables worth knowing about:
```bash
# Optional: longer request timeout for remote / VPN deployments
export AXONFLOW_TIMEOUT_SECONDS=12
# Optional (Enterprise): admin-minted per-user token for a VERIFIED
# {identity, role} — role-scoped access + per-developer audit attribution
# instead of the shared tenant identity. See "Per-user authorization
# token" below.
export AXONFLOW_USER_TOKEN=<token minted by your org admin>
```
**Fail behavior:**
- AxonFlow unreachable (network) → fail-open, tool execution continues
- AxonFlow auth/config error → fail-closed (exit 2), tool call blocked until config is fixed
- Per-user token rejected by the platform (HTTP 401) → fail-closed (exit 2) while the token is configured — see below
- PostToolUse failures → never block (audit and PII scan are best-effort)
### Per-user authorization token (`AXONFLOW_USER_TOKEN`)
The shared `AXONFLOW_AUTH` credential authenticates the *tenant*; the
**per-user token** identifies the *developer* behind the session. On an
Enterprise platform that validates per-user tokens (enterprise#2929, first
platform release after v9.9.0), an org admin mints a token per developer
(`POST /api/v1/admin/organizations/{org_id}/user-tokens`, or OIDC tokens
from your IdP), and the plugin sends it as the `X-User-Token` header on
every governed request — both hooks and the MCP session. The platform
validates it (signature, expiry, revocation, org binding) and resolves a
**non-forgeable `{identity, role}`** for the developer: audit rows attribute
to the verified identity, and role-scoped features (e.g. who can read the
whole tenant's audit trail vs. only their own rows) key on the validated
role instead of treating every fleet developer identically.
Resolution precedence on the hook surfaces:
1. **`AXONFLOW_USER_TOKEN`** — set per developer via managed settings / MDM
(fleet) or the shell profile (individual). Wins outright.
2. **`~/.config/axonflow/user-token.json`** — `{"token": "<minted token>"}`.
This is the **cross-plugin provisioning path** (the claude plugin reads
the same file), so fleet tooling writes ONE file per developer machine.
The file **must be `0600`** (owner read/write only); the plugin refuses a
group/world-readable token file with a stderr warning rather than loading
it silently:
```bash
umask 077
printf '{"token":"%s"}' "<minted token>" > ~/.config/axonflow/user-token.json
chmod 600 ~/.config/axonflow/user-token.json
```
3. **Unset** — no `X-User-Token` header is sent (never an empty header) and
requests are exactly what a pre-1.6 plugin sends; the platform keeps its
least-privilege attribution path (shared tenant identity, own-rows access).
**MCP plane is env-only.** Codex resolves the MCP session's headers itself
via the `env_http_headers` mapping in `~/.codex/config.toml`, so on that
plane the token must come from the `AXONFLOW_USER_TOKEN` env var (managed
settings / MDM); the `user-token.json` fallback covers the hook surfaces
only. After upgrading the plugin, **re-run
`bash scripts/install-mcp-with-headers.sh`** so your `config.toml` picks up
the new `X-User-Token` mapping (Codex omits the header entirely while the
env var is unset, so the mapping is inert until a token is provisioned).
The token is a **credential**: the plugin never logs or echoes its value,
and on the hook surfaces a malformed candidate (whitespace/control/quote
bytes — a mis-paste) is dropped locally with a diagnostic instead of being
sent. Codex sends the MCP-plane env value **raw**, and the platform **fails
closed** on a presented-but-invalid token (malformed, expired, revoked,
minted for a different org): governed calls are then denied — the hooks
block (exit 2) with a message naming the per-user token as the likely cause
— until the token is rotated or removed. Rotation/revocation is admin-driven
on the platform; re-provisioning the new token to the developer's env/file
is all the plugin needs.
---
## Pro tier (paid)
The plugin runs in two tiers:
- **Free** — no `X-License-Token` header sent; agent applies free-tier quotas (3-day audit retention, 200 governed events / day, 2 active custom policies, 1 HITL approval per rolling 7d).
- **Pro** — `X-License-Token: AXON-...` sent on every governed request; agent's plugin-claim middleware validates the Ed25519 signature + DB row and stamps a Pro-tier context (30-day audit retention, **2,000 events / day**, **unlimited active custom policies**, **unlimited HITL approvals**, plus the **LLM cost pre-flight** tool — estimate token cost for a multi-step plan before it runs).
Pro is **$9.99 USD for 90 days**, one-time payment, no auto-renewal, 14-day no-questions refund. See [getaxonflow.com/pricing](https://getaxonflow.com/pricing/) for the full breakdown and the Stripe buy button.
To activate Pro on this Codex install:
1. **Find your client ID.** From the plugin install root, run:
```bash
bash scripts/recover.sh status
```
The output includes a `client_id cs_<uuid>` 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. **Buy at the pricing page.** Visit [getaxonflow.com/pricing](https://getaxonflow.com/pricing/) and click **Buy Plugin Pro — $9.99**. At Stripe Checkout, paste your `client_id` into the **AxonFlow tenant ID** custom field. (The Stripe form's field label is still "AxonFlow tenant ID" — same value, the label will be renamed in a future release.)
3. **Install the issued license token.** After checkout you'll receive an `AXON-...` token by email. Install it one of two ways:
```bash
# Operator override / CI
export AXONFLOW_LICENSE_TOKEN="AXON-...your-token..."
# Persistent: write to ~/.codex/axonflow.toml (mode 0600)
bash scripts/recover.sh apply-token
```
Check current tier and config:
```bash
bash scripts/recover.sh status
```
Token resolution order: `AXONFLOW_LICENSE_TOKEN` env var, then `license_token = "AXON-..."` in `~/.codex/axonflow.toml`. The plugin filters out tokens that don't carry the canonical `AXON-` prefix before sending so the agent never sees malformed values.
#### One-time MCP-session setup (required for Pro-tier MCP traffic)
Per-call hooks (terminal command governance) carry your Pro-tier token automatically once `AXONFLOW_LICENSE_TOKEN` is set. **MCP-session traffic** (the long-lived connection codex opens to AxonFlow's MCP-server endpoint for tool discovery) needs a one-time setup because Codex's `mcp add` CLI doesn't expose a `--header` flag, but its `~/.codex/config.toml` schema does support `[mcp_servers.<n>.http_headers]` and `[mcp_servers.<n>.env_http_headers]` blocks. Run:
```bash
bash scripts/install-mcp-with-headers.sh
```
This registers AxonFlow as a codex MCP server AND patches your `~/.codex/config.toml` to inject `X-Axonflow-Client: codex-plugin/<version>` (static) plus `X-License-Token`, `Authorization`, and `X-User-Token` resolved from the `AXONFLOW_LICENSE_TOKEN`, `AXONFLOW_MCP_AUTHORIZATION`, and `AXONFLOW_USER_TOKEN` env vars at MCP-session time (Codex omits any header whose env var is unset). The script is idempotent — safe to re-run after a plugin upgrade or token rotation.
Verify with:
```bash
codex mcp get axonflow
```
The output should list non-empty `http_headers` and `env_http_headers` rows.
## Recover lost credentials
If you've lost your `AXONFLOW_AUTH` / tenant secret (and your tenant was registered with an email):
```bash
bash scripts/recover.sh request # POSTs /api/v1/recover; agent emails magic link
# (open email, click link, copy hex token)
bash scripts/recover.sh verify # POSTs /api/v1/recover/verify; persists new creds
```
The verify step writes the returned `tenant_id`, `secret`, `endpoint`, and `email` atomically into `~/.codex/axonflow.toml` (mode `0600`, inside a `0700` parent). An existing `license_token` line is preserved across recovery so you don't get silently downgraded from Pro to Free.
For automation / CI / runtime tests, the script reads `AXONFLOW_RECOVER_EMAIL`, `AXONFLOW_RECOVER_TOKEN`, and `AXONFLOW_LICENSE_TOKEN` from the environment instead of prompting.
Two new agent-callable skills (`recover-credentials` and `pro-tier-status`) let Codex guide a user through the same flows when they say things like *"I lost my AxonFlow credentials"* or *"am I on the Pro tier?"*.
---
## What gets checked
AxonFlow ships with **80+ built-in system policies** that apply to Codex automatically. No configuration required — new policies added to the platform are immediately enforced.
| Category | Coverage |
|---|---|
| **Dangerous commands** | Reverse shells, `rm -rf /`, `curl \| bash`, credential file access, path traversal |
| **SQL injection** | 30+ patterns including UNION injection, stacked queries, auth bypass, encoding tricks |
| **PII detection** | SSN, credit card, Aadhaar, PAN, email, phone, NRIC/FIN (Singapore), and more — with redaction |
| **Secrets exposure** | API keys, connection strings, hardcoded credentials, code secrets |
| **SSRF** | Cloud metadata endpoint (`169.254.169.254`) and internal-network blocking |
| **Prompt injection** | Instruction override, jailbreak attempts, role hijacking |
| **Codex-specific** | `.codex-plugin/*.json` and `.mcp.json` write protection (enabled via `AXONFLOW_INTEGRATIONS=codex`) |
Custom policies are easy — `POST /api/v1/dynamic-policies` or the Customer Portal. See [Policy Enforcement](https://docs.getaxonflow.com/docs/mcp/policy-enforcement/).
---
## The 15 MCP tools Codex can call
Beyond the hook surface, the agent's MCP server exposes **15 tools** Codex can call directly. All served by the platform at `/api/v1/mcp-server`.
### Governance (6)
| Tool | Purpose |
|------|---------|
| `check_policy` | Evaluate specific inputs against policies |
| `check_output` | Scan specific content for PII/secrets |
| `audit_tool_call` | Record an additional audit entry |
| `list_policies` | List active governance policies |
| `get_policy_stats` | Summary of governance activity |
| `search_audit_events` | Search individual audit records for debugging and compliance |
### Decision explainability & session overrides (4)
| Tool | Purpose |
|------|---------|
| `explain_decision` | Return the full [DecisionExplanation](https://docs.getaxonflow.com/docs/governance/explainability/) for a decision ID |
| `create_override` | Create a time-bounded, audit-logged session override (mandatory justification) |
| `delete_override` | Revoke an active session override |
| `list_overrides` | List active overrides scoped to the caller's tenant |
### Tenant identity & tier capability (5 — V1 Plugin Pro)
| Tool | Free access | Pro access |
|------|-------------|------------|
| `axonflow_get_tenant_id` | Visible + callable — returns tenant_id, server-resolved tier, upgrade URL | Same |
| `axonflow_list_pro_features` | Visible + callable — locked Pro feature list (5 differentiators + $9.99 / 90-day pricing) | Same |
| `axonflow_request_approval` | Visible + 1 per rolling 7d | Unlimited |
| `axonflow_create_tenant_policy` | Visible + 2 active max | Unlimited |
| `axonflow_get_cost_estimate` | Filtered out of `tools/list` — Pro-only | Visible + callable |
When a Free-tier cap is hit on these tools, the agent returns a structured upgrade envelope (same shape as the 429 daily-quota envelope) and the plugin surfaces the upgrade prompt to stderr — see [Free-tier limits and upgrade prompts](#free-tier-limits-and-upgrade-prompts) below.
See [Session Overrides](https://docs.getaxonflow.com/docs/governance/overrides/).
---
## Free-tier limits and upgrade prompts
When the plugin's hooks hit a Free-tier cap (200 events/day, 2 active custom policies, 1 HITL approval per rolling 7d, or a Pro-only feature), the agent returns a structured upgrade envelope. The plugin parses it and prints a single-line nudge to stderr — visible in Codex's hook log:
```
[AxonFlow] Daily limit reached on Free tier (200 events). Pro raises this to 2,000/day. Resets at midnight UTC.
[AxonFlow] Upgrade: https://buy.stripe.com/bJe28qbztcdVchjdkw8k800
```
The plugin also stamps a local back-off file from the response's `Retry-After` header so subsequent governed calls fall through immediately (no thundering herd against the agent) until the cap clears. The upgrade nudge is shown at most once per UTC day so it doesn't spam every hook.
---
## Skills
The skills are how Codex gets governance guidance for non-terminal tools — the advisory half of the hybrid model. Implicit activation means Codex invokes them automatically when the task matches the skill description; explicit invocation is `@axonflow`.
| Skill | When used | Activation |
|-------|-----------|------------|
| `pre-execute-check` | Before non-Bash tool calls that modify state | Implicit or explicit |
| `post-execute-audit` | After non-Bash tool calls complete | Implicit or explicit |
| `pii-scan` | After tool calls that return data | Implicit or explicit |
| `governance-status` | Checking governance posture | Explicit |
| `audit-search` | Searching compliance evidence | Explicit |
| `policy-list` | Listing active policies | Explicit |
| `recover-credentials` | Recovering lost credentials or installing a paid Pro license token | Implicit or explicit |
| `pro-tier-status` | Checking which tier (free or Pro) the install is on | Implicit or explicit |
---
## Latency
| Operation | Typical overhead |
|-----------|-----------------|
| Policy pre-check (hook) | 2–5 ms |
| PII detection | 1–3 ms |
| Audit write (async) | 0 ms (non-blocking) |
| **Total per-terminal-call overhead** | **3–10 ms** |
Imperceptible in interactive Codex sessions.
---
## Sister integrations
Same governance platform, same 80+ policies, same 15 MCP tools — different agent hosts:
| Integration | Repo | Docs |
|---|---|---|
| OpenAI Codex | *this repo* | [codex](https://docs.getaxonflow.com/docs/integration/codex/) |
| Claude Code | [axonflow-claude-plugin](https://github.com/getaxonflow/axonflow-claude-plugin) | [claude-code](https://docs.getaxonflow.com/docs/integration/claude-code/) |
| Cursor IDE | [axonflow-cursor-plugin](https://github.com/getaxonflow/axonflow-cursor-plugin) | [cursor](https://docs.getaxonflow.com/docs/integration/cursor/) |
| OpenClaw | [axonflow-openclaw-plugin](https://github.com/getaxonflow/axonflow-openclaw-plugin) | [openclaw](https://docs.getaxonflow.com/docs/integration/openclaw/) |
---
## Plugin structure
```
axonflow-codex-plugin/
├── .codex-plugin/
│ ├── plugin.json # Plugin metadata
│ └── marketplace.json # Marketplace listing
├── .mcp.json # MCP server connection (platform-side)
├── hooks/
│ └── hooks.json # PreToolUse + PostToolUse for exec_command
├── skills/
│ ├── pre-execute-check/
│ ├── post-execute-audit/
│ ├── pii-scan/
│ ├── governance-status/
│ ├── audit-search/
│ ├── policy-list/
│ ├── recover-credentials/ # Magic-link recovery + Pro-tier token install
│ └── pro-tier-status/ # Reports Free vs Pro tier
├── scripts/
│ ├── pre-tool-check.sh # Policy enforcement (PreToolUse)
│ ├── post-tool-audit.sh # Audit + PII scan (PostToolUse)
│ ├── mcp-auth-headers.sh # Basic-auth + X-License-Token headers for MCP
│ ├── recover.sh # request|verify|apply-token|status user surface
│ ├── telemetry-ping.sh # Anonymous heartbeat (at most once per 7 days)
│ ├── uninstall.sh # Clean removal of hooks, config, and marketplace entry
│ └── lib/
│ └── license-token.sh # Pro-tier token resolver + TOML config writer
├── runtime-e2e/
│ ├── v1-paid-tier/ # X-License-Token wire-up runtime test
│ ├── recovery/ # Recovery surface runtime test
│ └── ... # Read-side governance skill runtime tests
└── tests/
├── test-hooks.sh # Regression tests (mock + live)
├── E2E_TESTING_PLAYBOOK.md
└── e2e/ # Smoke E2E against live AxonFlow
```
---
## Testing
```bash
# Hook regression tests (no live stack required)
./tests/test-hooks.sh
# Smoke E2E against a live AxonFlow at localhost:8080
bash tests/e2e/smoke-block-context.sh
```
The smoke scenario runs the plugin's `pre-tool-check.sh` against a running platform, feeds a SQLi-bearing Bash tool invocation through it, and asserts Codex's deny semantics (exit 2 + stderr prefix `AxonFlow policy violation`) carry the richer-context markers (`decision:`, `risk:`). Exits 0 with `SKIP:` if no stack is reachable.
For the broader validation story — explain-decision, override lifecycle, audit-filter parity, cache invalidation — see the [Codex integration guide](https://docs.getaxonflow.com/docs/integration/codex/).
---
## Troubleshooting
**MCP server connection failed?** Codex reads MCP servers from `~/.codex/config.toml` (TOML), and from the `.mcp.json` of a plugin installed through `/plugins`. For a manual setup, add `[mcp_servers.axonflow]` with `url = "http://localhost:8080/api/v1/mcp-server"`. **Refused with 401 on Community SaaS or Enterprise?** Export `AXONFLOW_MCP_AUTHORIZATION="Basic $AXONFLOW_AUTH"` ([Step 3](#step-3-point-the-plugin-at-the-platform)) and re-run `scripts/install-mcp-with-headers.sh`.
**Hooks not firing on bash?** Hooks must be at `~/.codex/hooks.json` (not inside the plugin directory). Enable hooks with `[features] codex_hooks = true` in `~/.codex/config.toml`. The hook matcher should include `exec_command` — Codex uses this name for terminal commands, not `Bash`.
**Skills not activating?** Skills activate implicitly when the task matches the description. For explicit invocation, use `@axonflow`. Ensure the plugin is installed via `/plugins` in Codex and the MCP server is reachable.
**Plugin not visible in `/plugins`?** `marketplace.json` must live at `$CWD/.agents/plugins/marketplace.json` relative to where you launch `codex`. The `source.path` must be relative (start with `./`) and point inside the same root.
**PII in file writes not detected?** Codex hooks only support Bash (`exec_command`). Write/Edit operations cannot be hooked. PII detection for file writes depends on advisory skills (`pre-execute-check`, `pii-scan`) — the skill instructs the agent to call `check_output` before writing, but this is not enforced. This is the advisory half of the hybrid model at work; see [Governance Model](#the-hybrid-governance-model).
More troubleshooting in the [integration guide](https://docs.getaxonflow.com/docs/integration/codex/#troubleshooting).
---
## Telemetry
Anonymous heartbeat at most once every 7 days per machine: plugin version, OS, architecture, bash version, AxonFlow platform version, the licence tier that platform reports about itself, deployment mode (`community_saas` / `self_hosted` / `unknown`), and endpoint type (`localhost` / `private_network` / `remote` / `unknown`). **Never** tool arguments, message contents, or policy data. The stamp file mtime advances only after the HTTP POST returns 2xx, so a transient network failure does not silence telemetry until the next window.
The licence tier sent is whatever the platform reported about itself, relayed verbatim. The plugin does not normalise, map, or restrict the value, so a transient state such as `starting`, or a tier name introduced after this plugin shipped, reaches the wire unchanged rather than being flattened into a fixed list. What is never read or sent: **no licence key, no expiry date, no seat count, and no customer or organisation name**. It is read from the `tier` field of the `/health` response the heartbeat already fetches to detect the platform version, so it costs no additional request, and it is omitted entirely whenever that probe does not answer with one.
Two further values are relayed on the same terms, from the same response: the platform's **edition** and the deployment mode the **platform reports about itself**. The second is deliberately separate from the `deployment_mode` above, which is this plugin's own classification of the endpoint it was pointed at — they answer different questions and routinely differ, so neither is written over the other. Both are omitted entirely whenever the platform does not report them, which is the case for every platform released before they existed. Any relayed value longer than 64 bytes — measured in bytes, not characters — is dropped whole rather than truncated, since a truncated value would be something the platform never said, and a value containing a NUL is dropped for the same reason.
The heartbeat does not follow HTTP redirects on either leg, and only a **2xx** counts on either leg. A redirected or erroring `/health` teaches the plugin nothing — its body is not read at all, even when it carries one — rather than relaying values from a response your platform never meant as an answer. A redirected or rejected checkpoint POST is not treated as a delivery: the 7-day stamp advances only on a 2xx, so neither can silence telemetry for a week on a ping that was never received.
Opt out: set `AXONFLOW_TELEMETRY=off` in the environment Codex runs in.
### Scope of `AXONFLOW_TELEMETRY=off`
`AXONFLOW_TELEMETRY=off` disables the anonymous heartbeat described above. On **self-hosted** and **in-VPC** deployments, that heartbeat is the only data the plugin sends to AxonFlow, so setting `=off` means we receive nothing. On **Community SaaS** (`try.getaxonflow.com`) the hosted service also processes operational data — registrations, audit logs, policy enforcement records, workflow state, plan data, and request-header metadata aggregated for usage analytics — as part of running the platform; that operational data flow is governed by the [Privacy Policy](https://getaxonflow.com/privacy/), not by `AXONFLOW_TELEMETRY`.
`DO_NOT_TRACK` is **not** honored as an opt-out for AxonFlow telemetry. It is commonly inherited from host tools and developer environments — and in Codex specifically, the CLI injects `DO_NOT_TRACK=1` into every hook subprocess regardless of user intent. That makes it an unreliable expression of user intent, so AxonFlow telemetry is controlled exclusively by `AXONFLOW_TELEMETRY=off`.
Guarded by a stamp file at `$HOME/.cache/axonflow/codex-plugin-telemetry-sent` (delete to re-send). Details: [docs.getaxonflow.com/docs/telemetry](https://docs.getaxonflow.com/docs/telemetry/).
---
## Links
- **[Codex Integration Guide](https://docs.getaxonflow.com/docs/integration/codex/)** — the full walkthrough (recommended starting point)
- [AxonFlow Documentation](https://docs.getaxonflow.com)
- [Codex Plugins docs (OpenAI)](https://developers.openai.com/codex/plugins)
- [Policy Enforcement](https://docs.getaxonflow.com/docs/mcp/policy-enforcement/)
- [Decision Explainability](https://docs.getaxonflow.com/docs/governance/explainability/)
- [Session Overrides](https://docs.getaxonflow.com/docs/governance/overrides/)
- [Self-Hosted Deployment](https://docs.getaxonflow.com/docs/deployment/self-hosted/)
- [Security Best Practices](https://docs.getaxonflow.com/docs/security/best-practices/)
- Sister plugins: [Claude Code](https://github.com/getaxonflow/axonflow-claude-plugin) · [Cursor](https://github.com/getaxonflow/axonflow-cursor-plugin) · [OpenClaw](https://github.com/getaxonflow/axonflow-openclaw-plugin)
## License
MIT