| name | configure-codex-frontend |
| description | Configure Codex as the frontend builder in the three-agent AgentCore harness. Use for deploying the Codex Runtime, staging AGENTS.md and .codex/config.toml, or verifying that the generated interface resolves its service address at runtime and delegates work to the MCP server. |
RESTORE PATH - NOT THE SERVED ROLE
Codex requires GPT-5.x (OpenAI) via Bedrock Mantle. Workshop Studio accounts
cannot be granted the openai.gpt-5.5 Mantle entitlement (org SCP blocks the
grant; see EE-14394). Any attempt to run Codex on a Workshop Studio account
returns a 401. The served frontend in the workshop is opencode (Bedrock-native
claude-sonnet-4-6, no Mantle entitlement needed; see
configure-opencode-frontend).
Use this skill only if you are restoring the Codex path in a context where the
Mantle entitlement is available (non-Workshop Studio account with GPT-5.x
enabled). All Codex assets (coding-agents/codex/) remain in the repository as
the restore path.
Configure the Codex frontend builder
Codex builds the frontend interface. Claude Code builds the backend and a second
Claude Code (the validator) validates the composed result. There is no race and no
winner.
Prerequisites
coding-agents/infra.config exists.openai.gpt-5.5 is enabled for Bedrock Mantle in us-east-2.- The Runtime execution role can use the AWS SDK credential chain.
- Docker Buildx or Finch can build arm64 images.
Codex does not need an OpenAI key, AgentCore workload identity, or API-key
credential provider. The Runtime IAM role is the authentication path.
Deploy
cd coding-agents/codex
./setup.sh
python deploy.py
runtime_config.json must contain a Runtime ARN and the Runtime must reach
READY before continuing.
Stage project guidance
Copy the whole project configuration so hidden settings are preserved:
cp -R orchestrator/harness/codex/. /mnt/s3files/
test -s /mnt/s3files/AGENTS.md
test -s /mnt/s3files/.codex/config.toml
The root AGENTS.md defines the frontend role. The hidden
.codex/config.toml selects the amazon-bedrock provider and model.
The thin-client rule (why it is a browser fact, not a preference)
Any interface the frontend builds must resolve its service address at RUNTIME,
never at build time. This is not a use-case preference; it is a browser constraint:
localhost and 127.0.0.1 in a page mean the machine running the BROWSER.
A URL baked at build time is dead the moment the page moves to any other host.- A cross-origin JSON POST is preflighted by the browser. The service must answer
OPTIONS with the correct Access-Control-Allow-Origin header or the browser
will block the request before it reaches the server.
These constraints hold for every interface the frontend produces, regardless of the
task.
Verify
agentcore exec --it \
--runtime "$(jq -r .runtime_arn coding-agents/codex/runtime_config.json)" \
--region us-west-2
Inside the Runtime, run /app/run.sh and give Codex the task. Verify that the
produced interface resolves the backend service address at runtime (not hardcoded),
delegates backend work to the MCP server via tools/call, and handles OPTIONS
preflight correctly if it runs cross-origin. Do not claim completion until the
interface loads and a round-trip through the backend succeeds.
Reference: https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-openai-gpt-55.html
