remote-connections.md Codex Docs, 2026-05-07 20:02 UTC → 2026-05-14 21:00 UTC

1# Remote connections1# Remote connections

2 2 

3SSH remote connections are currently in alpha. To enable them today, set3import {

4 `remote_connections = true` in the `[features]` table in4 Desktop,

5 `~/.codex/config.toml`. Availability, setup flows, and supported environments5 Storage,

6 may change as the feature improves.6 Terminal,

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

7 8 

8Remote connections let Codex work with projects that live on another9Remote connections let you use Codex when you are away from the machine that

9SSH-accessible machine. Use them when the codebase, credentials, services, or10runs it, or when your project lives on another machine. Connect the ChatGPT

10build environment you need are available on that host instead of your local11mobile app to a Codex App host, pick up work from another device, or configure

11machine.12Codex to work 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 the ChatGPT mobile app to control a Codex App

27host. 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 app, update ChatGPT first.

48- A Mac host that is awake, online, running the Codex App, and signed in to the

49 same account and workspace. Mobile setup and device control currently require

50 the Codex App for macOS on the host; the setup flow isn't available from the

51 Codex CLI or IDE Extension.

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

53 that account or workspace.

54 

55If you use Codex through a ChatGPT workspace, your admin may need to enable

56Remote Control access before you can connect from your phone.

57 

58## Set up mobile access

59 

60Start in the Codex App on the host you want to connect. The setup flow enables

61remote access for that host, then shows a QR code you can scan from your phone.

62 

63<WorkflowSteps variant="headings">

64 

651. Start Codex mobile setup.

66 

67 Open Codex on the host and select **Set up Codex mobile** in the

68 sidebar.

69 

702. Scan the QR code.

71 

72 Use your phone to scan the QR code shown by Codex. The code opens ChatGPT so

73 you can finish connecting the mobile app to the host.

74 

753. Finish setup in ChatGPT.

76 

77 ChatGPT opens the Codex mobile setup flow. Confirm the same ChatGPT account

78 and workspace, then complete any required multi-factor authentication, SSO,

79 or passkey steps. After setup succeeds, the host appears in Codex on your

80 phone.

81 

824. Review host settings.

83 

84 In Codex on the host, use **Settings > Connections** to manage connected

85 devices. You can also choose whether to keep the computer awake, enable

86 Computer Use, or install the Chrome extension.

87 

88</WorkflowSteps>

89 

90<div class="not-prose my-6 max-w-4xl">

91 <CodexScreenshot

92 alt="Connections settings showing devices that can control this Mac and remote access settings"

93 lightSrc="/images/codex/app/mobile-control-this-mac-framed-light.webp"

94 darkSrc="/images/codex/app/mobile-control-this-mac-framed-dark.webp"

95 maxHeight="480px"

96 class="p-3 sm:p-4"

97 imageClass="rounded-xl"

98 />

99</div>

100 

101## Choose what to connect

102 

103Start with the Mac laptop or desktop where you already use Codex. Add an

104always-on Mac or SSH host when you need continuous access or a different

105environment.

106 

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

108 

109Connect the Mac where you already run Codex day to day. This gives remote access

110to the same projects, threads, credentials, plugins, and local setup you already

111use.

112 

113If that Mac sleeps, loses network access, or closes Codex, remote access stops

114until it is available again. If you use this computer as your host device, keep

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

116settings.

117 

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>

119 

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

121longer-running work.

122 

123Install the projects, credentials, plugins, MCP servers, and tools Codex should

124use on that machine.

125 

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

127 

128Use an SSH host or managed devbox when the project already lives in a remote

129environment. Connect the Codex App host to that environment first; your phone

130still connects to the Codex App host, and Codex works in the remote environment

131with its dependencies, security policies, and compute resources.

132 

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

134 

135## What comes from the connected host

136 

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

138connected host provides the environment Codex uses.

139 

140That means:

141 

142- Repository files and local documents come from the connected host.

143- Shell commands run on that host or remote environment.

144- Any plugin installed on that host is available when you use Codex remotely.

145- MCP servers, skills, browser access, and Computer Use come from that host's

146 configuration.

147- Signed-in websites and desktop apps are available only when the host can

148 access them.

149- Sandboxing, security controls, and action approvals still apply to the

150 connected session.

151 

152Codex uses a secure relay layer to keep trusted machines reachable across your

153authorized ChatGPT devices without exposing them directly to the public

154internet.

155 

156## Pick up work from another device

157 

158You can also connect one Codex App host to another. For example, if your laptop

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

160then later open Codex on your laptop and continue that thread from there.

161 

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

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

164device at the same time.

165 

166<div class="not-prose my-6 max-w-4xl">

167 <CodexScreenshot

168 alt="Connections settings showing another device available under Control other devices"

169 lightSrc="/images/codex/app/mobile-control-other-devices-framed-light.webp"

170 darkSrc="/images/codex/app/mobile-control-other-devices-framed-dark.webp"

171 maxHeight="360px"

172 class="p-3 sm:p-4"

173 imageClass="rounded-xl"

174 />

175</div>

176 

177## Connect to an SSH host

178 

179In the Codex App, add remote projects from an SSH host and run threads against

180the remote filesystem and shell. Remote project threads run commands, read

181files, and write changes on the remote host.

12 182 

13Keep the remote host configured with the same security expectations you use for183Keep the remote host configured with the same security expectations you use for

14normal SSH access: trusted keys, least-privilege accounts, and no184normal SSH access: trusted keys, least-privilege accounts, and no

15unauthenticated public listeners.185unauthenticated public listeners.

16 186 

17## Codex app

18 

19In the Codex app, add remote projects from an SSH host and run threads against

20the remote filesystem and shell.

21 

22<WorkflowSteps variant="headings">187<WorkflowSteps variant="headings">

23 188 

241. Add the host to your SSH config so Codex can auto-discover it.1891. Add the host to your SSH config so Codex can auto-discover it.

33 Codex reads concrete host aliases from `~/.ssh/config`, resolves them with198 Codex reads concrete host aliases from `~/.ssh/config`, resolves them with

34 OpenSSH, and ignores pattern-only hosts.199 OpenSSH, and ignores pattern-only hosts.

35 200 

362. Confirm you can SSH to the host from the machine running the Codex app.2012. Confirm you can SSH to the host from the machine running the Codex App.

37 202 

38 ```bash203 ```bash

39 ssh devbox204 ssh devbox

45 user's login shell. Make sure the `codex` command is available on the210 user's login shell. Make sure the `codex` command is available on the

46 remote host's `PATH` in that shell.211 remote host's `PATH` in that shell.

47 212 

484. In the Codex app, open **Settings > Connections**, add or enable the SSH host,2134. In the Codex App, open **Settings > Connections**, add or enable the SSH

49 then choose a remote project folder.214 host, then choose a remote project folder.

50 215 

51</WorkflowSteps>216</WorkflowSteps>

52 217 

58remote_connections = true223remote_connections = true

59```224```

60 225 

61Remote project threads run commands, read files, and write changes on the

62remote host.

63 

64<CodexScreenshot226<CodexScreenshot

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

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

67 darkSrc="/images/codex/app/remote-connections-dark.webp"229 darkSrc="/images/codex/app/remote-connections-dark.webp"

68 maxHeight="420px"230 maxHeight="420px"

69 variant="no-wallpaper"231 class="p-3 sm:p-4"

232 imageClass="rounded-xl"

70/>233/>

71 234 

72## Authentication and network exposure235## Authentication and network exposure

78mesh networking tool such as Tailscale instead of exposing the app server241mesh networking tool such as Tailscale instead of exposing the app server

79directly to the internet.242directly to the internet.

80 243 

244## Troubleshooting

245 

246### You do not see the host on your phone

247 

248Confirm that the Codex App is running on the host, **Allow other devices to

249connect** is enabled, and the same ChatGPT account and workspace are selected on

250both devices.

251 

252### The approval request does not appear

253 

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

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

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

257that Remote Control access is enabled.

258 

259### The remote session disconnects

260 

261Check whether the host went to sleep, lost network access, or closed Codex.

262Keep the host awake and connected while Codex works.

263 

264### Authentication blocks setup

265 

266Complete the account or workspace authentication prompt shown during setup. If

267your organization requires SSO, multi-factor authentication, or a passkey,

268finish that flow before trying again. If setup still fails, ask your workspace

269admin to confirm that Remote Control access is enabled.

270 

81## See also271## See also

82 272 

83- [Codex app settings](https://developers.openai.com/codex/app/settings)273- [Codex App](https://developers.openai.com/codex/app)

274- [Codex App features](https://developers.openai.com/codex/app/features)

275- [Codex App settings](https://developers.openai.com/codex/app/settings)

276- [Computer Use](https://developers.openai.com/codex/app/computer-use)

277- [Chrome extension](https://developers.openai.com/codex/app/chrome-extension)

84- [Command line options](https://developers.openai.com/codex/cli/reference)278- [Command line options](https://developers.openai.com/codex/cli/reference)

85- [Authentication](https://developers.openai.com/codex/auth)279- [Authentication](https://developers.openai.com/codex/auth)