# Codex Agent

Run Codex through AML's maintained Agent Client Protocol profile.
Canonical: https://agent-markup-language.com/docs/providers/agents/codex/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

**Codex Agent — `codexAgent()`**

A thin AML profile over the maintained Codex ACP adapter. AML owns the evaluation, session, Tool bridge, structured result, and cleanup lifecycle; Codex owns the model session and coding-agent behavior.

- **Best for:** OpenAI coding workflows that need an ACP-compatible coding Agent.

- **Know before using:** AML does not install Codex or the ACP adapter. Shell and network containment come from the enclosing Sandbox, not from Codex's filesystem mode.

**Built-in** **ACP** **Credentialed**

## What this provider launches

`codexAgent()` launches the command configured by `command`, defaulting to `codex-acp`. The command is the ACP adapter entrypoint, not necessarily the native `codex` binary. The adapter receives its Codex configuration through environment variables that AML prepares for each acquired Agent session:

```text
<Agent>
  AML normalizes model, system instructions, permissions, Tools, and MCP
        ↓
  codex-acp (or your configured command)
        ↓
  Codex model session
```

Every acquisition receives private Codex state. `CODEX_SQLITE_HOME` and logs live under AML's temporary session directory. Without authored Skills, `CODEX_HOME` uses that directory too; with [`<Skill />`](https://agent-markup-language.com/docs/reference/primitives/skill/), AML points `CODEX_HOME` at the Agent's private staging home so Codex discovers the copied `.agents/skills/<name>/` packages. Both roots are released when the Agent session finishes.

The private `CODEX_HOME` also prevents the operator's global Codex guidance from being inherited. Codex still discovers
project-scoped `AGENTS.md` and `AGENTS.override.md` files from the repository root down to the effective working
directory. AML's authored `system` content becomes `developer_instructions` in addition to that project guidance. Skill bodies remain files for progressive discovery and are not inserted into `developer_instructions`.

## Prerequisites

**Install the adapter**

Install `@agentclientprotocol/codex-acp` and the native `@openai/codex` CLI, or provide equivalent executables for
both configured command paths. AML does not download them at runtime.

**Provide credentials**

Supply `apiKey`, `CODEX_API_KEY`, or `OPENAI_API_KEY` through the provider environment, according to the adapter and
model configuration you use.

**Choose a runtime**

Run on a trusted host or inside a Sandbox whose image contains the ACP command, its runtime, a shell, and all
model-provider dependencies.

Install the repository baseline and verify both commands from the environment where AML will launch them:

```sh title="Terminal"
npm install --global @agentclientprotocol/codex-acp@1.4.0 @openai/codex@0.147.0
codex-acp --help
codex --version
```

These versions are a repeatable repository baseline, not a guarantee that every newer adapter/CLI pair is compatible. Re-run the live provider path when either changes.

