remote-connections.md Codex Docs, 2026-05-14 21:00 UTC → 2026-05-18 22:01 UTC

6 Terminal,6 Terminal,

7} from "@components/react/oai/platform/ui/Icon.react";7} from "@components/react/oai/platform/ui/Icon.react";

8 8 

9Remote connections let you use Codex when you are away from the machine that9Remote connections let you use Codex from another device or another machine.

10runs it, or when your project lives on another machine. Connect the ChatGPT10Use Codex in the ChatGPT mobile app to work with Codex on a connected Mac,

11mobile app to a Codex App host, pick up work from another device, or configure11continue work from another Codex App device, or connect the Codex App to

12Codex to work on an SSH host.12projects on an SSH host.

13 13 

14Remote access uses the connected host's projects, threads, files, credentials,14Remote access uses the connected host's projects, threads, files, credentials,

15permissions, plugins, Computer Use, browser setup, and local tools.15permissions, plugins, Computer Use, browser setup, and local tools.

23- Get notified when Codex completes a task or needs your attention.23- Get notified when Codex completes a task or needs your attention.

24- Switch between connected hosts and threads.24- Switch between connected hosts and threads.

25 25 

26The next sections cover using the ChatGPT mobile app to control a Codex App26The next sections cover using Codex in the ChatGPT mobile app to control a Codex

27host. To connect Codex to a project on an SSH host, see27App host. To connect Codex to a project on an SSH host, see

28[connect to an SSH host](#connect-to-an-ssh-host).28[connect to an SSH host](#connect-to-an-ssh-host).

29 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">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">

44 44 

45- Codex access in the ChatGPT account and workspace you want to use.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 see46- The latest ChatGPT mobile app on an iOS or Android device. If you do not see

47 Codex in the app, update ChatGPT first.47 Codex in the ChatGPT mobile app, update ChatGPT first.

48- A Mac host that is awake, online, running the Codex App, and signed in to the48- The latest Codex App for macOS running on a Mac host that is awake, online,

49 same account and workspace. Mobile setup and device control currently require49 and signed in to the same account and workspace. Mobile setup starts from the

50 the Codex App for macOS on the host; the setup flow isn't available from the50 Codex App; you cannot set it up from the Codex CLI or IDE Extension.

51 Codex CLI or IDE Extension.

52- Any required multi-factor authentication, SSO, or passkey configuration for51- Any required multi-factor authentication, SSO, or passkey configuration for

53 that account or workspace.52 that account or workspace.

54 53 

115it plugged in and turn on **Keep this Mac awake** in the host's connection114it plugged in and turn on **Keep this Mac awake** in the host's connection

116settings.115settings.

117 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 

118### <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>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>

119 122 

120Use a dedicated always-on Mac when you want Codex to stay reachable for123Use a dedicated always-on Mac when you want Codex to stay reachable for

132 135 

133For SSH setup details, see [connect to an SSH host](#connect-to-an-ssh-host).136For SSH setup details, see [connect to an SSH host](#connect-to-an-ssh-host).

134 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 

135## What comes from the connected host141## What comes from the connected host

136 142 

137Your phone sends prompts, approvals, and follow-up messages to Codex. The143Your phone sends prompts, approvals, and follow-up messages to Codex. The

155 161 

156## Pick up work from another device162## Pick up work from another device

157 163 

158You can also connect one Codex App host to another. For example, if your laptop164You can continue work from another signed-in Codex App device. For example, if

159is unavailable, you can start a thread from your phone on an always-on host,165your laptop is unavailable, you can start a thread from your phone on an

160then later open Codex on your laptop and continue that thread from there.166always-on host, then later open Codex on your laptop and continue that same

167thread there.

161 168 

162In Codex on the laptop, use **Settings > Connections > Control other devices**169In Codex on the laptop, use **Settings > Connections > Control other devices**

163to add the other host. A device can allow remote access and control another170to add the other host. A device can allow remote access and control another

215 222 

216</WorkflowSteps>223</WorkflowSteps>

217 224 

218If remote connections don't appear yet, enable the alpha feature flag in

219`~/.codex/config.toml`:

220 

221```toml

222[features]

223remote_connections = true

224```

225 

226<CodexScreenshot225<CodexScreenshot

227 alt="Codex app settings showing SSH remote connections"226 alt="Codex app settings showing SSH remote connections"

228 lightSrc="/images/codex/app/remote-connections-light.webp"227 lightSrc="/images/codex/app/remote-connections-light.webp"

234 233 

235## Authentication and network exposure234## Authentication and network exposure

236 235 

237Use SSH port forwarding with local-host WebSocket listeners. Don't expose an236Remote connections use SSH to start and manage the remote Codex app server.

238unauthenticated app-server listener on a shared or public network.237Don't expose app-server transports directly on a shared or public network.

239 238 

240If you need to reach a remote machine outside your current network, use a VPN or239If you need to reach a remote machine outside your current network, use a VPN

241mesh networking tool such as Tailscale instead of exposing the app server240or mesh networking tool instead of exposing the app server directly to the

242directly to the internet.241internet.

243 242 

244## Troubleshooting243## Troubleshooting

245 244 

251 250 

252### The approval request does not appear251### The approval request does not appear

253 252 

254Open the ChatGPT mobile app and go to Codex. Confirm that the phone and host use253Open Codex in the ChatGPT mobile app. Confirm that the phone and host use the

255the same ChatGPT account and workspace, then scan the QR code again or restart254same ChatGPT account and workspace, then scan the QR code again or restart setup

256setup from the host. If you use a ChatGPT workspace, ask your admin to confirm255from the host. If you use a ChatGPT workspace, ask your admin to confirm that

257that Remote Control access is enabled.256Remote Control access is enabled.

258 257 

259### The remote session disconnects258### The remote session disconnects

260 259