remote-connections.md Codex Docs, 2026-04-17 00:44 UTC → 2026-05-07 20:02 UTC

1# Remote connections1# Remote connections

2 2 

3SSH remote connections are currently in alpha. We are gradually rolling out3SSH remote connections are currently in alpha. To enable them today, set

4access. Availability, setup flows, and supported environments may change as4 `remote_connections = true` in the `[features]` table in

5the feature improves.5 `~/.codex/config.toml`. Availability, setup flows, and supported environments

6 may change as the feature improves.

6 7 

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

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

18In 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

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

20 21 

22<WorkflowSteps variant="headings">

23 

211. 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.

22 25 

23 ```text26 ```text

424. 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,

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

44 50 

51</WorkflowSteps>

52 

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

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

55 

56```toml

57[features]

58remote_connections = true

59```

60 

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

46remote host.62remote host.

47 63 

48![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/>

49 71 

50## Authentication and network exposure72## Authentication and network exposure

51 73