remote-connections.md +85 −0 added
1# Remote connections
2
3SSH remote connections are currently in alpha. To enable them today, set
4 `remote_connections = true` in the `[features]` table in
5 `~/.codex/config.toml`. Availability, setup flows, and supported environments
6 may change as the feature 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
22<WorkflowSteps variant="headings">
23
241. Add the host to your SSH config so Codex can auto-discover it.
25
26 ```text
27 Host devbox
28 HostName devbox.example.com
29 User you
30 IdentityFile ~/.ssh/id_ed25519
31 ```
32
33 Codex reads concrete host aliases from `~/.ssh/config`, resolves them with
34 OpenSSH, and ignores pattern-only hosts.
35
362. Confirm you can SSH to the host from the machine running the Codex app.
37
38 ```bash
39 ssh devbox
40 ```
41
423. Install and authenticate Codex on the remote host.
43
44 The app starts the remote Codex app server through SSH, using the remote
45 user's login shell. Make sure the `codex` command is available on the
46 remote host's `PATH` in that shell.
47
484. In the Codex app, open **Settings > Connections**, add or enable the SSH host,
49 then choose a remote project folder.
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
61Remote project threads run commands, read files, and write changes on the
62remote host.
63
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/>
71
72## Authentication and network exposure
73
74Use SSH port forwarding with local-host WebSocket listeners. Don't expose an
75unauthenticated app-server listener on a shared or public network.
76
77If you need to reach a remote machine outside your current network, use a VPN or
78mesh networking tool such as Tailscale instead of exposing the app server
79directly to the internet.
80
81## See also
82
83- [Codex app settings](https://developers.openai.com/codex/app/settings)
84- [Command line options](https://developers.openai.com/codex/cli/reference)
85- [Authentication](https://developers.openai.com/codex/auth)