VPS Tutorials
Deploying Codex CLI on a VPS (2026): Installing, Logging In, and Running a Remote Development Environment Persistently
Install Codex CLI on an Ubuntu/Debian VPS, configure ChatGPT or API Key login, and set up a recoverable remote development environment using a regular user and tmux.
Deploying Codex CLI on a VPS (2026): Installing, Logging In, and Running a Remote Development Environment Persistently
If you already rent a Linux VPS and want to use it as an always-online remote development machine, Codex CLI is a very practical entry point: after logging in over SSH, you can read code, edit files, and run tests directly in the project directory. The real pitfalls are not npm install, but how to authenticate in a headless environment, how to limit permissions, and how to continue after the process disconnects.
This article uses Ubuntu 22.04/24.04 and Debian 12 as examples, going from a clean VPS to a Codex CLI setup that can be used long term. All commands can be copied and executed, but replace the API Key, project path, and Linux username with your own values.
Codex CLI itself does not need a high-end CPU; the main consumption comes from Node.js, code indexing, test commands, and the services you run at the same time. For personal projects, start with the following configurations:
| Purpose | Recommended configuration | Notes |
|---|---|---|
| Small scripts, static sites | 2 cores / 2GB / 40GB SSD | Suitable for editing and running tests side by side |
| Node, Python full-stack projects | 2-4 cores / 4GB / 60GB NVMe | Leaves headroom for dependency installation and builds |
| Multi-repository or Docker projects | 4 cores / 8GB / 80GB NVMe | More stable when running databases, tests, and builds simultaneously |
It can be installed with only 1GB of memory, but npm install, TypeScript compilation, or Docker builds can easily trigger OOM. It is best to separate production services from the Codex working directory, and at least create a regular user; do not let the coding agent operate in the root directory all the time.
Log in via SSH and update the system:
ssh root@YOUR_SERVER_IP
apt update && apt full-upgrade -y
apt install -y ca-certificates curl git build-essential unzip tmux
Create a working user:
adduser coder
usermod -aG sudo coder
mkdir -p /srv/workspaces
chown -R coder:coder /srv/workspaces
su - coder
If you have not yet configured SSH keys, complete key-based login first before disabling password login. When troubleshooting Permission denied, you can refer to the VPS SSH Permission denied troubleshooting checklist. Do not expose port 22 to all sources without any restrictions before the Codex deployment is complete.
Codex CLI officially supports npm installation. For a production VPS, it is not recommended to use the old Node.js bundled with the distribution; install the NodeSource LTS version first:
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version
After confirming the Node.js version meets the project requirements, install Codex:
sudo npm install --global @openai/codex
codex --version
Upgrading is also simple:
sudo npm update --global @openai/codex
If the system prohibits global npm writes, you can use nvm to install Node.js, then run the global installation as the coder user. Do not change the entire /usr directory to 777 just for convenience.
Codex CLI supports ChatGPT login and API Key login. Running codex login on a computer with a desktop opens an authorization page in the browser; a pure SSH VPS usually has no browser, so an API Key is more suitable for automation or remote machines.
Run the following in the project directory on the VPS:
mkdir -p /srv/workspaces/demo && cd /srv/workspaces/demo
codex login
If the terminal provides an authorization URL, open it in a browser on your local computer, complete the login, and return to the SSH session. Different CLI versions may display slightly different prompts; just follow the terminal instructions. You can check the login status with:
codex login status
Do not write the API Key directly into shell history. Pass it to the CLI via standard input using a protected environment variable:
read -s OPENAI_API_KEY
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status
If you need to use it for systemd or CI, put the Key in a credentials file readable only by coder:
mkdir -p /home/coder/.config
install -m 600 /dev/null /home/coder/.config/codex.env
printf 'OPENAI_API_KEY=replace-me\n' > /home/coder/.config/codex.env
Do not commit .config/codex.env to Git, and do not put the Key into ~/.bashrc and then take screenshots or paste it into tickets. API Key login is billed by API usage and is suitable for scripts and continuous integration; ChatGPT login uses the permissions and quota of the corresponding ChatGPT workspace. For specific authentication behavior, refer to the Codex CLI documentation in OpenAI Docs and Authentication.
Switch to the code repository:
cd /srv/workspaces/demo
git clone YOUR_REPOSITORY_URL .
git status
codex
For the first conversation, it is recommended to have Codex perform a read-only inspection of the project first, then allow modifications:
先阅读项目结构和 README，只告诉我启动命令，不要修改文件。
After confirming the working directory, propose a small change and require tests to be run. The smaller the workspace permissions, the better: do not put /etc, database backup directories, or cloud provider credential directories into the Codex working directory. For production projects, create a Git branch or commit a checkpoint first so you can roll back.
If you run codex directly, the process usually ends when SSH disconnects. The simplest approach is to use tmux:
tmux new -s codex
cd /srv/workspaces/demo
codex
Press Ctrl+b, then d to exit the session while keeping the process running; after logging in again, restore it:
tmux attach -t codex
View existing sessions:
tmux ls
tmux is suitable for manual operation; it is not recommended to turn an interactive coding agent that requires permission confirmation into an unattended boot service. Only consider systemd if you are running a fixed codex exec script, and set up a dedicated user, working directory, resource limits, and read-only credentials for the service.
This is usually because the npm global directory is not in PATH. Locate it first:
npm prefix --global
which node
which npm
When installing globally with sudo, confirm that /usr/bin or the npm bin directory is in the current user's PATH; when using nvm, reload the corresponding shell configuration.
Check the repository owner and directory permissions:
whoami
ls -ld /srv/workspaces/demo
sudo chown -R coder:coder /srv/workspaces/demo
Do not use chmod -R 777 to solve permission problems; this would expose source code, .env, and SSH configuration to other users on the same machine.
First check memory and OOM logs:
free -h
dmesg -T | grep -i -E 'oom|killed process'
A 2GB VPS can temporarily add 2GB of swap, but swap cannot replace real memory. When there are many build tasks, upgrading to 4GB saves more time than repeated retries.
Confirm that the same Linux user is used to log in and run Codex, and check the status:
whoami
codex login status
Do not log in the Key as root and then switch to the coder user to run; the credential directories for the two users are different.
node --versionandcodex --versionreturn normally;- The
coderuser can read and write the project but does not have unnecessary system directory permissions; - ChatGPT login or API Key login has been selected and can be verified via
codex login status; - The API Key file permissions are
600and it has been added to.gitignore; - Interactive sessions run in tmux and can be restored after SSH disconnects;
- There is a Git branch or commit before modifications, and the test commands and rollback path are clear;
- Docker projects have separately configured healthchecks, logs, and resource limits; you can continue to refer to the VPS Docker Compose production environment configuration checklist.
The core of running Codex CLI on a VPS is not how luxurious the machine configuration is, but getting authentication, user permissions, and session persistence right. A small project can start with 2 cores and 2GB; if you need to run Docker, databases, and build tasks at the same time, choose 4 cores and 8GB directly to spend less time troubleshooting OOM.