AgentKit Studio
Runtimes and deployment

Codex Agent

The Codex App Server adapter's execution model, configuration surface, timeout budgets and sandbox limits, and when it refuses to start.

Codex Agent (codex) gives each turn its own ephemeral Codex thread, while DSH remains the owner of the visible session and its history. Studio does not pretend a Codex Agent is an OpenAI-compatible gateway model; it keeps the same codex app-server --stdio protocol boundary as the official Codex provider (src/providers/codex-runtime.mjs:3-8).

Execution model

StageOwnerSource
Model / tool loopCodex App Serverexecution: 'codex-app-server'
AdapterIn-process, Studioowner: 'studio'
Contractstudio.codex.adapter/v1contract
Event sourcestudio-codex-adaptereventOwner
Streamingcodex-turn/itemstreamOwner
Session and historyDSH SessionOne ephemeral thread per turn
Model provider idagentkit-studio-codexsrc/providers/codex-models.mjs:4

Source: src/runtime-contract.mjs:30-34.

A new thread starts every turn, so permissions, sandbox and reasoning effort apply to that turn only and are never written into user configuration (src/providers/codex-runtime.mjs:169-178).

When to choose it

  • The work is editing code, running commands and reading repository diffs — Codex's tool set and sandbox model are built for exactly that.
  • You want Codex approval semantics (approvalPolicy) rather than DSH tool approval.
  • Your team already runs the official Codex provider and wants to reuse the same CLI and app server.
  • You need native-request replay (replay) while still staying on the DSH session.

When the work is not coding, DSH Native is lighter (see runtime comparison).

Configuration entry points

Executable resolution order

  1. AGENTKIT_CODEX_BIN (explicit path wins)
  2. @openai/codex/bin/codex.js (resolved from the package)
  3. On Windows, the native binary is preferred so a GUI child process does not flash a console window

Source: src/providers/codex-command.mjs:29-42.

Environment variables

VariableDefaultPurpose
AGENTKIT_CODEX_MODEL—Default model
AGENTKIT_CODEX_APPROVAL_POLICYneverApproval policy
AGENTKIT_CODEX_SANDBOX—Sandbox mode
AGENTKIT_CODEX_REASONING_SUMMARYReadable summaryReasoning summary; a readable text form is requested by default
AGENTKIT_CODEX_TIMEOUT_MS0 (no total deadline)Total turn budget
AGENTKIT_CODEX_IDLE_TIMEOUT_MS600000 (10 min, min 10000)Idle budget
AGENTKIT_CODEX_STREAM_IDLE_TIMEOUT_MS900000 (15 min, min 1000)SSE silence budget
AGENTKIT_CODEX_MODEL_IDLE_TIMEOUT_MSStream budget + 60 sLoopback model proxy silence budget
AGENTKIT_CODEX_MODEL_API_KEY—Injected into the child env only; never argv or user config
AGENTKIT_MANAGED_CODEX_APIresponsesresponses or chat-completions in the managed shape

Source: src/providers/codex-runtime.mjs:132-160, :189, src/managed-runtime-host.mjs:32-42, src/managed-runtime-definition.mjs:22-23.

Why the default budgets exceed Codex's own

Codex aborts a round after 300 seconds of SSE silence, while a managed business turn may keep streaming reasoning and report output far longer. Studio therefore pins a 15-minute per-round silence budget and keeps it deployment-tunable, and lets the loopback model proxy budget sit slightly above Codex's so the proxy never cuts a still-live upstream first (src/providers/codex-runtime.mjs:146-158).

Limits

LimitEffectSource
Workspace must be absoluteA relative path throws CODEX_WORKSPACE_INVALIDsrc/providers/codex-runtime.mjs:165-166
A Codex Agent must be boundUsing a Codex model unbound throws CODEX_AGENT_REQUIREDsrc/providers/dsh-runtime.mjs:588
A DSH workspace is requiredA session without cwd throws CODEX_WORKSPACE_UNAVAILABLEsrc/providers/dsh-runtime.mjs:620-621
The model needs a gateway addressA provider without a Codex interface throws CODEX_MODEL_PROVIDER_UNAVAILABLEsrc/providers/dsh-runtime.mjs:625-627
The official provider is requiredMissing or disabled throws CODEX_PROVIDER_UNAVAILABLEsrc/providers/dsh-runtime.mjs:630-634
No total deadline by defaultAGENTKIT_CODEX_TIMEOUT_MS=0 means only idle budgets bound the turnsrc/providers/codex-runtime.mjs:144
Invalid sandbox degradesAn invalid sandbox mode falls back to the runtime default instead of reaching Codexsrc/providers/codex-runtime.mjs:174

Sandbox and approval

Sandbox values share the execution-policy enum: read-only, workspace-write, danger-full-access (src/execution-policy.mjs:8). The managed default is workspace-write with a ceiling of danger-full-access (src/execution-policy.mjs:10-11), and a request may only narrow that ceiling, never exceed it (src/execution-policy.mjs:29-33).

In chat-completions mode web_search is explicitly disabled — hosted Responses tools have no Chat Completions equivalent (src/providers/codex-runtime.mjs:186-187).

Failure shapes

CodeTriggerWhat you can do
CODEX_AGENT_REQUIREDA Codex model was selected without binding a Codex AgentSet the Agent's runtime to Codex Agent first
CODEX_WORKSPACE_INVALIDThe working directory is not an absolute pathUse an absolute path
CODEX_WORKSPACE_UNAVAILABLEThe DSH session supplied no workspaceRe-select the workspace and reopen the session
CODEX_INPUT_INVALIDNeither text nor image input was providedType something before sending
CODEX_MODEL_PROVIDER_UNAVAILABLEThe current model provider has no Codex interfaceAdd the gateway address in model settings
CODEX_PROVIDER_UNAVAILABLEThe Codex App Server provider is not registeredInstall and enable the official Codex provider
CODEX_RUNTIME_FAILEDInternal app-server failureCheck the operations log; one retry is reasonable

Codex cancellation is cooperative: a local cancellation acknowledgement does not mean a remote tool stopped (the matrix in src/runtime-contract.mjs:30-34 declares cancel but no hard kill). Resource degradation rules are in degradation and retry.

Source of truth

ClaimLocation
Protocol boundary and thread ownershipsrc/providers/codex-runtime.mjs:1-8
Configuration resolutionsrc/providers/codex-runtime.mjs:127-160
Per-turn overrides and sandbox fallbacksrc/providers/codex-runtime.mjs:165-190
Executable resolutionsrc/providers/codex-command.mjs:29-42
Model provider idsrc/providers/codex-models.mjs:4
Route failure branchessrc/providers/dsh-runtime.mjs:588-634
Execution policy enum and narrowingsrc/execution-policy.mjs:8-33

On this page