remote-connections.md +278 −0 added
1# Remote connections
2
3import {
4 Desktop,
5 Storage,
6 Terminal,
7} from "@components/react/oai/platform/ui/Icon.react";
8
9Remote connections let you use Codex from another device or another machine.
10Use Codex in the ChatGPT mobile app to work with Codex on a connected Mac,
11continue work from another Codex App device, or connect the Codex App to
12projects on an SSH host.
13
14Remote access uses the connected host's projects, threads, files, credentials,
15permissions, plugins, Computer Use, browser setup, and local tools.
16
17## What you can do remotely
18
19- Start new threads in projects on the host, or continue existing ones.
20- Send follow-up instructions, answer questions, and steer active work.
21- Approve commands and other actions.
22- Review outputs, diffs, test results, terminal output, and screenshots.
23- Get notified when Codex completes a task or needs your attention.
24- Switch between connected hosts and threads.
25
26The next sections cover using Codex in the ChatGPT mobile app to control a Codex
27App host. To connect Codex to a project on an SSH host, see
28[connect to an SSH host](#connect-to-an-ssh-host).
29
30<div class="not-prose my-6 max-w-4xl rounded-xl bg-[url('/images/codex/codex-wallpaper-1.webp')] bg-cover bg-center p-4 md:p-8">
31 <CodexScreenshot
32 alt="Codex mobile setup screen alongside the ChatGPT mobile Codex project list"
33 lightSrc="/images/codex/app/mobile-setup-light.webp"
34 darkSrc="/images/codex/app/mobile-setup-dark.webp"
35 variant="no-wallpaper"
36 maxHeight="none"
37 maxWidth="420px"
38 />
39</div>
40
41## Before you set up mobile access
42
43Make sure you have:
44
45- Codex access in the ChatGPT account and workspace you want to use.
46- The latest ChatGPT mobile app on an iOS or Android device. If you do not see
47 Codex in the ChatGPT mobile app, update ChatGPT first.
48- The latest Codex App for macOS running on a Mac host that is awake, online,
49 and signed in to the same account and workspace. Mobile setup starts from the
50 Codex App; you cannot set it up from the Codex CLI or IDE Extension.
51- Any required multi-factor authentication, SSO, or passkey configuration for
52 that account or workspace.
53
54If you use Codex through a ChatGPT workspace, your admin may need to enable
55Remote Control access before you can connect from your phone.
56
57## Set up mobile access
58
59Start in the Codex App on the host you want to connect. The setup flow enables
60remote access for that host, then shows a QR code you can scan from your phone.
61
62<WorkflowSteps variant="headings">
63
641. Start Codex mobile setup.
65
66 Open Codex on the host and select **Set up Codex mobile** in the
67 sidebar.
68
692. Scan the QR code.
70
71 Use your phone to scan the QR code shown by Codex. The code opens ChatGPT so
72 you can finish connecting the mobile app to the host.
73
743. Finish setup in ChatGPT.
75
76 ChatGPT opens the Codex mobile setup flow. Confirm the same ChatGPT account
77 and workspace, then complete any required multi-factor authentication, SSO,
78 or passkey steps. After setup succeeds, the host appears in Codex on your
79 phone.
80
814. Review host settings.
82
83 In Codex on the host, use **Settings > Connections** to manage connected
84 devices. You can also choose whether to keep the computer awake, enable
85 Computer Use, or install the Chrome extension.
86
87</WorkflowSteps>
88
89<div class="not-prose my-6 max-w-4xl">
90 <CodexScreenshot
91 alt="Connections settings showing devices that can control this Mac and remote access settings"
92 lightSrc="/images/codex/app/mobile-control-this-mac-framed-light.webp"
93 darkSrc="/images/codex/app/mobile-control-this-mac-framed-dark.webp"
94 maxHeight="480px"
95 class="p-3 sm:p-4"
96 imageClass="rounded-xl"
97 />
98</div>
99
100## Choose what to connect
101
102Start with the Mac laptop or desktop where you already use Codex. Add an
103always-on Mac or SSH host when you need continuous access or a different
104environment.
105
106### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Desktop width={17} height={17} /></span><span>Your Mac laptop or desktop</span></span>
107
108Connect the Mac where you already run Codex day to day. This gives remote access
109to the same projects, threads, credentials, plugins, and local setup you already
110use.
111
112If that Mac sleeps, loses network access, or closes Codex, remote access stops
113until it is available again. If you use this computer as your host device, keep
114it plugged in and turn on **Keep this Mac awake** in the host's connection
115settings.
116
117On a Mac laptop, remote access can stay available with the lid open while the
118computer is plugged in. With the lid closed, connect an external display as
119well. Choosing **Sleep** still stops remote access.
120
121### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Storage width={17} height={17} /></span><span>A dedicated always-on Mac</span></span>
122
123Use a dedicated always-on Mac when you want Codex to stay reachable for
124longer-running work.
125
126Install the projects, credentials, plugins, MCP servers, and tools Codex should
127use on that machine.
128
129### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Terminal width={17} height={17} /></span><span>A remote development environment</span></span>
130
131Use an SSH host or managed devbox when the project already lives in a remote
132environment. Connect the Codex App host to that environment first; your phone
133still connects to the Codex App host, and Codex works in the remote environment
134with its dependencies, security policies, and compute resources.
135
136For SSH setup details, see [connect to an SSH host](#connect-to-an-ssh-host).
137
138For browser or desktop tasks on an always-on Mac or remote host, enable
139 Computer Use and install the Chrome extension on that host.
140
141## What comes from the connected host
142
143Your phone sends prompts, approvals, and follow-up messages to Codex. The
144connected host provides the environment Codex uses.
145
146That means:
147
148- Repository files and local documents come from the connected host.
149- Shell commands run on that host or remote environment.
150- Any plugin installed on that host is available when you use Codex remotely.
151- MCP servers, skills, browser access, and Computer Use come from that host's
152 configuration.
153- Signed-in websites and desktop apps are available only when the host can
154 access them.
155- Sandboxing, security controls, and action approvals still apply to the
156 connected session.
157
158Codex uses a secure relay layer to keep trusted machines reachable across your
159authorized ChatGPT devices without exposing them directly to the public
160internet.
161
162## Pick up work from another device
163
164You can continue work from another signed-in Codex App device. For example, if
165your laptop is unavailable, you can start a thread from your phone on an
166always-on host, then later open Codex on your laptop and continue that same
167thread there.
168
169In Codex on the laptop, use **Settings > Connections > Control other devices**
170to add the other host. A device can allow remote access and control another
171device at the same time.
172
173<div class="not-prose my-6 max-w-4xl">
174 <CodexScreenshot
175 alt="Connections settings showing another device available under Control other devices"
176 lightSrc="/images/codex/app/mobile-control-other-devices-framed-light.webp"
177 darkSrc="/images/codex/app/mobile-control-other-devices-framed-dark.webp"
178 maxHeight="360px"
179 class="p-3 sm:p-4"
180 imageClass="rounded-xl"
181 />
182</div>
183
184## Connect to an SSH host
185
186In the Codex App, add remote projects from an SSH host and run threads against
187the remote filesystem and shell. Remote project threads run commands, read
188files, and write changes on the remote host.
189
190Keep the remote host configured with the same security expectations you use for
191normal SSH access: trusted keys, least-privilege accounts, and no
192unauthenticated public listeners.
193
194<WorkflowSteps variant="headings">
195
1961. Add the host to your SSH config so Codex can auto-discover it.
197
198 ```text
199 Host devbox
200 HostName devbox.example.com
201 User you
202 IdentityFile ~/.ssh/id_ed25519
203 ```
204
205 Codex reads concrete host aliases from `~/.ssh/config`, resolves them with
206 OpenSSH, and ignores pattern-only hosts.
207
2082. Confirm you can SSH to the host from the machine running the Codex App.
209
210 ```bash
211 ssh devbox
212 ```
213
2143. Install and authenticate Codex on the remote host.
215
216 The app starts the remote Codex app server through SSH, using the remote
217 user's login shell. Make sure the `codex` command is available on the
218 remote host's `PATH` in that shell.
219
2204. In the Codex App, open **Settings > Connections**, add or enable the SSH
221 host, then choose a remote project folder.
222
223</WorkflowSteps>
224
225<CodexScreenshot
226 alt="Codex app settings showing SSH remote connections"
227 lightSrc="/images/codex/app/remote-connections-light.webp"
228 darkSrc="/images/codex/app/remote-connections-dark.webp"
229 maxHeight="420px"
230 class="p-3 sm:p-4"
231 imageClass="rounded-xl"
232/>
233
234## Authentication and network exposure
235
236Remote connections use SSH to start and manage the remote Codex app server.
237Don't expose app-server transports directly on a shared or public network.
238
239If you need to reach a remote machine outside your current network, use a VPN
240or mesh networking tool instead of exposing the app server directly to the
241internet.
242
243## Troubleshooting
244
245### You do not see the host on your phone
246
247Confirm that the Codex App is running on the host, **Allow other devices to
248connect** is enabled, and the same ChatGPT account and workspace are selected on
249both devices.
250
251### The approval request does not appear
252
253Open Codex in the ChatGPT mobile app. Confirm that the phone and host use the
254same ChatGPT account and workspace, then scan the QR code again or restart setup
255from the host. If you use a ChatGPT workspace, ask your admin to confirm that
256Remote Control access is enabled.
257
258### The remote session disconnects
259
260Check whether the host went to sleep, lost network access, or closed Codex.
261Keep the host awake and connected while Codex works.
262
263### Authentication blocks setup
264
265Complete the account or workspace authentication prompt shown during setup. If
266your organization requires SSO, multi-factor authentication, or a passkey,
267finish that flow before trying again. If setup still fails, ask your workspace
268admin to confirm that Remote Control access is enabled.
269
270## See also
271
272- [Codex App](https://developers.openai.com/codex/app)
273- [Codex App features](https://developers.openai.com/codex/app/features)
274- [Codex App settings](https://developers.openai.com/codex/app/settings)
275- [Computer Use](https://developers.openai.com/codex/app/computer-use)
276- [Chrome extension](https://developers.openai.com/codex/app/chrome-extension)
277- [Command line options](https://developers.openai.com/codex/cli/reference)
278- [Authentication](https://developers.openai.com/codex/auth)