remote-connections.md Codex Docs, 2026-03-07 18:10 UTC → 2026-04-17 00:44 UTC

1# Remote connections

2 

3SSH remote connections are currently in alpha. We are gradually rolling out

4access. Availability, setup flows, and supported environments may change as

5the feature improves.

6 

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

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

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

10machine.

11 

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

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

14unauthenticated public listeners.

15 

16## Codex app

17 

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

19the remote filesystem and shell.

20 

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

22 

23 ```text

24 Host devbox

25 HostName devbox.example.com

26 User you

27 IdentityFile ~/.ssh/id_ed25519

28 ```

29 

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

31 OpenSSH, and ignores pattern-only hosts.

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

33 

34 ```bash

35 ssh devbox

36 ```

373. Install and authenticate Codex on the remote host.

38 

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

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

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

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

43 then choose a remote project folder.

44 

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

46remote host.

47 

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

49 

50## Authentication and network exposure

51 

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

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

54 

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

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

57directly to the internet.

58 

59## See also

60 

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

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

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