remote-connections.md Codex Docs, 2026-04-22 18:29 UTC → 2026-05-07 20:02 UTC

1# Remote connections1# Remote connections

2 2 

3SSH remote connections are currently in alpha. To enable them today, set3SSH remote connections are currently in alpha. To enable them today, set

4`remote_control = true` in the `[features]` table in `~/.codex/config.toml`.4 `remote_connections = true` in the `[features]` table in

5Availability, setup flows, and supported environments may change as the5 `~/.codex/config.toml`. Availability, setup flows, and supported environments

6feature improves.6 may change as the feature improves.

7 7 

8Remote connections let Codex work with projects that live on another8Remote connections let Codex work with projects that live on another

9SSH-accessible machine. Use them when the codebase, credentials, services, or9SSH-accessible machine. Use them when the codebase, credentials, services, or

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

20the remote filesystem and shell.20the remote filesystem and shell.

21 21 

22<WorkflowSteps variant="headings">

23 

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

23 25 

24 ```text26 ```text

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

44 then choose a remote project folder.49 then choose a remote project folder.

45 50 

51</WorkflowSteps>

52 

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

47`~/.codex/config.toml`:54`~/.codex/config.toml`:

48 55 

49```toml56```toml

50[features]57[features]

51remote_control = true58remote_connections = true

52```59```

53 60 

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

55remote host.62remote host.

56 63 

57![Codex app settings showing SSH remote connections](/images/codex/app/remote-connections-light.webp)64<CodexScreenshot

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

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

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

68 maxHeight="420px"

69 variant="no-wallpaper"

70/>

58 71 

59## Authentication and network exposure72## Authentication and network exposure

60 73