default/codex

# Codex (`codex`)

> A single-agent baseline that runs one `codex exec --json` session in the task's real environment. Codex edits and evaluates the candidate; Galapagos independently scores the changing solution file and keeps the best observed checkpoint.

## Overview

For the default Docker evaluation mode, this scaffold follows the same installed-agent topology as `claude_code`: it resolves the task's own image, layers `@openai/codex` onto that image, and starts one shared container. The agent runs as the host's non-root uid with `/workspace` writable. The trusted runner, evaluator, and task data are provisioned under root-owned `/eval`, so the agent can use the scorer but cannot rewrite it. The evaluator that records the result attaches to this same container, which keeps the score Codex sees and the score Galapagos records in the same runtime.

For a task explicitly scored in local mode, Codex runs as a host subprocess instead. This passes `--dangerously-bypass-approvals-and-sandbox`, so local mode gives model-generated commands the permissions of the current user. Use it only with tasks and prompts you trust. A Docker task that itself needs the host Docker socket (for example ALE-Bench) can also reach the host daemon and is not a host-security sandbox.

The CLI boundary is Codex-specific:

- `codex exec --json` provides machine-readable JSONL events.
- `general.max_iterations` is communicated as the improvement budget in `TASK.md`.
- Codex has no `--max-turns`, so `proposer.codex_cli_max_steps` is a harness safety cap over completed command, file-change, MCP, web-search, plan, and agent-message items.
- `turn.completed.usage` supplies input, cached-input, output, and reasoning-output token counts.
- Native rollouts under `$CODEX_HOME/sessions/**/*.jsonl`, the combined CLI log, and `run_summary.json` remain in the run directory.

## Authentication

Authentication is structurally **ChatGPT-managed**, matching the `claude_code` token-then-login
fallback. API-key billing is not supported. The priority order is:

1. `CODEX_ACCESS_TOKEN`, consumed over stdin with `codex login --with-access-token` inside the
   isolated run home. This is the closest Codex equivalent to Claude's setup token. Official Codex
   access tokens are currently available to supported Business/Enterprise workspaces; do not copy a
   short-lived browser access token out of `auth.json`.
2. A file-backed `codex login` browser session at `~/.codex/auth.json`. This is the normal path for
   personal ChatGPT subscriptions.

For the access-token path, export the secret or put it in the git-ignored `.env`:

```bash
export CODEX_ACCESS_TOKEN='<workspace-issued-codex-access-token>'
```

For the browser-login fallback, prepare file-backed local auth once:

```toml
# ~/.codex/config.toml
cli_auth_credentials_store = "file"
```

```bash
codex login
codex login status
```

For an access token, the controller sends the value only to the isolated `codex login` process over
stdin; it is not forwarded through Docker `-e`, left in the agent environment, or recorded in run
metadata. For browser login, the scaffold verifies that `auth.json` contains ChatGPT access and
refresh tokens rather than an API-key login, then copies it into the isolated `CODEX_HOME` with mode
`0600`. Codex refreshes that staged cache normally. Galapagos atomically writes a changed cache back
to its source before deleting the staged copy, so a Docker run does not throw away a rotated refresh
token. Runs sharing one `auth.json` must be serialized, as required by Codex account-auth automation.

`CODEX_API_KEY`, `OPENAI_API_KEY`, and `OPENAI_BASE_URL` are removed from the Codex process
environment. `CODEX_ACCESS_TOKEN` is also removed after its one-time login bootstrap. Thus an
unrelated API key in `.env` cannot silently change the billing path. Native session JSONL is
preserved after credentials are removed.

`GALAPAGOS_CODEX_CREDENTIALS_FILE` may point to another writable copy of the same ChatGPT
`auth.json` format for an outer orchestrator. It does not enable API-key auth. The source must accept
refresh write-back; an orchestrator backed by a secret manager should restore the current file before
the run and persist the updated file afterward. OS-keyring-only credentials cannot be copied into the
task container, which is why file credential storage is required for this fallback.

The isolated Codex home does not copy host `config.toml` settings. It keeps native session history
but disables account apps, remote plugins, memories, update checks, and internal multi-agent
delegation. This prevents a benchmark container from inheriting personal connectors and preserves
the scaffold's single-agent baseline.

## Algorithm

1. Resolve the task image and install Codex into it (or locate the host CLI for local mode).
2. Provision the trusted evaluator and score the seed through the normal Galapagos setup path.
3. Write `solution<task suffix>`, `run_eval.sh`, `TASK.md`, and the non-interactive launch script.
4. Run one `codex exec --json --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox`
   session. The final flag is the explicit long-form alias of `--yolo`.
5. Parse JSONL for progress and token usage while polling the solution. Every changed non-empty snapshot is independently evaluated and admitted to the keep-all population.
6. Score any final unobserved write, retain the best-scored genome, save run/session metadata, persist
   any Codex-managed auth refresh, remove staged auth, and tear down the container.

## Configuration

- `general.max_iterations` (100): improvement budget communicated to Codex.
- `proposer.codex_cli_max_steps` (null): hard completed-item cap; null means twice the improvement budget.
- `proposer.codex_wall_timeout_seconds` (null): whole-session timeout; null derives it from the action cap and evaluator timeout.
- `proposer.codex_model` (`gpt-5.6-sol`): `--model`; provider prefixes such as `openai/` are stripped like Harbor.
- `proposer.reasoning_effort` (`max`): `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or
  `ultra` (availability is model- and CLI-version-dependent).
- `proposer.reasoning_summary` (`auto`): `auto`, `concise`, `detailed`, or `none`.
- `proposer.codex_web_search` (`disabled`): `disabled`, `cached`, `indexed`, or `live`.
- `proposer.codex_docker_image`, `codex_docker_memory`, `codex_docker_cpus`, and `codex_docker_network`: container overrides.
- `proposer.codex_docker_cli_version` (null): optional npm package version pin.

## Source

The environment and checkpoint lifecycle reuse Galapagos's `claude_code` scaffold.
Installation, model-name normalization, isolated `CODEX_HOME`, and native-session retention follow
Harbor's installed Codex agent. Managed credential staging follows Galapagos's Claude Code trust
model, adapted to Codex's workspace access tokens and refreshable ChatGPT login cache. The
command/event contract follows the official Codex non-interactive and configuration documentation.