For container execution, the [Codex image variant](https://agent-markup-language.com/docs/sandbox-images/#choose-a-variant) includes this Codex and `codex-acp` baseline. The default full image includes them too. Local Sandbox still requires both commands on the host.

**Caution — Read-only does not mean fully isolated**

AML maps filesystem access to Codex's `INITIAL_AGENT_MODE`, but the provider implementation explicitly leaves shell
and network restrictions to the enclosing Sandbox. Use a real Sandbox boundary when the prompt, code, or user input is
not trusted.

## Complete example

This example uses the public SDK entrypoint and makes the Workspace/Sandbox boundary explicit. A real Codex ACP executable must be available in the selected environment. Local Sandbox requires `read-write` access to start any host process, including `codex-acp`; the instruction not to modify files is therefore advisory. Use an enforcing Sandbox such as a deliberately hardened Docker runtime when read-only access is a security requirement.

```tsx
import { Agent, AmlRuntime, Sandbox, Workspace, codexAgent, localSandbox, localWorkspace } from "@aml-jsx/sdk"

const workspace = localWorkspace({ directory: "/absolute/path/to/repository" })
const sandbox = localSandbox()
const provider = codexAgent({
  // The default is "codex-acp". Use "npx" only when your deployment policy
  // deliberately permits package resolution at launch time.
  command: "codex-acp",
  model: "gpt-5.6-luna",
  reasoningEffort: "low",
})

const result = await new AmlRuntime({
  agentProvider: provider,
}).evaluate(
  <Workspace id="codex-review" provider={workspace} load={false} save={false}>
    <Sandbox provider={sandbox} access="read-write">
      <Agent system="Inspect files but do not modify them.">
        Summarize the repository structure and identify the highest-risk module.
      </Agent>
    </Sandbox>
  </Workspace>
)

console.log(result)
```

For a first integration, verify the executable independently:

```sh
codex-acp --help
```

If you use the repository's live ACP test pattern, the adapter can be launched through `npx` with an explicit package version and an isolated `CODEX_HOME`. That is useful for development, but preinstalling the adapter in a deployment image is more predictable.

## Options and precedence

| Option              | Type                     | Default       | Semantics                                                                                  |
| ------------------- | ------------------------ | ------------- | ------------------------------------------------------------------------------------------ |
| `apiKey`            | `string`                 | —             | Adds `CODEX_API_KEY` and selects the ACP `api-key` authentication method.                  |
| `command`           | `string`                 | `"codex-acp"` | ACP executable or launcher. It must be a non-empty, trimmed string without null bytes.     |
| `args`              | `readonly string[]`      | `[]`          | Appended to the launch command exactly as supplied. Arguments cannot contain null bytes.   |
| `config`            | JSON-compatible object   | `{}`          | Base Codex configuration. It must serialize successfully before any external work begins.  |
| `codexPathOverride` | `string`                 | `"codex"`     | Sets `CODEX_PATH` for the ACP adapter; it does not replace `command`.                      |
| `env`               | `Record<string, string>` | `{}`          | Additional launch environment. Use it for provider-specific credentials and configuration. |
| `model`             | `string`                 | —             | Provider-level model fallback.                                                             |
| `reasoningEffort`   | `string`                 | —             | Writes the provider-native value into `model_reasoning_effort` in Codex configuration.     |
| `workingDirectory`  | `string`                 | —             | Fallback working directory when no Sandbox supplies the effective directory.               |

Values such as `"high"` in the examples are provider-native examples, not an AML allowlist. AML only checks that the value is a normalized non-empty string without null bytes, then forwards it to Codex unchanged.

The effective values are resolved as follows:

1. `<Agent model="..." />` overrides the factory `model`.
2. The Agent's normalized `system` text becomes Codex `developer_instructions`.
3. `config` is copied first; AML-owned `model`, `model_reasoning_effort`, and `developer_instructions` are written afterward and therefore win when present.
4. An active Sandbox supplies the effective working directory. `workingDirectory` is used when the Agent is not running inside one.
5. `apiKey` is explicit provider configuration. Otherwise `env.CODEX_API_KEY` or `env.OPENAI_API_KEY` can advertise API-key authentication to the ACP adapter.

**Note — Environment precedence**

AML spreads the provider's `env`, then writes its session-owned Codex variables such as `CODEX_HOME`, `CODEX_CONFIG`,
`CODEX_SQLITE_HOME`, `APP_SERVER_LOGS`, `CODEX_PATH`, `INITIAL_AGENT_MODE`, and `NO_BROWSER`. Do not rely on
overriding those session variables through `env`; they are owned by the AML launch profile.

## Permissions and capabilities

| AML request                | Codex launch behavior                                                     | Boundary that still matters                                                 |
| -------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `filesystem: "read-write"` | `INITIAL_AGENT_MODE=agent-full-access`; `permissionPolicy="allow_always"` | The host or Sandbox still controls actual process and filesystem authority. |
| `filesystem: "read-only"`  | `INITIAL_AGENT_MODE=read-only`; `permissionPolicy="allow_once"`           | Shell and network restrictions rely on the enclosing Sandbox.               |
| `shell: false`             | No additional Codex-native mapping is claimed by this profile.            | Use a Sandbox that rejects shell execution.                                 |
| `network: false`           | No additional Codex-native mapping is claimed by this profile.            | Use a Sandbox or deployment network policy that enforces it.                |

Codex native subagents inherit the parent turn's effective Codex permission profile and approval policy. AML leaves multi-agent execution enabled, so a subagent spawned after AML sets the Codex ACP adapter's `INITIAL_AGENT_MODE=read-only` remains read-only. This inheritance does not add Codex-native mappings for `shell: false` or `network: false`; those restrictions still depend on the enclosing Sandbox.

## Failure modes and troubleshooting

1. **`command not found` or ACP startup failure**

   Confirm that `codex-acp` exists in the same host or Sandbox where AML calls `spawn()`. If you use a custom `command`, run that exact command with its `args` outside AML first.

2. **Authentication or model errors**

   Check the adapter's credential requirements and the model identifier. Prefer deployment environment configuration over writing credentials into a Workspace. `apiKey` maps to `CODEX_API_KEY`; provider-specific environment variables can be passed through `env`.

3. **The Agent starts but cannot edit or execute**

   Inspect both layers: Codex's filesystem mode and the enclosing Sandbox's `access`, `root`, and process capabilities. AML's permission mapping cannot grant a Sandbox capability that is absent.

4. **Configuration is rejected before launch**

   Remove leading/trailing whitespace and null bytes from strings. Keep `config` JSON-compatible: no cycles, functions, class instances, `BigInt`, or non-finite numbers.

5. **Codex follows instructions you did not put in `<Agent system>`**

   Inspect the repository's `AGENTS.md` and `AGENTS.override.md` chain. The private `CODEX_HOME` isolates global Codex
   state, but it intentionally does not suppress project instructions.

## Provider references

- [Codex ACP package](https://github.com/agentclientprotocol/codex-acp) — ACP adapter source and installation context.

- [Codex project instructions](https://developers.openai.com/codex/guides/agents-md/) — Official OpenAI documentation for AGENTS.md discovery and precedence.

- [Agent Client Protocol](https://agentclientprotocol.com/) — The protocol boundary used by AML's shared Agent session engine.

- [AML Codex profile source](https://github.com/we-are-singular/aml/tree/main/providers/agents/codex/src) — Executable mapping, environment, and option validation.

- [AML Codex tests](https://github.com/we-are-singular/aml/tree/main/providers/agents/codex/tests) — Launch, precedence, and live integration coverage.

## Related AML documentation

These capabilities use AML's shared Agent lifecycle and do not require Codex-specific setup:

- [JavaScript Tools](https://agent-markup-language.com/docs/cookbook/tools/) — Define, scope, validate, and operate an application-owned Tool.

- [Model Context Protocol](https://agent-markup-language.com/docs/cookbook/mcp/) — Declare MCP servers, transports, allowlists, and runtime requirements.

- [Runtime configuration](https://agent-markup-language.com/docs/runtime/) — Configure limits, cancellation, lifecycle events, tracing, and cleanup.

- [Agent component reference](https://agent-markup-language.com/docs/reference/primitives/agent/) — Review Agent props, resolution, capability scope, and result behavior.