Guide

Codex CLI remote control: mobile app, cloud and status pad

Updated

On this page

In the Codex CLI, codex remote-control runs remote control for the local app-server daemon and prints short-lived pairing codes. The --remote flag connects the terminal UI to an app server over WebSocket or a Unix socket. To control a Mac or Windows computer from your phone, you start setup in the ChatGPT desktop app, not in the CLI. For work that keeps going while your computer sleeps, you use Codex Cloud.

Logitech MX Creative Keypad running Orbtile with a Codex session waiting for approval

Ways to control or connect to Codex CLI remotely

OpenAI splits remote access across the Codex CLI, the ChatGPT desktop and mobile apps, and Codex Cloud.

Remote pathWhere you set it upCommands or settingsWhat it does
Local daemonCodex CLIcodex remote-control, start, stop, pairRuns remote control for the local app-server daemon and prints short-lived pairing codes
App-server clientCodex CLIcodex --remote, codex app-server --listenConnects the TUI and supported session commands to an app server
Mobile or desktop controlChatGPT desktop app on macOS or WindowsSettings > Connections > Control this Mac or PC, then a QR scanLets a phone or another desktop send prompts and approvals to the host
SSH and HandoffChatGPT desktop app and ~/.ssh/configSettings > Connections, the chat footerRuns Codex on an SSH host and moves a chat and its Git state between hosts
Codex CloudCodex CLIcodex cloud, exec, list, codex applyRuns tasks in the cloud while your computer sleeps, then applies the diff locally
Orbtile status padOrbtile on a Mac or a PC with Windows 11Orbtile settingsShows Codex sessions on a keypad or phone and answers supported approvals

See OpenAI Codex: CLI, desktop app, IDE extension and setup.

Manage the local daemon with codex remote-control

codex remote-control is Experimental. Managed remote-control clients and SSH remote workflows use it. It is not a replacement for codex app-server --listen when you build a local protocol client.

codex remote-control
codex remote-control --no-daemon
codex remote-control start
codex remote-control stop
codex remote-control pair --json
  • The bare command uses the managed background server when it can, and falls back to the foreground.
  • --no-daemon runs in the foreground and works only on the bare command, not on start, stop or pair.
  • start turns on remote control for the local app-server daemon, and stop stops it.
  • pair prints a short-lived manual pairing code.
  • --json works on every remote-control command.
  • With pair --json, the output includes pairingCode, manualPairingCode, environmentId and expiresAt.

Turn off device remote control for a workspace

Admins can turn off device remote control with allow_remote_control = false. For cloud-managed users, set it with Edit as TOML in Agent security, in the Global requirements.toml. Device-managed clients can use a supported local requirements source instead. The setting does not turn off SSH remote connections.

Connect the TUI to an app server with --remote

Running codex opens the interactive terminal UI (TUI). Add --remote to attach it, or a supported session command, to an app server.

codex app-server --listen ws://IP:PORT
codex --remote ws://host:port
codex --remote wss://host:port --remote-auth-token-env <ENV_VAR>
codex --remote unix://
  • --remote accepts ws://host:port, wss://host:port, unix:// and unix://PATH.
  • Only codex, agents, queue, resume, fork, archive, delete and unarchive accept --remote.
  • --remote-auth-token-env reads a bearer token from an environment variable when you connect with --remote.
  • Codex sends the token only over wss:// or local-only ws:// URLs.
  • The global --no-daemon flag cannot be combined with --remote or codex agents.

Start and secure a codex app-server listener

codex app-server is Experimental. It is mainly for development and debugging, and may change without notice.

  • --listen takes stdio://, ws://IP:PORT, unix://, unix://PATH or off.
  • --stdio is short for --listen stdio:// and cannot be used with --listen.
  • --ws-auth takes capability-token or signed-bearer-token.
  • Without --ws-auth, WebSocket auth is off, and non-local listeners warn at startup.
  • Capability tokens use --ws-token-file or an expected digest in --ws-token-sha256.
  • Signed bearer tokens need --ws-shared-secret-file.
  • For wss:// clients, use TLS termination or a secure proxy.

Browse, queue and resume sessions on a remote server

