tutorial

How to Run OpenAI Codex CLI on a VPS: Setup and Auth Guide

Sahil Kathpal

• 7 min read

TL;DR

You can run OpenAI Codex CLI on a headless VPS, but the OAuth flow requires a browser — you solve this by SSH port-forwarding the callback URL back to your local machine. Once authenticated, use tmux to keep sessions alive across disconnects. If you want a single always-on environment that works for Codex CLI, Claude Code, and other agents without repeating this setup, Grass provides pre-configured cloud VMs at codeongrass.com.

Why run Codex CLI on a VPS at all?

The obvious reason: your laptop closes, your agent dies. A VPS keeps Codex running while you sleep, travel, or just close the lid. There's a Reddit thread from March 2026 in r/codex titled "[HELP] Deploy Codex in a VPS" — dozens of developers hit this exact wall and found no clean official path. The problem isn't installing Codex, it's authenticating it on a machine with no browser.

This guide covers:

  1. Installing Codex CLI on a Linux VPS
  2. Solving the headless OAuth problem with SSH port-forwarding
  3. Keeping sessions alive with tmux
  4. Using the Codex remote connections alpha for working on remote projects via SSH

What does your VPS need?

Any modern Linux VPS works. Tested on Ubuntu 22.04 and Debian 12. Minimum specs for Codex CLI itself are minimal — a $4-6/month instance (2GB RAM, 1 vCPU) is enough for the agent process. Your workload may need more.

Requirements:

  • Node.js 20+ (Codex CLI is an npm package)
  • tmux (for session persistence)
  • SSH access with port-forwarding allowed (check AllowTcpForwarding in sshd_config)
  • Your OpenAI API key

How do you install Codex CLI on Linux?

SSH into your VPS, then install Node.js if it isn't there:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify:

node --version
# v20.x.x
npm --version
# 10.x.x

Install Codex CLI globally:

npm install -g @openai/codex

Verify the install:

codex --version

Expected output:

0.x.x

If you get a permission error during npm install -g, either fix npm's global prefix to a user-owned directory or use a Node version manager like nvm instead of the system Node.

# nvm alternative
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
npm install -g @openai/codex

How do you authenticate Codex CLI on a headless server?

This is the hard part. Codex CLI uses OAuth — it opens a browser to complete login. A headless VPS has no browser. Running codex auth login will print a URL and hang waiting for the callback, but the callback never arrives because nothing can open a browser on the server.

The workaround: SSH port-forwarding tunnels the OAuth callback from the server back to your local machine, where your browser can complete it.

Step 1 — Set up the tunnel when you SSH in.

Use -L to forward the local port Codex will use for its callback server. Codex CLI listens on localhost:54321 by default (confirm in the Codex docs for your installed version — this may vary):

ssh -L 54321:localhost:54321 user@your-vps-ip

This forwards traffic arriving at localhost:54321 on your local machine to localhost:54321 on the VPS. When the OAuth provider redirects to http://localhost:54321/callback, your local browser handles it, the token gets sent to the VPS listener, and auth completes.

Step 2 — Run the login command on the VPS.

codex auth login

Expected output:

Opening browser for authentication...
If browser did not open, visit: https://auth.openai.com/authorize?...
Waiting for callback on http://localhost:54321/callback ...

Step 3 — Open the URL in your local browser.

Copy the URL from the terminal output and paste it into your local browser. Complete the OpenAI login flow. The browser will redirect to http://localhost:54321/callback — because of your SSH tunnel, this hits the VPS listener, not your local machine.

Step 4 — Confirm auth completed.

Back in the VPS terminal:

✓ Authenticated as your@email.com

If you see a timeout instead, check that:

  • The SSH session with -L 54321:localhost:54321 is still open (not in a different terminal tab without forwarding)
  • No local firewall is blocking port 54321
  • The callback URL in the browser includes localhost:54321 and not some other port

Alternative: API key auth

If your Codex CLI version supports API key authentication directly (bypassing OAuth), set the environment variable:

export OPENAI_API_KEY="sk-..."

Check codex --help or the official OpenAI Codex CLI docs for whether your version supports --api-key or environment-variable-only auth. If it does, you skip the tunnel entirely.

How do you keep Codex running after you disconnect?

Without session persistence, your Codex process dies the moment your SSH connection drops. tmux solves this. It keeps the terminal session alive on the server independent of any SSH connection.

Install tmux:

sudo apt-get install -y tmux

Start a named session:

tmux new-session -s codex

Inside the tmux session, start your Codex CLI task:

codex "Refactor the auth module to use JWT"

Detach from the session without killing it: Ctrl-b d

Later, reconnect to your VPS and reattach:

tmux attach-session -t codex

Your Codex session is exactly where you left it. To list active sessions:

tmux ls

Expected output:

codex: 1 windows (created Tue May 12 09:00:00 2026)

Troubleshooting: If tmux exits unexpectedly, check whether Codex received a SIGHUP. Add set-option -g remain-on-exit on to ~/.tmux.conf to keep panes open after a process exits, so you can read the error output.

