Remote Connections docs contradict the new `codex remote-control pair` CLI workflow

Open 💬 0 comments Opened Jul 29, 2026 by lbudzynowski

Documentation issue

The current Remote connections documentation says that:

  • Remote hosts must run the ChatGPT desktop app on macOS or Windows.
  • Mobile setup cannot be started from the Codex CLI or IDE extension.
  • Setup must start in the desktop app.

Source: https://developers.openai.com/codex/remote-connections

However, the current Developer commands documentation now explicitly documents an experimental CLI/headless workflow:

codex remote-control start
codex remote-control pair

It says that start launches the local app-server daemon with Remote Control enabled and that pair prints a short-lived manual pairing code. The JSON output includes pairingCode, manualPairingCode, environmentId, and expiresAt.

Source: https://developers.openai.com/codex/developer-commands#codex-remote-control

Why this is confusing

A Linux or headless host now appears to have an officially documented pairing path through Codex CLI, but the primary Remote Connections guide still tells users that this is impossible and requires the macOS/Windows desktop app.

This is particularly confusing for users following issue #31183, which requested exactly the codex remote-control pair command that is now documented.

Suggested fix

Please update the Remote Connections guide to distinguish between:

  1. The stable desktop-app setup flow for macOS and Windows.
  2. The experimental Codex CLI/headless flow, including Linux, using codex remote-control start followed by codex remote-control pair.

It would also help to document the runtime requirements for CLI hosts, especially that the host must remain awake, online, authenticated, and keep the remote-control daemon running.

If the CLI pairing workflow is not intended to be supported on Linux/headless hosts despite the Developer Commands page, please state its actual platform/support limitations explicitly on both pages.

View original on GitHub ↗