HeyRocky

Run OpenAI Turns Through the Codex App-Server Runtime

Hermes can optionally hand openai/* and openai-codex/* turns to the Codex CLI app-server instead of running the normal Hermes tool loop. Hermes remains the outer shell for sessions, gateway delivery, skills, memory review, and slash commands, while Codex owns the model turn, sandbox, shell, patching, planning, and its native plugins.

This runtime is opt-in. Hermes does not silently move ordinary sessions onto it, and non-OpenAI providers continue to use the default runtime.

Decide whether the runtime fits

Use the Codex app-server path when ChatGPT subscription authentication, the Codex sandbox, or native Codex plugins are important to the workflow. Stay on the default Hermes runtime when a turn needs agent-loop tools that the stateless callback cannot provide, including delegate_task, direct memory writes, session_search, or the Hermes todo store.

The two runtimes also expose different tool surfaces. Codex supplies its own shell, apply_patch, update_plan, view_image, and web search. Hermes exposes selected richer tools back to Codex through an MCP callback, including browser automation, web extraction, vision, image generation, skills, and text to speech.

Readiness checklist

  • Install a current Codex CLI and complete its normal authentication flow.
  • Verify a direct Codex CLI request before involving Hermes.
  • Enable model.openai_runtime: codex_app_server only in the intended profile.
  • Keep the default sandbox at the documented workspace-safe level unless a narrower policy is required.
  • Confirm the selected model uses the OpenAI or OpenAI Codex provider family.
  • Inventory which task-critical tools come from Codex, native plugins, or the Hermes MCP callback.
  • Keep workflows that require delegate_task, memory, session_search, or Hermes todo on the default runtime.
  • Test one read, one patch, one denied command, and one callback tool before unattended use.
  • Record the rollback command and verify a fresh session after switching runtimes.
model:
  openai_runtime: codex_app_server

Use /codex-runtime auto to switch back to Hermes' normal runtime for the current session, or change the profile configuration and start a fresh session for a durable rollback.

Understand the boundary

Codex runs terminal and file work inside its own sandbox. User-installed Codex plugins are managed and authorized by Codex, then surfaced inside the runtime. Hermes registers a local MCP callback for supported Hermes tools that Codex does not provide natively.

That bridge does not turn every Hermes tool into a stateless MCP tool. Features that require access to the active AIAgent loop remain unavailable inside the Codex-owned turn. Persistent goals and Kanban can work through their surrounding Hermes orchestration, but the exact tool availability inside a worker still follows the runtime boundary. Treat cron compatibility as workflow-specific and test the actual scheduled job before relying on it.

Approval and sandbox discipline

Do not equate a successful Codex login with broad filesystem authority. Workspace roots, network access, command approvals, and plugin permissions remain separate controls. A Kanban worker may receive narrowly added writable roots for its board and workspace; that exception should not become a general no-sandbox policy.

When approvals are required, verify allow-once, denial, and timeout behavior. Long-running goals can create more approval prompts because each continuation is a fresh Codex turn.

Common pitfalls

  • Assuming every OpenAI turn is automatically routed to Codex. The feature is opt-in and provider-scoped.
  • Expecting Hermes agent-loop tools inside the callback. delegate_task, memory, session_search, and Hermes todo are not available there.
  • Confusing Codex plugins with Hermes plugins. They have separate installation, authorization, and lifecycle controls.
  • Using a danger-level sandbox to fix a path mistake. Add only the documented writable root instead.
  • Testing chat but not tools. A model response does not prove patching, approvals, plugins, or callbacks work.
  • Changing the runtime mid-task without a fresh verification turn. Session state and tool expectations can otherwise become confusing.

Verification steps

  1. Run a direct Codex CLI request and confirm the expected account and model.
  2. Enable the app-server runtime in a test profile and start a fresh Hermes session.
  3. Read and patch a disposable file inside the allowed workspace.
  4. Trigger a command that requires approval; test allow-once and denial.
  5. Call one native Codex tool, one installed Codex plugin if used, and one Hermes callback tool.
  6. Confirm a required unavailable agent-loop tool is handled by switching back rather than failing unpredictably.
  7. Inspect session history after restart and verify tool events remain understandable.
  8. Switch to /codex-runtime auto, start a fresh turn, and confirm the normal Hermes runtime is restored.

Use the official Hermes documentation for the current source of truth.

Related pages