Codex SDK harness
Run supported OpenAI models with the managed Codex SDK harness in Orca Agent Engine.
The codex_sdk harness runs the Codex SDK agent loop with an OpenAI model. In separate mode, the SDK runs on the harness host and calls tools in the session sandbox. In colocated mode, its worker runs inside the sandbox. This is a different harness from the older codex CLI identifier.
colocated mode is not fully implemented in this release. Use separate, the default.
Get your registry endpoint
Registry endpoint
Examples on this page target your registry endpoint - the deployment host root, with no path
suffix. For CLI, set ORCA_REGISTRY_URL and exactly one of ORCA_ACCESS_TOKEN (Bearer) or
ORCA_API_KEY (x-api-key). For TypeScript SDK, set ORCA_BASE_URL / ORCA_API_KEY (Bearer).
To find the endpoint, see Connect to the registry.
Select this harness
Set metadata.harness when you create the agent. The example uses gpt-5.4, which is in the pinned Codex SDK model catalog:
ork agent create \
--name "repo-worker" \
--model gpt-5.4 \
--metadata harness=codex_sdkThe harness defaults to separate. Set metadata.mode to colocated on the agent if you want the SDK worker inside the sandbox. A self-hosted environment requires colocated. Both choices use the same harness identity; you cannot change an agent's harness after creation.
After configuring the Python SDK, pass the same harness metadata:
from orca import Orca
client = Orca()
agent = client.agents.create(
name="repo-worker",
model="gpt-5.4",
metadata={"harness": "codex_sdk"},
)The images embedded in ork local CLI v0.5.0 reject codex_sdk at agent creation. Follow the local tutorial to select the published Agent Engine v0.5.1 Registry and Harness images. Agent creation and request guardrail denial were verified with the v0.5.0 images, and v0.5.1 changes neither path; model replies require a configured OpenAI key or Gateway route.
Models and credentials
The harness accepts OpenAI models and reasoning effort levels in its pinned catalog. If the deployment exposes the runtime.runorca.ai/v1 group in GET /apis, GET /apis/runtime.runorca.ai/v1/harnesses lists its recognized models and levels. Catalog support does not grant access to a model; the deployment must configure credentials and model authorization.
In Cloud separate mode, the harness host can call the provider directly with its configured OpenAI key, or use Orca AI Gateway when the deployment or session selects Gateway egress. Cloud colocated mode uses a session-scoped Gateway token rather than putting the provider key in the sandbox. The Gateway path requires an OpenAI Responses route and permission for the selected model.
Capabilities and limits
Codex SDK tool calls go through the session's managed tools and permission policies. The harness supports managed skills, remote MCP tools, client custom-tool callbacks, interruption, and native conversation recovery across worker restarts. Its model usage is recorded from the SDK.
The harness does not support multiagent rosters or multimodal user input. Request budgets are checked between turns; they do not stop spending partway through a model turn. Soft budget approvals and stateful tool-phase guardrails are unsupported. In separate mode, the harness enforces stateless request, tool_call, and tool_result guardrails, and stateful guardrails at request only. colocated mode does not fully support guardrails yet. A rule the harness cannot enforce stops the session from starting; see Guardrail enforcement.