Codex CLI on a VPS: Setup, Sign-In Over SSH and Security

Published on

Install OpenAI's Codex CLI on a Linux VPS, sign in over SSH with a device code or API key, keep it running in tmux and set its sandbox and approvals safely.

A smartphone on grey fabric showing Python code in a dark editor, partly out of focus

You want OpenAI's Codex to keep working on a server while your laptop is closed, but its first sign-in expects a browser, and a VPS has none. Codex CLI, OpenAI's terminal coding agent, reads your code, edits files and runs commands on whatever machine it runs on. This guide installs it on a Linux VPS as OpenAI's docs describe, signs in over SSH, keeps it running in tmux and locks down its sandbox, with commands for Ubuntu 24.04 and Debian 12. Using Claude Code instead? See our Claude Code VPS guide.

Quick answer: Codex CLI needs Ubuntu 20.04+ or Debian 10+ and at least 4 GB of RAM, with 8 GB recommended. Install it as a normal user with curl -fsSL https://chatgpt.com/codex/install.sh | sh. To sign in without a browser, run codex login --device-auth after you turn on device code login in your ChatGPT security settings, tunnel port 1455 over SSH, or use an API key. Install bubblewrap for the sandbox (Ubuntu 24.04 may also need an AppArmor profile), run Codex inside tmux and keep the default workspace-write sandbox with on-request approvals. Your plan's limits, or API billing, apply on a VPS just as on a laptop.

What You Need

From the system requirements in OpenAI's Codex repository and the pricing page:

  • Ubuntu 20.04+ or Debian 10+, on x86_64 or ARM64.
  • 4 GB of RAM minimum, 8 GB recommended.
  • Git 2.23 or newer, optional but recommended. Ubuntu 24.04 and Debian 12 ship newer versions.
  • A plan that includes the CLI (Plus, Pro, Business, Enterprise or Edu) or an API key.

On our plans, VPS-S (4 GB) meets the minimum and VPS-M (8 GB) the recommendation, in both tiers; the 2 GB Premium VPS-XS falls short. Our VPS page for AI agents lists them, and the order form marks Ubuntu 24.04 LTS as recommended.

Step 1: Prepare the Server

Codex runs commands as the user that started it, so give it its own account outside the sudo group. OpenAI's remote connections page asks for "trusted keys, least-privilege accounts, and no unauthenticated public listeners" on any SSH host Codex works on. Ubuntu's user management guide creates the account:

sudo adduser agent

On your own computer, create a key and copy it over, as in Ubuntu's OpenSSH guide, with your VPS's IP address in place of 203.0.113.10:

ssh-keygen -t ed25519
ssh-copy-id agent@203.0.113.10

Then, from your admin account on the server, install tmux, Git, bubblewrap for the sandbox and curl for the installer. Leave out sudo if you're logged in as root:

sudo apt update
sudo apt install tmux git bubblewrap curl

Our Linux VPS beginners guide covers these first steps in more detail.

Step 2: Install Codex CLI

Log in as the new user (ssh agent@203.0.113.10) and run the standalone installer from the Codex CLI page:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

The script checks the download's SHA-256 checksum, puts codex in ~/.local/bin and, for a bash user, adds that folder to your PATH in ~/.bashrc. Answer its final Start Codex now? [y/N] with Enter, log in again so the new PATH applies, then check:

codex --version

Running the installer again updates Codex, as does codex update, and codex doctor reports on the installation, configuration, sign-in, Git and terminal. With Node.js, the docs' alternative is npm install -g @openai/codex.

Step 3: Sign In Over SSH

The first codex run asks how you want to sign in, and codex login starts the same flow. ChatGPT sign-in opens a browser and hands the result to a callback server on localhost:1455 of the machine running Codex. Here that machine is the VPS, which your laptop's browser can't reach. OpenAI's authentication docs offer three ways around that, plus API keys.

