remote-connections.md Codex Docs, 2026-03-16 18:25 UTC → 2026-04-22 00:42 UTC

1# Remote connections

2 

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

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

5Availability, setup flows, and supported environments may change as the

6feature improves.

7 

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

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

10build environment you need are available on that host instead of your local

11machine.

12 

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

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

15unauthenticated public listeners.

16 

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 

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

23 

24 ```text

25 Host devbox

26 HostName devbox.example.com

27 User you

28 IdentityFile ~/.ssh/id_ed25519

29 ```

30 

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

32 OpenSSH, and ignores pattern-only hosts.

332. Confirm you can SSH to the host from the machine running the Codex app.

34 

35 ```bash

36 ssh devbox

37 ```

383. Install and authenticate Codex on the remote host.

39 

40 The app starts the remote Codex app server through SSH, using the remote

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

42 remote host's `PATH` in that shell.

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

44 then choose a remote project folder.

45 

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

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

48 

49```toml

50[features]

51remote_control = true

52```

53 

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

55remote host.

56 

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

58 

59## Authentication and network exposure

60 

61Use SSH port forwarding with local-host WebSocket listeners. Don't expose an

62unauthenticated app-server listener on a shared or public network.

63 

64If you need to reach a remote machine outside your current network, use a VPN or

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

66directly to the internet.

67 

68## See also

69 

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

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

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