Codex Desktop private stdio app-server is unreachable to external clients

[hitsmaxft]

Summary

Codex App Server exposes structured thread control, including turn/steer and turn/interrupt, and supports both stdio and Unix-socket transports. However, a Codex Desktop-owned thread is currently hosted by a private stdio app-server process that external clients such as codex-bridge cannot connect to.

As a result, the protocol supports interruption, but an external local integration cannot interrupt or steer the active turn that the Desktop app actually owns.

Official protocol reference: https://developers.openai.com/codex/app-server

Observed environment

• macOS
• Codex Desktop 26.820.60940
• Observation date: 2026-08-29
• External client: codexapp-cli / codex-bridge
• Shared control socket used by the bridge: ~/.codex/app-server-control/app-server-control.sock

This version scope is a local observation, not a claim that every Codex Desktop version is affected.

Reproduction

1. Start Codex Desktop and open a thread.
2. Start work in that thread so it has an active turn.
3. Inspect the local process topology: Desktop starts its own app-server over private stdio.
4. Connect an external client to the shared Unix-socket app-server and complete the initialize / initialized handshake.
5. Send turn/interrupt with the Desktop thread ID and active turn ID (the current bridge uses codex app-server proxy --sock PATH).
6. The request cannot control the Desktop-owned turn because that thread belongs to the separate private stdio server.

The same ownership split prevents a true same-turn turn/steer. Falling back to codex exec resume is only a follow-up operation and may fail with an active-writer conflict.

Expected behavior

Codex Desktop should provide a documented, supported way for an authorized local client to control the same app-server instance that owns the Desktop thread. For example, Desktop could:

• honor a documented configuration that connects it to a shared local app-server;
• expose a local-only authenticated Unix socket for its app-server; or
• document another supported attachment/control endpoint for Desktop-owned threads.

Then an external client could use the protocol's existing turn/steer and turn/interrupt methods without taking over the thread writer.

Actual behavior

The Desktop app-server is private to the Desktop process over stdio. The shared socket is a different server instance, so structured control requests cannot reach the active Desktop turn.

codexapp-cli therefore reports an explicit app_server_unavailable / app_server_rejected failure. It deliberately does not queue a textual /stop and report success, because that would not prove the turn was interrupted.

Impact

• No reliable external interruption of a Desktop-owned turn.
• No true same-turn steering from codex-bridge.
• Approval/control integrations cannot share the Desktop app-server session.
• codex exec resume is not an equivalent replacement and can conflict with active-writer ownership.
• Local hardware workflows that need an external controller must use a separate, tightly allowlisted host executor rather than app-server control.

Evidence boundary

Confirmed locally:

• Rollout state provides the active thread and turn IDs.
• The installed app-server schema supports turn/steer and turn/interrupt.
• The Desktop-owned thread is not controllable through the shared socket.
• Failure is reproduced without sending UI events or taking over the writer.

Not yet confirmed:

• Whether Codex Desktop has an undocumented supported control endpoint.
• The first affected Desktop version or whether platforms other than macOS are affected.
• Whether the behavior is intentional isolation or a regression.

Security considerations

Any shared control endpoint should remain local-only, require restrictive filesystem permissions (for example 0600 on a Unix socket), and preserve app-server initialization/authentication boundaries. This request is for structured thread control, not an unauthenticated arbitrary host-command channel.

Project references

• Architecture and observed regression: https://github.com/hitsmaxft/codexapp-cli/blob/main/DESIGN.md
• Current interrupt behavior: https://github.com/hitsmaxft/codexapp-cli/blob/main/README.md
• Reproduction and error semantics: https://github.com/hitsmaxft/codexapp-cli/blob/main/DEBUGGING.md

[hitsmaxft]

2026-08-31 investigation update

The original reproduction conflated two separate problems. The standalone daemon was not rejecting InitializeParams or client identity. The request never reached JSON-RPC.

Confirmed transport root cause in Codex CLI 0.151.0

• The Unix control-socket acceptor immediately calls tokio_tungstenite::accept_async, so the socket transport is WebSocket over UDS, including an HTTP Upgrade handshake:
  https://github.com/openai/codex/blob/rust-v0.151.0/codex-rs/app-server-transport/src/transport/unix_socket.rs
• codex app-server proxy only copies raw stdin bytes to the Unix stream and raw socket bytes to stdout. It does not perform WebSocket Upgrade or frame conversion:
  https://github.com/openai/codex/blob/rust-v0.151.0/codex-rs/stdio-to-uds/src/lib.rs
• The Codex daemon own working client connects to the UDS with client_async("ws://localhost/", stream) and sends JSON-RPC in WebSocket text frames:
  https://github.com/openai/codex/blob/rust-v0.151.0/codex-rs/app-server-daemon/src/client.rs

Therefore raw JSONL sent through app-server proxy is parsed as an invalid WebSocket handshake and the listener closes the connection before initialize. remoteControlEnabled=true is unrelated to this local transport behavior.

codexapp-cli fix and validation

The bridge now connects directly with WebSocket-over-UDS, sends initialize and initialized, and then sends turn/steer or turn/interrupt as text frames. The fake proxy path was removed and replaced by a real local WebSocket UDS test server.

Validation completed locally:

• read-only live probe against the standalone daemon: WebSocket Upgrade + initialize + thread/loaded/list passed;
• isolated live write test created a brand-new temporary-cwd thread, started a turn, and sent turn/steer from a second connection;
• the steer RPC succeeded, and the same turn rollout recorded the injected STEER_ACCEPTED user input before completing with READY;
• build, Clippy with warnings denied, workspace tests, and isolated fixture CLI smoke tests passed.

No pre-existing project thread was used for the live test.

Desktop GUI boundary

Desktop 26.820.60940 still owns a separate private stdio app-server. Its bundled codex_app MCP advertises create_thread, send_message_to_thread, fork_thread, and related tools, but the GUI host pipe is private, approval-routed, and rejects an external tools/list connection by closing the pipe. It is not a documented attachment endpoint and codexapp-cli will not bypass its peer/code-signing boundary.

Result: true same-turn steer now works for threads owned by the standalone/shared daemon. Desktop-owned GUI threads remain unreachable until Desktop exposes a supported attachment/control endpoint or again shares the managed daemon.