app-server

agent-canvas

app-server

app-server

sandbox-server

app-server

agent-server

app-server

It is one Codex process versus several Codex processes.

  Direct Codex app-server:

  Conversation A ─┐
  Conversation B ─┼─> one Codex app-server
  Conversation C ─┘       └─ one AuthManager
                             └─ one refresh lock
                                 └─ auth.json

  All conversations use the same in-memory authentication manager. If A refreshes, B waits; afterward B reloads the new credentials and skips its own refresh. Only one process writes auth.json.

  Local Docker with OpenHands ACP:

  Conversation A -> codex-acp A -> Codex app-server A -> refresh lock A ┐
  Conversation B -> codex-acp B -> Codex app-server B -> refresh lock B ├-> shared auth.json
  Conversation C -> codex-acp C -> Codex app-server C -> refresh lock C ┘

  Each OpenHands conversation launches a separate codex-acp, and each adapter launches its own codex app-server. The locks are therefore independent. codex-acp process creation
  (<https://github.com/agentclientprotocol/codex-acp/blob/v1.1.2/src/CodexJsonRpcConnection.ts#L15-L42>)

  Even with the OpenHands broker:

  1. A and B both load refresh token r0.
  2. The broker safely rotates r0 → r1 only once.
  3. Both Codex processes receive r1.
  4. Both independently truncate and rewrite the same auth.json.
  5. One process can read the file while it is empty or partially written.

  The broker protects the logical token rotation, but not the subsequent filesystem writes. Codex currently performs those writes without an inter-process lock or atomic replacement. Codex file-auth implementation
  (<https://github.com/openai/codex/blob/rust-v0.144.6/codex-rs/login/src/auth/storage.rs#L191-L223>)

  One important qualification: if by "backend agent-server directly" you mean an OpenHands agent-server started natively that still creates one ACP subprocess per conversation, then it is not safer. It has the same problem. Sharing is safe only
  when one Codex app-server process owns the home and multiplexes all conversations—and no separate CLI/login/logout process writes there concurrently.

Current topology:

  Default local Docker
    conversation A container
      OpenHands agent-server → ACPAgent A → codex-acp A → Codex app-server A
    conversation B container
      OpenHands agent-server → ACPAgent B → codex-acp B → Codex app-server B

  Direct OpenHands agent-server
    one OpenHands agent-server
      ACPAgent A → codex-acp A → Codex app-server A
      ACPAgent B → codex-acp B → Codex app-server B

  Local Docker defaults to NO_GROUPING, which deliberately creates a new sandbox/container for every conversation. The setting defaults to NO_GROUPING
  (<https://github.com/OpenHands/OpenHands/blob/7db8bd4d92d6db33816cb534799b0bb618bbb7de/openhands/app_server/settings/settings_models.py#L605-L693>), and the Docker sandbox service then starts a separate container
  (<https://github.com/OpenHands/OpenHands/blob/7db8bd4d92d6db33816cb534799b0bb618bbb7de/openhands/app_server/sandbox/docker_sandbox_service.py#L385-L495>).

  A directly run OpenHands agent-server can host multiple conversations, but that does not mean one Codex process. Every conversation gets its own ACPAgent, and each ACPAgent owns and spawns its own ACP subprocess
  (<https://github.com/OpenHands/software-agent-sdk/blob/68aa583ebf07efefbb9219b63859c1aacecaf7b3/openhands-sdk/openhands/sdk/agent/acp_agent.py#L1668-L1674>). The launch happens once per agent instance
  (<https://github.com/OpenHands/software-agent-sdk/blob/68aa583ebf07efefbb9219b63859c1aacecaf7b3/openhands-sdk/openhands/sdk/agent/acp_agent.py#L2333-L2470>). Therefore, sharing ~/.codex from a direct agent-server is also unsafe when multiple
  Codex conversations run concurrently.

  Could Docker use one Codex process? Yes, architecturally. The upstream adapter already supports it:

  - One codex-acp process starts exactly one Codex app-server (<https://github.com/agentclientprotocol/codex-acp/blob/v1.1.2/src/index.ts#L71-L127>).
  - It maintains multiple session states keyed by session ID (<https://github.com/agentclientprotocol/codex-acp/blob/v1.1.2/src/CodexAcpServer.ts#L145-L173>).
  - It explicitly tests independent sessions and concurrent prompts (<https://github.com/agentclientprotocol/codex-acp/blob/v1.1.2/src/__tests__/CodexACPAgent/CodexAcpClient.test.ts#L917-L1022>).

  But simply enabling sandbox grouping or pointing every conversation at one CODEX_HOME does not accomplish that. OpenHands would need a sandbox-owned Codex/ACP manager instead of conversation-owned subprocesses. It must also route events,
  approvals, cancellation, masking and teardown by session. More importantly, OpenHands currently injects each conversation's entire secret registry into that conversation's subprocess environment. A shared process would mix conversation-
  specific secrets unless that mechanism were redesigned.

  Default Docker isolation creates another constraint: a Codex process inside container A cannot operate on container B's filesystem and runtime. A shared process therefore requires grouped conversations in the same sandbox, or a much larger
  remote-execution design.

  There is also a subtle Codex 0.144.6 caveat: one app-server shares its main AuthManager across threads and serializes its refreshes, but it also constructs a separate auth manager for its background cloud-config loader. Meanwhile, file
  storage rewrites auth.json using truncate-and-write without a file lock (<https://github.com/openai/codex/blob/rust-v0.144.6/codex-rs/login/src/auth/storage.rs#L191-L218>). So one process substantially reduces the conversation-driven race, but
  it is not yet a complete storage-safety guarantee.

  My conclusion:

  - Do not point current local-Docker conversations at a shared CODEX_HOME.
  - Do not consider direct OpenHands agent-server sharing safe either; it currently launches multiple Codex processes.
  - Keep the per-conversation homes and broker work for the current PR.
  - A future simplification should be a sandbox-scoped, multi-session Codex process for grouped, same-user conversations—with session-scoped secrets and lifecycle routing. That is a separate architectural change, not a small replacement for the
    broker.

Fixing this by having one ground truth somewhere and a credential broker handling sync with several processes , whether its local / docker / saas, seems like the only way forward

This sounds to me like, we already added a lot of complexity, the only way forward is to add more ?

Multiple codex auth.json files in conversations logs… doesn’t fit with the goal of 15298 🤔