›_ Codex Issues
Codex Issues / #31183

Headless Linux CLI remote-control has no supported re-pair/add path after Desktop/mobile moved to QR/PIN flow

Open 💬 3 comments Opened Jul 5, 2026 by biaobiaobiao108
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What issue are you seeing?

A previously working headless Linux/VPS Codex CLI remote-control setup can no longer be re-added from current Codex Desktop / ChatGPT mobile clients.

The Linux side can run the remote-control app server and appears to connect to the remote-control backend, but the current Mac/iOS add flow only offers QR/PIN-style pairing intended for Codex Desktop hosts. The Linux CLI does not expose a matching pair, add, pin, or QR-code command, so there is no apparent supported path to re-pair a headless Linux CLI remote-control environment.

This is similar to #30637 and related to the remote SSH/mobile confusion in #23699, but this report is specifically about the missing migration/re-pair path for an existing headless Linux CLI remote-control setup.

Why this matters

The old behavior was extremely useful for always-on VPS workflows: start Codex remote-control on the VPS, then use Codex from Mac/iOS to connect to that always-on environment. After the newer Desktop/mobile pairing flow, that workflow appears stranded: the server can be online, but current clients cannot add it again.

Environment

Controller clients:

  • macOS Codex Desktop: recently updated, current UI uses Settings > Connections > Control other devices > Add
  • ChatGPT/Codex on iOS: recently updated, current UI expects QR scan or pairing code

Remote host:

  • Headless Linux VPS over SSH
  • Codex CLI: codex-cli 0.142.5
  • Codex is available in the login shell PATH
  • Remote process can be launched under a supervisor/daemon as:
codex app-server --remote-control --listen unix://

The process establishes an outbound HTTPS connection to the remote-control relay/backend and listens on the local app-server control socket.

Steps to reproduce

  1. On a headless Linux host, install/authenticate Codex CLI.
  2. Start remote control with the CLI/daemon path, for example:
codex remote-control start

or run the equivalent app-server process:

codex app-server --remote-control --listen unix://
  1. Verify the Linux process is running and connected.
  2. On current macOS Codex Desktop, open Settings > Connections > Control other devices and click Add.
  3. Observe that the UI expects a QR/PIN flow for another Mac/PC Codex Desktop app.
  4. On Linux, inspect the CLI help:
codex remote-control --help
codex remote-control start --help
  1. Observe there is no matching pair, add, pin, or QR-code command on the Linux CLI side.

Actual behavior

  • The headless Linux remote-control daemon/app-server can be running and connected.
  • Current Mac/iOS clients do not show a usable way to add/re-pair that Linux host.
  • The client-side Add flow expects a pairing code/QR flow that the Linux CLI does not expose.
  • Official remote connection docs say mobile setup starts from Codex App and cannot be set up from CLI or IDE Extension, but there does not appear to be a migration path for existing CLI remote-control users.

Expected behavior

One of these should exist:

  • A supported CLI command for headless Linux hosts, such as codex remote-control pair, codex remote-control add, or codex remote-control start --pair, that prints a QR code or pairing code compatible with the current Desktop/mobile add flow.
  • Or Codex Desktop should support re-adding a connected headless Linux CLI remote-control environment by environment id/account authorization.
  • Or the documentation/UI should clearly state that headless Linux CLI remote-control is no longer supported for new/re-paired mobile/Desktop connections, and explain the intended replacement workflow.

Current CLI output

codex remote-control --help only exposes:

Commands:
  start  Start the app-server daemon with remote control enabled
  stop   Stop the app-server daemon
  help   Print this message or the help of the given subcommand(s)

codex remote-control start --help also does not expose pairing/add/PIN options.

Additional context

The officially documented current mobile flow appears to require a macOS/Windows Codex App host to initiate QR pairing. That works for Desktop hosts, but it leaves always-on Linux/VPS remote-control users without a way to restore the old workflow after app/client updates or stale pairings.

View original on GitHub ↗

3 Comments

github-actions[bot] contributor · 1 month ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #30637
  • #31117

Powered by Codex Action

mjzcng · 1 month ago

I ran into the same gap with a headless/Linux Codex CLI host after the mobile/Desktop flow moved to QR/manual-code pairing.

I put together a small workaround script here: https://github.com/mjzcng/codex-cli-mobile-pairing

It starts codex app-server --stdio, initializes the app-server client with experimentalApi: true, then calls the public experimental app-server methods:

  • remoteControl/enable
  • remoteControl/pairing/start with manualCode: true
  • remoteControl/pairing/status

On codex-cli 0.142.5, this produced a manualPairingCode that ChatGPT mobile was able to claim successfully for a CLI-hosted environment.

This is not a replacement for an official supported CLI command, but it may help confirm that the missing piece is mostly CLI exposure of the pairing flow rather than the remote-control backend itself.

mpashka · 1 month ago

Additional reproduction from Linux CLI + ChatGPT Android:

Environment:

  • OS: Linux
  • Codex CLI: codex-cli 0.142.5
  • ChatGPT Android: current/latest available to the user

Observed CLI behavior:

$ codex remote-control
Starting app-server with remote control enabled...
This machine is available for remote control as yp-x1.
Press Ctrl-C to stop.

Actual result:

  • No QR code is printed.
  • No manual pairing code is printed.
  • ChatGPT Android's Remote Connections flow still asks to scan a QR code.
  • The Linux machine is not discovered automatically.

Local CLI checks:

$ codex remote-control --help
[experimental] Manage the app-server daemon with remote control enabled

Usage: codex remote-control [OPTIONS] [COMMAND]

Commands:
  start  Start the app-server daemon with remote control enabled
  stop   Stop the app-server daemon
  help   Print this message or the help of the given subcommand(s)

codex remote-control start --help exposes only common config/json/feature flags; I could not find any pair, qr, pin, add, pairing, or manual-code subcommand.

Additional investigation:

  • Current official docs at https://developers.openai.com/codex/remote-connections say mobile setup supports Codex App hosts on macOS and Windows.
  • The same docs say mobile setup starts from the Codex App and cannot be set up from the Codex CLI or IDE Extension.
  • Source inspection shows backend pairing response fields such as pairing_code and manual_pairing_code in codex-rs/app-server-transport/src/transport/remote_control/enroll.rs, but the Linux CLI command appears to expose only daemon enablement, not the pairing UX.

This makes the user-facing failure mode confusing: the CLI says the machine is available for remote control, but the only documented mobile setup path requires a Codex App QR flow that Linux CLI cannot initiate.

Suggested behavior if Linux CLI pairing is unsupported:

  • Do not print "This machine is available for remote control" in a way that implies mobile pairing is possible.
  • Print a clear unsupported-flow message and link to the Remote Connections docs.

Suggested behavior if Linux CLI pairing is intended:

  • Add a supported command such as codex remote-control pair that starts a pairing session and prints a terminal QR code and/or manual pairing code compatible with ChatGPT mobile.