Device code (beta, OpenAI's preferred route). Turn on device code login in your ChatGPT security settings first; in a Business or Enterprise workspace, an admin enables it in the workspace permissions. Then run:

codex login --device-auth

Open the printed link on your phone or laptop, sign in and enter the one-time code. The first-run screen calls this Sign in with Device Code. Only enter codes your own terminal printed.

Forward the callback port. Connect from your computer with a tunnel for port 1455, run codex login in that session and open the printed address in your local browser:

ssh -L 1455:localhost:1455 agent@203.0.113.10

Copy your login. Copying ~/.codex/auth.json from your computer also works, but OpenAI's CI/CD auth guide says not to share one file between machines, since a token refresh on one can break the other.

API key. To pay per use through your OpenAI Platform account instead of your plan, pipe a key into codex login. Bash's read -s keeps it off the screen and out of your shell history:

read -rs OPENAI_API_KEY && export OPENAI_API_KEY
printenv OPENAI_API_KEY | codex login --with-api-key
unset OPENAI_API_KEY

codex login status prints the active method and exits with 0 when you're logged in. ChatGPT logins refresh their tokens during use.

By default, the login sits in plain text in ~/.codex/auth.json, and the docs say to treat it "like a password: it contains access tokens." Codex creates the file readable by your user only, but a copied file may not be, so set the permissions as OpenAI's CI guide does:

chmod 700 ~/.codex
chmod 600 ~/.codex/auth.json

Step 4: Keep It Running with tmux

When your SSH connection drops, the terminal Codex runs in goes with it. tmux keeps a terminal open on the server; these commands follow the tmux Getting Started guide:

tmux new -A -s codex
cd ~/projects/myapp
codex

-A attaches to the codex session if it exists and creates it otherwise. Give Codex a task, press Ctrl+b and then d, and tmux prints [detached (from session codex)] while Codex keeps working. Run the same tmux new -A -s codex later to get the screen back; tmux ls lists your sessions. Codex still waits whenever it needs your approval, so check in now and then.

Work in a Git repository (git init for a new project). The Codex CLI page suggests Git checkpoints before and after each task, and codex exec refuses to run outside a repository by default. After a reboot, codex resume --last in the project folder reopens your most recent chat.

Step 5: Set the Sandbox and Approvals

Two settings decide what Codex does on its own, according to OpenAI's approvals and security page. The sandbox mode (read-only, workspace-write or danger-full-access) limits what commands can do, and the approval policy (on-request or never) decides when Codex stops to ask.

In a Git repository, Codex recommends its Auto preset: workspace-write with on-request. Codex reads, edits and runs commands in the project folder and in temporary folders such as /tmp, and asks before it edits elsewhere or runs a command that needs the network, which is off by default. Inside the project, .git, .codex, .agents and .aws stay read-only, so git commit can still ask for approval. /permissions changes the mode mid-session, and /status shows the policy and writable folders. For a repository you don't trust yet, start with codex --sandbox read-only --ask-for-approval on-request.

On Linux the sandbox uses bubblewrap (bwrap) plus seccomp, and Codex warns at startup when bwrap is missing or can't create the user namespace it needs. On Ubuntu 24.04 that warning can appear even with bubblewrap installed, because of an AppArmor restriction. OpenAI's sandbox page fixes it with the bwrap-userns-restrict profile that Ubuntu ships in apparmor-profiles. Run this from your admin account:

sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

As the profile's comments explain, bwrap gets its user namespace, but the commands it starts get no extra capabilities. The docs' last resort, sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0, lifts the restriction for every program instead. codex sandbox linux -- ls tests the sandbox by hand.

Skip --dangerously-bypass-approvals-and-sandbox (alias --yolo), which removes both the sandbox and the approvals. The CLI reference reserves it for "an externally hardened environment" or a dedicated sandbox VM, and OpenAI warns that with full access in a dev container, a malicious project can exfiltrate anything available there, including Codex credentials. A VPS with SSH keys, deploy keys or a database on it is no different.

Where the Config File Lives

Your settings live in ~/.codex/config.toml, per config basics, and CODEX_HOME moves the whole folder. Flags and -c key=value override the file, and /etc/codex/config.toml sets system-wide defaults. A repository's own .codex folder, with its config, hooks and rules, loads only once you trust the project, so don't trust a clone you haven't read. A starting point for a server:

# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[shell_environment_policy]
ignore_default_excludes = false

The first two lines make the Auto preset explicit. The last one matters on a server: by default, Codex passes environment variables whose names contain KEY, SECRET or TOKEN to the commands it runs, and false filters them out, as the advanced config page explains. network_access = true under [sandbox_workspace_write] gives commands the network, but OpenAI warns that prompt injection can then make the agent fetch and follow untrusted instructions. If an old config contains approval_policy = "untrusted", remove it: that value is retired and "can prevent either client from starting."

Usage Limits: ChatGPT Plan or API Key

A VPS changes where Codex runs, not how much you can use it. With ChatGPT sign-in, usage comes from your plan, according to the pricing page:

  • Plus and Standard Business get estimates, not fixed numbers: for example 15 to 160 local messages per five hours with GPT-6.1 Sol, depending on the task. Weekly limits may also apply, and cloud chats draw from the same allowance.
  • Pro plans currently have no five-hour limit.
  • At the limit, a turn that is already running can keep going, subject to fair use. Plus and Pro can buy credits, and anyone can run extra local chats with an API key.
  • /status shows what's left during a session, and the usage dashboard shows when limits reset.

With an API key, OpenAI bills usage at standard API rates through your OpenAI Platform account. You get the CLI without cloud features such as GitHub code review, and only the models your key can use.

Unattended Runs with codex exec

codex exec runs one task from a script or scheduled job without the terminal interface. Two examples from the non-interactive mode page:

codex exec "summarize the repository structure and list the top 5 risky areas"
codex exec --sandbox workspace-write "<task>"

It starts in a read-only sandbox, so add --sandbox workspace-write when the task has to edit files; --full-auto from older guides is no longer supported. It reuses your saved login, but OpenAI recommends API keys for automation, and CODEX_API_KEY passes one to a single run. Don't export OPENAI_API_KEY or CODEX_API_KEY for a whole job that also runs repository code such as tests, because that code can read them.

Optional: Use It from the ChatGPT Desktop App

The ChatGPT desktop app for macOS and Windows can run chats on an SSH host. With Codex installed and signed in on the VPS, add a host alias to ~/.ssh/config on your computer, where the app looks for hosts:

Host codex-vps
  HostName 203.0.113.10
  User agent
  IdentityFile ~/.ssh/id_ed25519

Then add the host under Settings > Connections and pick a project folder. The app starts Codex in the remote user's login shell, so this check should print a path:

ssh codex-vps 'bash -lc "command -v codex"'

Your phone can then reach the VPS through that computer while it stays awake and online. Mobile setup starts in the desktop app and needs ChatGPT sign-in, not an API key. Don't expose Codex's app server to the internet; the docs point to a VPN instead.

Security Basics

  • A separate user without sudo, as in step 1. Our guide to securing an AI agent on a VPS adds outbound firewall rules for that user and audit logs.
  • SSH keys only. Our SSH hardening guide switches password login off.
  • Only SSH open. The device code and the tunnel need no other port. With UFW, run sudo ufw allow 22 before sudo ufw enable, as in Ubuntu's firewall guide; Debian 12 needs sudo apt install ufw first. Our UFW and Fail2Ban guide goes further.
  • Few secrets on the box. Treat auth.json and API keys as passwords, and keep keys this server doesn't need somewhere else.
  • Your own backups. Backups aren't included in the price of our VPS plans and can be arranged through a support ticket. Commit and push often either way.

FAQ

How much RAM does Codex CLI need on a VPS? At least 4 GB, with 8 GB recommended. The model runs on OpenAI's servers, so the RAM goes to Codex, your tools and the commands it starts.

Can I use Codex CLI with the free ChatGPT plan? OpenAI's pricing page doesn't list the CLI for Free or Go: those plans get GPT-6 Luna in the desktop app, subject to rollout. The CLI is listed for Plus, Pro, Business, Enterprise and Edu, and for API keys.

Does Codex keep working when I close my laptop? Yes, if it runs in tmux on the VPS. It still pauses for approvals, and your plan's usage limits still apply. Reattach with tmux new -A -s codex.

Do I need a GPU? No. With OpenAI's models, the VPS only runs Codex and your code. Only --oss runs a model on the server, through a local provider such as Ollama; our Ollama guide shows what CPU-only hardware can do.

Can I control Codex on my VPS from my phone? Yes, through the ChatGPT desktop app on a Mac or Windows PC that stays on, with the VPS added as an SSH host. Without one, an SSH app on your phone can attach to the tmux session.

Sources

All opened on 30 October 2026:

Codex, ChatGPT and OpenAI are trademarks of OpenAI. Space-Node is not affiliated with or endorsed by OpenAI or by the makers of the other tools named in this guide.