Codex on a VPS: install it on a Linux server and connect over SSH

How Codex on a VPS fits together

Three machines are involved, and each has one job:

• The Linux server runs Codex. Chats in its projects run commands, read files and write changes there, with the server's dependencies, security policies and compute. The desktop app starts Codex on it over SSH, in the remote user's login shell.
• A Mac or Windows PC runs the ChatGPT desktop app, which holds the SSH connection. It's the host your phone talks to, so it has to stay awake and online too.
• Your phone runs the ChatGPT app and controls that host through remote control. It sends prompts and approvals and shows you diffs, terminal output and notifications.
• OpenAI documents only macOS and Windows as remote-control hosts, so pairing a phone straight with a Linux server isn't documented. Pair your phone with the Mac or PC instead, ideally an always-on Mac mini.

What you need

• A Linux server you can reach with SSH. The Codex CLI's install guide on GitHub lists Ubuntu 20.04+ or Debian 10+, with 4 GB of RAM as the minimum and 8 GB recommended; release builds exist for x86_64 and ARM64.
• A Mac or Windows PC with the ChatGPT desktop app, to add the server as an SSH host. If you want to reach the server from your phone, this computer has to stay on.
• A ChatGPT account for Codex. OpenAI's plan table lists SSH remote connections on Plus, Pro, Business and Enterprise and with an API key, and mobile remote control on Plus, Pro, Business and Enterprise but not with an API key.
• The ChatGPT app on your phone, iOS or Android.

How to set up Codex on a Linux VPS

1. Rent a server and check SSH

   Create a Linux server and make sure you can log in with SSH from the Mac or PC that will run the desktop app. Use key-based login and an account with only the rights Codex needs, not root.

2. Install the Codex CLI on the server

   Run OpenAI's install script on the server; the same command updates it later, and npm works too. Install bubblewrap for Codex's sandbox: without bwrap on the PATH, Codex falls back to a bundled helper that needs unprivileged user namespaces, and warns when it starts. Ubuntu 24.04 may keep warning until you load the bwrap-userns-restrict AppArmor profile.

   # On the server: install the Codex CLI (run it again to update)
   curl -fsSL https://chatgpt.com/codex/install.sh | sh
   # or: npm install -g @openai/codex
   
   # Codex's sandbox on Linux uses bubblewrap
   sudo apt install bubblewrap   # Fedora: sudo dnf install bubblewrap

3. Log in on a headless server

   The server has no browser, so use device code login: run codex login --device-auth, or choose Sign in with Device Code, and follow the prompt. It's in beta, and device code login has to be turned on first in your ChatGPT security settings or by your workspace admin. If you can't use it, forward the login callback with ssh -L 1455:localhost:1455 and run codex login on the server, or copy ~/.codex/auth.json from a computer where you're signed in and treat that file like a password.

   # Headless sign-in (beta; turn on device code login in ChatGPT first)
   codex login --device-auth
   
   # Or forward the browser callback from your computer, then run codex login
   ssh -L 1455:localhost:1455 you@devbox.example.com
   
   # Exits 0 once you're signed in
   codex login status

4. Add the server to your SSH config

   On the Mac or PC, add a Host entry to ~/.ssh/config and check that ssh devbox works. Codex reads concrete host aliases from that file and ignores pattern-only entries. The desktop app starts Codex in the remote user's login shell, so codex has to be on the PATH there.

   # ~/.ssh/config on the Mac or PC running the ChatGPT desktop app
   Host devbox
     HostName devbox.example.com
     User you
     IdentityFile ~/.ssh/id_ed25519
   
   # Check it works before adding it in the app
   ssh devbox

5. Add it as an SSH host in the desktop app

   In the ChatGPT desktop app, open Settings > Connections, add or enable the SSH host, then choose a project folder on the server. Chats in that project run commands, read files and write changes on the server.

6. Control it from your phone

   On the same Mac or PC, open Settings > Connections > Control this Mac or PC, select Set up or Add, and scan the QR code with the ChatGPT app. Open Codex on your phone, pick that computer and the server's project, and start a chat. The chat runs on the server through the Mac or PC, so keep that computer awake and online; a Mac mini at home can do that job. Setup details and fixes are in Codex remote control.

