createCodexHarness

Purpose and behavior

Create the Codex CLI preset without starting the CLI; createAgent({ harness, model }) binds it and rejects unsupported settings. It captures, resumes and forks conversations, accepts live steering through codex app-server and reasoning low to max, and rejects maxOutputTokens.

Complete example and detailed rules.

Parameters and properties

• settingsOptional
  CodexSettings | undefined
  Codex settings; model, reasoning and maxOutputTokens belong on createAgent() and are rejected here.
• settings.modelProviderOptional
  CodexModelProvider | undefined
  Custom Responses-compatible endpoint used instead of OpenAI. It requires a model name on createAgent() and accepts only usage authentication; both are checked when the agent is composed.
• settings.approvalReviewerOptional
  "user" | "auto_review" | undefined
  auto_review lets Codex’s automatic reviewer decide approval requests, with full file access. Otherwise headless runs bypass approvals and interactive sessions keep the CLI’s prompts.
• settings.authenticationOptional
  AgentAuthentication | undefined
  Credential selection: “account” (subscription login), “usage” (API key), { account: { file | key | variable } } or { usage: { key | variable } }. Codex rejects account key and variable and accepts only usage with modelProvider; unsupported forms fail when the agent is composed. Omitted, Outpost installs no credentials.
• settings.variablesOptional
  Readonly<Record<string, string>> | undefined
  Environment variables for this CLI’s commands, merged over .outpost/.env; a name also set by the sandbox provider fails with code configuration. Claude Code rejects CLAUDE_CODE_MAX_OUTPUT_TOKENS or MCP_TIMEOUT here when maxOutputTokens or startupTimeoutMs already sets it.
• settings.saveConversationsOptional
  boolean | undefined
  Save the native conversation after each turn, default true. false disables capture and cannot be combined with conversations.
• settings.conversationsOptional
  ConversationStore | undefined
  Conversation store used instead of the native one, such as createTransportConversations() over the agent’s format. A store of another format, or saveConversations: false, fails when the harness is created.
• settings.mcpServersOptional
  McpServers | undefined
  MCP servers keyed by name, passed on the command line: —mcp-config for Claude Code, -c overrides for Codex. Secrets stay variable references; an undeclared referenced variable fails before the agent starts.

Returns

CliHarness

Signature

export declare function createCodexHarness(
  settings?: CodexSettings,
): CliHarness;

Related contracts

• CliHarness
• CodexSettings