> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex driver

> How the Guild runtime executes the OpenAI Codex coding engine to drive agent turns.

Guild's runtime can drive agent turns with the OpenAI Codex coding engine. The Codex driver runs alongside the existing Claude driver, so the runtime can execute either engine in the same environment.

This page describes how the runtime installs, configures, and executes Codex. You do not set these values yourself — the runtime manages them for every turn.

## Execution environment

The runtime container pins the Codex command-line interface (CLI) to a specific global package version:

```bash theme={null}
npm install -g @openai/codex@0.146.0
```

The driver sets the `CODEX_HOME` environment variable to `/home/node/.codex`. Codex writes session rollouts to this directory, so resumed turns reuse persistent session state within the same runtime container.

## Running a turn

The driver runs Codex as a subprocess. It executes `codex exec` to start a new turn and `codex exec resume` to continue a resumed turn. Both invocations pass `-o` to capture the final result output.

## System prompt

Codex has no system-prompt flag, so the driver folds the agent's system prompt into the turn's message — but only on a fresh session.

* **Fresh session** — the system prompt is prepended to the message, separated by a `---` line.
* **Resumed session** — the system prompt is dropped. A session's instructions are fixed when it is created, so passing them again would be silently ignored.

The Claude driver handles a resumed session's system prompt the same way.

## Command-line flags

The driver configures Codex with the following flags, verified against Codex 0.146.0:

| Flag                                         | Description                                                                             |
| -------------------------------------------- | --------------------------------------------------------------------------------------- |
| `--json`                                     | Emits the event stream as JSON Lines (JSONL) on standard output.                        |
| `--strict-config`                            | Fails the run when the configuration contains unknown or invalid keys.                  |
| `--dangerously-bypass-approvals-and-sandbox` | Skips approval prompts and the Codex sandbox. The runtime container provides isolation. |
| `--skip-git-repo-check`                      | Runs Codex outside a Git repository without failing.                                    |
| `--ignore-user-config`                       | Ignores user-level Codex configuration so runs stay reproducible.                       |

## Model provider

The driver points Codex at a `guild` model provider instead of OpenAI directly. The provider uses the base URL `<task.baseurl>/runtime/services/openai/v1` with the `responses` wire API and authenticates with `Bearer <task-secret>`, mapped from `GUILD_CODEX_API_KEY`.

## Fail-fast networking

The driver sets `request_max_retries=0` and `stream_max_retries=0`. When the network is offline or blackholed, the turn fails in under a second instead of retrying until the turn deadline elapses.

## Event-stream translation

The driver reads Codex's JSONL event stream and translates each line into runtime events:

* `thread.started` — captures the thread identifier used to resume the session.
* `turn.started`, `turn.completed`, and `turn.failed` — track the turn lifecycle. `turn.failed` is terminal.
* `item.started` and `item.completed` — surface progress feedback and track errors.

Those become the same task notifications any other agent emits:

| Notification | Emitted from                                                                                                                              |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `progress`   | Each `item.started` and `item.completed` that renders a readable line. The turn lifecycle events produce no progress output of their own. |
| `done`       | The end of the turn, carrying the final text from the file named by `-o`.                                                                 |
| `error`      | A `turn.failed` event, which ends the turn.                                                                                               |

<Note>
  An `error` **item** is not a failed turn. Codex reports recoverable problems — unknown model metadata, for one — as an error item and then completes the turn normally. Only `turn.failed` is terminal.
</Note>

An item type the driver does not recognize still renders as a generic progress line rather than being dropped, so a new Codex item type cannot silently swallow a turn.