Source: OpenAI's docs on remote connections and SSH hosts

Terminal only: the Codex CLI over SSH in tmux

If a terminal is all you need, you can skip the desktop app. SSH into the server, run the Codex CLI inside tmux, and detach: Codex keeps running after you disconnect, and you reattach from any computer that can SSH in.

1. Start Codex inside tmux

   Install tmux from your distribution's packages if it isn't there, start a session, and run codex in your project folder.

   # On the server: run Codex inside tmux so it outlives your SSH connection
   tmux new -s codex
   cd ~/my-project
   codex
   
   # Detach with Ctrl+B, then D. Reattach later with:
   tmux attach -t codex

2. Know what it doesn't do

   This setup isn't connected to your phone. OpenAI says mobile setup starts from the desktop app and can't be set up from the CLI. The CLI has an experimental codex remote-control command, which the docs tie to managed remote-control clients and SSH workflows, but they don't describe pairing a phone with a server that only runs the CLI.

Keep the server safe

• Treat it like any SSH server: trusted keys, a least-privilege account, and no unauthenticated services listening on the public internet.
• Don't expose Codex's app server. codex app-server --listen and codex --remote are mainly for development and debugging, and OpenAI warns against opening app-server transports on a shared or public network.
• To reach the server from outside its network, use a VPN or a mesh network such as Tailscale, which connects only your own devices over encrypted WireGuard links.
• Keep ~/.codex/auth.json private; OpenAI says to treat it like a password.
• Sandbox settings, security controls and approvals apply to chats on the server as they do locally, and the sandbox on Linux needs bubblewrap.

Move a chat between your computer and the server

The desktop app can hand a chat off, with its Git state, between your computer and a connected SSH host. Both need a saved project for the same Git repository. In the chat footer, pick where it runs now, choose the destination host (This computer brings it back), review and select Hand off. Codex creates or reuses a worktree there. A response that's still running is interrupted, and a chat can't be handed off to Codex cloud.

No server at all: Codex cloud

• Codex cloud runs coding tasks on OpenAI's cloud. Each task gets its own workspace and keeps working while your computer is asleep.
• Start from the web, from the desktop app (Work in > Cloud) or from the ChatGPT app on your phone (open Codex, choose Cloud and an environment). With the default environment you can start without picking a repository, and Codex can check out repositories from your connected GitHub or GitLab account.
• A cloud task only sees its cloud environment: your local files, running processes, browser sign-ins and VPN access aren't carried over. Reusable setups live under Work in > Cloud > Select environment > Create environment.
• It needs a ChatGPT sign-in, not an API key. From a terminal, codex cloud opens a picker of your cloud chats and codex cloud exec submits a task.

Mac mini host vs Linux SSH host vs Codex cloud

Give the server a standing job

A server that never sleeps still waits for your next prompt. Crewmark turns a Codex chat on it into an AI employee with a role, a goal in numbers, working hours and a heartbeat: during working hours the crewmark CLI, which runs on Linux as well as macOS and Windows, wakes the employee to work through its issues on a shared board. The computer it runs on has to stay on, and a VPS does.

1. Hire an employee

   Pick a role from the AI employee roles, such as software engineer or SEO specialist, and write its goals and KPIs.

2. Connect Codex on the server

   Paste the setup link into a Codex chat on the server. It installs the crewmark CLI and links that chat to the employee. Claude Code works too; see Claude Code on a VPS.

3. Set working hours and a heartbeat

   Weekdays only or every day, hours that can run past midnight, and a wake-up every 15, 30, 60, 120 or 240 minutes. Each wake-up goes into the same Codex chat, so it carries on where it left off. Codex's own scheduling options are compared in proactive Codex.

4. Assign issues and talk to it from your phone

   Open crewmark.ai in your phone's browser to create and assign issues, or write to the employee in its Work log; the message reaches the Codex chat on the server, and it answers there. Assigning an issue wakes it right away, and when it needs a review or a decision it sets the issue to Needs action and asks you there. Jobs to give it are in Codex use cases.

FAQ