Skip to main content
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:
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:

​
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:
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.
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.