How to add an SSH host connection in Codex

Remote projects in Codex stop at setup when the app host cannot reach the SSH environment that owns the repository. An SSH host connection lets the Codex App start a remote app server through OpenSSH so threads use the remote filesystem and shell instead of a local checkout.

Codex discovers concrete Host aliases from the SSH config on the machine running the Codex App. The alias should resolve with OpenSSH, authenticate without a password prompt, and land in an account where the codex command is on the login shell's PATH.

Remote project threads run commands, read files, and write changes on the SSH host. Use a least-privilege remote account, keep host keys verified, and reach off-network machines through a VPN or mesh network instead of exposing Codex app-server transports on a shared or public network.

Steps to add an SSH host connection in Codex:

  1. Add a concrete SSH alias on the machine running the Codex App.
    ~/.ssh/config
    Host codex-devbox
  HostName devbox.example.com
  User dev
  IdentityFile ~/.ssh/id_ed25519_codex
  IdentitiesOnly yes

    Codex auto-discovers concrete Host aliases and ignores wildcard-only entries such as Host *.
    Related: How to set per-host SSH identity files in SSH config
    Tool: SSH Config Snippet Generator

  2. Check the resolved SSH settings for the alias. 
    $ ssh -G codex-devbox
host codex-devbox
user dev
hostname devbox.example.com
port 22
##### snipped #####
identityfile ~/.ssh/id_ed25519_codex

    The printed user, hostname, port, and identityfile values should match the host and account that should own the remote Codex project.

  3. Confirm normal SSH login through the alias. 
    $ ssh codex-devbox 'hostname'
devbox

    If this is the first connection, verify the host key fingerprint before accepting it. A trusted SSH alias is the boundary Codex uses to start the remote session.
    Related: How to verify SSH host key fingerprints before connecting

  4. Confirm that the remote login shell can find Codex. 
    $ ssh codex-devbox 'command -v codex'
/usr/local/bin/codex

    The Codex App starts the remote app server through SSH using the remote user's login shell. If this command prints nothing, install Codex on the remote host or fix that account's shell PATH.

  5. Confirm that the remote Codex profile is authenticated. 
    $ ssh codex-devbox 'codex login status'
Logged in using ChatGPT

    Run the check as the same remote user that the SSH alias uses. If it prints Not logged in, complete login on the remote host before adding the connection.
    Related: How to check Codex login status
    Related: How to log in to Codex with device authentication

  6. Open Codex App on the local app host and go to Settings → Connections.
  7. Add or enable the codex-devbox SSH host, then choose the remote project folder.

    The host list comes from the app host's SSH config. Edit that local config and reopen Settings → Connections if the alias is missing.

  8. Start a thread in the selected remote project with a harmless smoke-test prompt. 
    Check the current repository path and run git status --short.
  9. Confirm that the thread runs against the remote project.

    The thread should show the selected SSH host and project folder, and any terminal output should come from the remote repository rather than a local checkout.