These Stable commands also work with a --remote server.

  • codex agents opens the agent command centre on a shared local or remote server.
  • With codex agents, --cd sets the folder for new remote tasks.
  • codex queue adds a message to an existing session, found by UUID or exact name with --thread.
  • codex queue --resume also resumes the session if it isn't loaded.
  • codex resume continues a chat by ID, and --last picks the most recent chat in the current folder.
  • Add --all to codex resume to include chats from other folders.
  • codex archive and codex unarchive also act on the subagent sessions a session spawned.
  • codex delete removes a session permanently, and --force skips the prompt only when you give a UUID.

Control a Mac or Windows computer from the ChatGPT mobile app

Remote connections in the ChatGPT mobile app for iOS and Android reach a Mac or Windows computer running the ChatGPT desktop app. Setup starts in the desktop app. You can't set it up from the Codex CLI or the IDE extension. From a terminal, codex app [PATH] launches the desktop app. See Codex app vs Codex CLI: desktop app and terminal compared.

What you can do from your phone and what stays on the host

A secure relay keeps the host reachable without exposing it directly to the public internet.

  • Start or continue chats in projects on the host, and switch between hosts and chats.
  • Send follow-ups, answer questions, steer active work and approve commands.
  • Review diffs, test results, terminal output and screenshots.
  • Get notified when a task finishes or needs your attention.
  • Repository files, local documents and shell commands come from the host.
  • MCP servers, skills, browser access and Computer Use come from the host's configuration.
  • Sandboxing, security controls and approval settings still apply.

Pair your phone with the desktop app by QR code

You need Codex access in your ChatGPT account and workspace. You also need the latest ChatGPT mobile app and the latest ChatGPT desktop app on a macOS or Windows host. The host must be awake, online and signed in to the same account and workspace. In a workspace, your admin may need to turn on Remote Control access first.

  • In the host's desktop app, open Settings > Connections > Control this Mac or PC and select Set up or Add.
  • Approve remote access and complete any requested verification.
  • Scan the QR code with your phone, then confirm the same account and workspace.
  • Complete any MFA, SSO or passkey steps.
  • Pair each phone with each host it will control.
  • If you haven't used a connection since 8 June 2026, update both apps and pair again.

Keep the host awake and reachable

Remote access needs the host awake and online.

  • Use Settings > Connections on the host to manage connected devices.
  • Keep the host plugged in and turn on Keep this Mac awake.
  • A Mac laptop stays reachable with the lid open on power, or closed with an external display connected.
  • Choosing Sleep on the Mac stops remote access.
  • On Windows, keep the session unlocked for tasks that use Computer Use.
  • Signing out turns off Remote Control but keeps your existing pairings.
  • Use Control other devices in the same settings to add another host to control from this desktop.

SSH hosts, Handoff and Codex Cloud

Connect the ChatGPT desktop app to an SSH host

The ChatGPT desktop app can open remote projects over SSH. Add a concrete host alias to ~/.ssh/config, because Codex ignores pattern-only hosts.

Host devbox
  HostName devbox.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519
  • Install Codex on the remote host.
  • Make sure the codex command is on the remote host's PATH.
  • To reach a machine outside your network, use a VPN or mesh network rather than exposing the app server to the internet.

Hand off a chat between your computer and a remote host

Handoff moves an existing chat and its Git state between your computer and a connected remote host. Handoff to a Codex cloud environment isn't supported.

  • Select the destination in the chat footer, or This computer to bring a remote chat back.
  • Codex creates or reuses a worktree on the destination host.
  • Codex interrupts any running response before the move.

Run and apply Codex Cloud tasks from the terminal

Codex Cloud runs coding tasks in the cloud, so work continues while your computer sleeps. On the web or in the desktop app, choose Work in > Cloud. On mobile, open Codex. Plus and Edu Plus plans get 2 vCPUs, 8 GiB of memory and 8 GiB of disk. Pro, Business, Enterprise, Edu and Edu Pro get 4 vCPUs, 16 GiB of memory and 32 GiB of disk. By default, a task's saved state can be recovered for up to seven days after you last start a turn or resume it.

From the terminal, use codex cloud (Experimental) and codex apply (Stable, alias codex a).

CommandOptionsWhat it does
codex cloudNoneOpens an interactive picker
codex cloud exec--env <ENV_ID> (required), --attempts from 1 to 4Submits a task to a cloud environment, with optional best-of-N attempts
codex cloud list--env, --limit from 1 to 20, --cursor, --jsonLists recent tasks
codex apply <TASK_ID>TASK_IDApplies the latest diff from a cloud chat to your local working tree and prints the patched files

