Codex Agent

Built-in Agent provider

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:

<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 />, 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:

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 includes this Codex and codex-acp baseline. The default full image includes them too. Local Sandbox still requires both commands on the host.

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.

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:

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.

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 packageACP adapter source and installation context.

Codex project instructionsOfficial OpenAI documentation for AGENTS.md discovery and precedence.

Agent Client ProtocolThe protocol boundary used by AML's shared Agent session engine.

AML Codex profile sourceExecutable mapping, environment, and option validation.

AML Codex testsLaunch, precedence, and live integration coverage.

Related AML documentation

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

JavaScript ToolsDefine, scope, validate, and operate an application-owned Tool.

Model Context ProtocolDeclare MCP servers, transports, allowlists, and runtime requirements.

Runtime configurationConfigure limits, cancellation, lifecycle events, tracing, and cleanup.

Agent component referenceReview Agent props, resolution, capability scope, and result behavior.