How does the Codex remote connections alpha work?

OpenAI added a remote connections alpha to Codex CLI that lets the agent work directly on files on a remote server over SSH, without needing Codex installed on the server. This is distinct from what we've covered so far (Codex installed on the VPS) — here, Codex runs locally but operates on a remote filesystem.

To use it, you need to opt into the alpha via a feature flag. Check the official OpenAI Codex CLI documentation for the current flag name and opt-in process, as this is actively changing. As of early 2026 the feature was controlled by a flag set in your Codex config or passed as a CLI argument.

Once enabled, you configure a remote connection in your Codex settings pointing at an SSH host defined in your ~/.ssh/config:

# ~/.ssh/config
Host myproject
  HostName your-vps-ip
  User ubuntu
  IdentityFile ~/.ssh/id_ed25519

Then in Codex, you can open a remote project by pointing at the SSH config host. Codex communicates with the remote filesystem via SSH, so your agent can read and modify files on the server without you having manually synced them.

When does this matter? If your project already lives on the VPS (e.g., a running web server), this lets you run Codex from your laptop while it edits files in place. You avoid copying files back and forth.

Current limitations (alpha): Expect rough edges. The alpha doesn't support all project types. Some file operations fall back to less efficient paths. Keep an eye on the OpenAI changelog for updates.

Troubleshooting common problems

codex: command not found after installing

npm global bin directory isn't in your $PATH. Find where npm installs globals:

npm config get prefix
# /usr/local

Add {prefix}/bin to your PATH:

export PATH="/usr/local/bin:$PATH"
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc

OAuth callback URL mismatch error

The redirect URL registered with OpenAI must match what Codex expects. This usually means the port-forwarding port doesn't match what Codex is listening on. Run codex auth login --verbose if available, or check the Codex docs for the exact callback port.

AllowTcpForwarding no on the server

Some minimal VPS images disable TCP forwarding. Edit /etc/ssh/sshd_config:

sudo nano /etc/ssh/sshd_config
# Change: AllowTcpForwarding no
# To:    AllowTcpForwarding yes
sudo systemctl restart sshd

Codex hangs without output

It might be waiting for input or hitting a rate limit. Attach to your tmux session and check the pane. Also check ~/.codex/logs/ if the CLI writes logs there.

Rate limit or quota errors

These come from the OpenAI API, not from Codex or your VPS. Check your usage at platform.openai.com. Codex CLI running 24/7 on a VPS can burn through quota faster than interactive use.

One environment for all your coding agents

If you're already maintaining a VPS for Codex, you'll probably end up running Claude Code on it too. Or OpenCode. The per-agent setup — install, auth, tmux config, SSH keys, port-forwarding — compounds quickly.

Grass takes a different angle: pre-configured cloud VMs that are always on, designed specifically for running AI coding agents. It's agent-agnostic, so the same environment that runs Claude Code also runs Codex CLI. You bring your own API keys — Grass never touches them (BYOK model) — so your OpenAI key stays yours.

What's relevant if you're doing the VPS setup manually:

  • Session persistence is built in. Sessions survive disconnects and you reconnect to pick up where you left off, without configuring tmux yourself.
  • Mobile control: monitor and steer agents from your phone, approve or deny tool executions (bash commands, file writes) from a native modal. Useful when you're away from your desk and want to check on a long Codex run.
  • Free tier: 10 hours, no credit card required.

If you want to evaluate it before committing to another VPS, the free tier lets you run Codex CLI and see how the environment compares to your manual setup.

FAQ

Can I run Codex CLI without a browser on a headless VPS?

Yes, but you need to handle the OAuth callback. The SSH port-forwarding method in this guide tunnels the callback to your local browser. Some Codex CLI versions also support direct API key auth via OPENAI_API_KEY, which skips OAuth entirely — check your version's docs.

Does Codex CLI work on Ubuntu 22.04 / Debian 12?

Yes. Both are well-supported. Install Node.js 20+ via NodeSource or nvm, then install Codex CLI via npm. The OS itself isn't the complication — the OAuth flow is.

How do I keep Codex running when I close my SSH session?

Use tmux. Start a session before running Codex, detach with Ctrl-b d, and reattach later with tmux attach-session -t codex. The process keeps running on the server regardless of your SSH connection state.

What is the Codex remote connections alpha and how do I enable it?

It's an OpenAI feature (currently in alpha, feature-flag-gated) that lets Codex CLI operate on remote project files over SSH without installing Codex on the remote server. Codex reads and writes files on the remote machine via your SSH config. Check the official OpenAI Codex CLI documentation for the current opt-in method, as it's actively evolving.

Is there a simpler way to run multiple coding agents (Codex, Claude Code) on the same remote machine?

Manually, you'd replicate the auth and tmux setup for each agent. Grass (codeongrass.com) provides an always-on cloud VM that's agent-agnostic and handles session persistence, mobile monitoring, and permission approval without per-agent configuration.