Notifications and hooks for unattended terminal turns

Put alerts in your user-level ~/.codex/config.toml. Codex ignores notify in a project-local .codex/config.toml and prints a startup warning.

  • notify runs an external program on agent-turn-complete and passes it one JSON argument.
  • tui.notification_method takes auto, osc9 or bel.
  • tui.notification_condition takes unfocused or always.
  • Hooks in hooks.json or under [hooks] in config.toml run scripts or MCP tools on events such as PermissionRequest and Stop.
  • Codex skips new or changed non-managed hooks until you review and trust them with /hooks.

See Codex notifications for finished turns and approvals.

Watch and answer Codex sessions on a keypad or phone with Orbtile

Logitech's MX Keypad page lists OpenAI Codex among the AI tools its keys can work with. Logitech's software for MX Keypad needs Logi Options+ 2.07 or later on Windows 10 or later, or macOS 13 or later. Windows on ARM64 is not supported. In Logi Options+, the Keyboard Shortcut action maps keys to keyboard shortcuts.

Orbtile takes a different approach. It drives the nine LCD keys and two page buttons of the Logitech MX Creative Keypad over USB, without Logi Options+. Orbtile Mobile shows the same sessions on an iPhone with iOS 17 or later, or an Android phone with Android 8.0 or later, over your local network. Orbtile runs on a Mac with Apple silicon and macOS 14.0 or later, or a Windows 11 PC (x64).

  • Nothing to install: Orbtile reads Codex thread files and Codex's own signals.
  • Desktop threads, terminal codex sessions and codex exec runs all show as Codex.
  • Working sessions glow cool blue, and waiting or permission states glow magenta-violet and move to the front.
  • Tap key 9 to focus the first waiting session, including on other pages.
  • A short press on a session key opens its window, and a 0.6-second hold opens Focus mode.
  • Compatible Codex desktop command approvals offer Deny and Allow on the keys.
  • Supported desktop multiple-choice questions can be answered on the keys.
  • Terminal command approvals offer Allow only, so decline one in the terminal.
  • Other requests show Answer on computer.
  • In Settings > Agents > Codex > Native waiting, Terminal engine address accepts a unix:// socket or a ws://127.0.0.1:port listener.
  • For example, run codex app-server --listen ws://127.0.0.1:4500, start work with codex --remote on the same address, and set that address in Orbtile.
  • Leave Terminal engine address blank to use Codex's default socket, and restart Orbtile after changing it.
  • For an SSH host, choose Install Codex Hooks from the host's menu in Remote Hosts, which needs Python 3 on the host.
  • Then enter /hooks in Codex on the host and trust the 12 Orbtile hooks.
  • Remote keys are display-only, except Allow for Codex terminal command approvals.

See Watch Claude Code and Codex running on a remote server over SSH.

FAQ

Can I set up ChatGPT mobile remote access directly from the Codex CLI?

No. Setup starts in the ChatGPT desktop app on the Mac or Windows host, under Settings, Connections, Control this Mac or PC. You then scan a QR code with the ChatGPT mobile app. You can't set it up from the Codex CLI or the IDE extension, but codex app opens the desktop app from a terminal.

What do codex remote-control and the --remote flag do in the Codex CLI?

codex remote-control start and stop turn remote control on and off for the local app-server daemon. codex remote-control pair prints a short-lived manual pairing code. The --remote flag connects the terminal UI and supported session commands to an app server over ws://, wss:// or unix://. Add --remote-auth-token-env to send a bearer token.

How do I run Codex Cloud tasks from the terminal and apply their changes locally?

Run codex cloud to open an interactive picker. Use codex cloud exec with the required --env flag to submit a task, or codex cloud list to see recent tasks. To bring the latest diff from a cloud chat into your local working tree, run codex apply with the task ID.

How does Orbtile work with local, --remote and SSH Codex sessions?

Orbtile reads Codex thread files and Codex's own signals, and shows each session on a Logitech MX Creative Keypad, an iPhone or an Android phone. For a session using an explicit listener, set the same address in Orbtile's Terminal engine address setting. SSH hosts are added under Remote Hosts. Their keys are display-only, except Allow for terminal command approvals.