Getting started with OpenAI's Codex

Codex is a terminal-based coding agent from OpenAI that can read files, edit code, and run commands in your working directory. It can be run pretty much anywhere: your PC, laptop, server, even your phone (with which you can control your computer!). Running it on a VPS gives you a persistent Linux environment for long-running coding sessions, remote repositories, and development work that continues independently from your laptop.

In this guide, you install and/or use Codex on a Linux VPS and use it securely over SSH. This is a practical setup for development and automation work, because the language model itself runs through OpenAI, using your ChatGPT account or an OpenAI API key, and not on your VPS. Alternatively, you can also use self-hosted models (e.g. through Ollama) to power Codex.

Why a GPU is not required for Codex

For a standard Codex CLI setup, your server does not perform model inference itself. In practice, this means a CPU-only server is enough as long as the server has sufficient memory, internet access, and a supported Linux distribution.

Your server mainly provides the shell, filesystem access, git repository, and runtime environment in which Codex works. A faster CPU and more memory improve local tasks such as package installs, tests, indexing, and builds, but a GPU is not a requirement for the Codex CLI itself.

What server specifications do I need to run Codex effectively?

The system requirements to run Codex depends on your setup, but mostly comes down to the system requirements of your operating system:

• server with Ubuntu + Codex accessed through your ChatGPT / OpenAI API account: 2 CPU cores 4GB RAM.
• server with Ubuntu + Codex + external Ollama server hosting the LLM: 2 CPU cores 4GB RAM.
• server with Ubuntu + Codex + local Ollama server hosting the LLM: Specifications depend on the chosen LLM, but assume a minimum of 32GB RAM for any practical usage. See this guide for an outline on how to pick the right specifications. 

Installing Codex manually

Step 1

Connect to your server via SSH, the VPS console (VPS), or the OpenStack console (OpenStack instance).

Step 2

Update your server and install the tools used in this guide:

sudo apt -y update && sudo apt -y upgrade && sudo apt -y install curl git build-essential tmux nodejs npm bubblewrap

In this command, curl is useful for downloads, git is used for repositories, build-essential provides common build tools for local dependencies, tmux keeps your shell session running after you disconnect from SSH, nodejs and npm are used to install Codex, and bubblewrap provides reliable Linux sandboxing for commands run by Codex.

Step 3

Install Codex with npm:

npm i -g @openai/codex

If npm gives you a permissions error, configure npm to install global packages for your own user account and try again:

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm i -g @openai/codex

This avoids installing Codex as root and keeps the executable in your user's PATH.

Step 4

Reload your shell and verify that Codex is available:

source ~/.bashrc
command -v codex

If a path such as /home/username/.local/bin/codex is shown, Codex is available from your shell.

Step 5

Finally, start Codex:

codex

On first launch, Codex takes you through authentication and initial setup. See the next chapter for the steps involved.

Codex onboarding and authentication

Step 1

When you first run Codex with the command codex, Codex asks you to sign in. You can sign in with your ChatGPT account or with an OpenAI API key.

For most interactive use on a server, signing in with ChatGPT is the easiest option:

codex login

If your server cannot open a browser, use the device authentication flow instead:

codex login --device-auth

Codex then shows a login code and a URL. Open the URL in your local browser, enter the code, and complete the login.

Step 2

Check whether Codex is logged in:

codex login status

If the command confirms that credentials are present, Codex is ready to use.

Step 3

Start Codex in a project directory:

mkdir -p ~/projects/example-project
cd ~/projects/example-project
codex

From this point on, simply chat with Codex to use it. For example, git clone a repository to your server, navigate to the directory, launch Codex and tell it something like “I'm working in this git repo for <description of project> and I'm looking to fix a bug in file <filename>. Please help me fix it.”

Using Ollama with Codex

As an alternative to using Codex with your ChatGPT account or an OpenAI API key, you can also use an LLM hosted through Ollama on the same server or on a remote server. This lets Codex use a local or Ollama-hosted open-weight model instead of an OpenAI-hosted model.

Ollama installed on same server as Codex

The quickest way to launch Codex with Ollama is:

ollama launch codex

To configure Codex for Ollama without launching it immediately, run:

ollama launch codex --config

You can also start Codex manually with Ollama by using the --oss flag:

codex --oss

By default, Codex uses Ollama as the local provider for OSS mode. To use a specific model, pass the model with -m, for example:

codex --oss -m gpt-oss:120b

Ollama installed on another server than Codex & persistent setups

For a persistent setup, add an Ollama provider and profile to ~/.codex/config.toml:

First, open the file:

nano ~/.codex/config.toml

Make sure the following content is added/updated in the file, save your work, and close the file (ctrl + x > y > enter).

[model_providers.ollama-launch]
name = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "responses"

[profiles.ollama-launch]
model = "gpt-oss:120b"
model_provider = "ollama-launch"
model_context_window = 131072
model_auto_compact_token_limit = 90000
model_supports_reasoning_summaries = false

Then start Codex with that profile:

codex --profile ollama-launch

Using Codex with an API key

As an alternative to signing in with a ChatGPT account, you can use Codex with an OpenAI API key. This is especially useful for scripts, CI/CD workflows, and other programmatic use cases.

To log in with an API key without printing the key to the terminal, run:

read -rsp "OpenAI API key: " OPENAI_API_KEY; echo
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY

Check the login status afterwards:

codex login status

If you later want to remove saved Codex credentials from the server, run:

codex logout

Useful commands

Codex can be used both from inside an interactive Codex session and directly from the Linux shell. The commands below are useful once Codex is installed and authenticated.

Start or continue a session

Start Codex in the current directory:

codex

Start Codex with an initial prompt:

codex "explain this project"

Resume a previous interactive session:

codex resume

Resume the most recent session for the current directory:

codex resume --last

Permissions

You can loosen Codex's approval settings with the permissions menu:

/permissions

You can also start Codex with a different approval policy, for example:

codex --ask-for-approval never

Be careful with this on a server. If you also bypass the sandbox with --dangerously-bypass-approvals-and-sandbox or --yolo, Codex can run commands without approvals or sandboxing. Only use that in an isolated environment.

Run Codex non-interactively

Use codex exec if you want Codex to perform one task and then exit. This is useful for checking logs, explaining files, generating summaries, or using Codex in scripts:

codex exec "summarize the current git diff"

You can also pipe content into Codex:

cat logs.txt | codex exec "explain the error and suggest a fix"

To make non-interactive output easier to process in scripts, use JSON Lines output:

codex exec --json "summarize the repository structure" | jq

Useful commands inside Codex

The following commands are entered inside an active Codex session:

/help

Shows the available commands.

/init

Generates an AGENTS.md scaffold in the current directory. This file can describe the project, commands, coding style, test instructions, and anything else Codex should remember for this repository.

/permissions

Opens the permissions overview, where you can review or change what Codex may do without asking first.

/model

Lets you choose the active model and, where available, reasoning level.

/fast

Toggles Fast mode for supported models.

/plan fix the login bug

Starts plan mode for a larger change. This is useful when you want Codex to first propose an approach before editing files.

/diff

Shows the Git diff, including files that Git is not tracking yet. Use this to review Codex's edits before committing.

/review

Asks Codex to review your working tree. This is useful after Codex completes work or when you want a second review of local changes.

/compact

Summarizes the visible conversation to free up context while keeping the important details.

/clear

Clears the terminal and starts a fresh chat.

/new

Starts a new conversation inside the same Codex CLI session.

/resume

Opens the session picker so you can continue an earlier conversation.

/status

Shows session configuration, token usage, approval policy, writable roots, and remaining context capacity.

/mcp

Lists configured Model Context Protocol tools. Use this when you have connected extra tools or services to Codex.

/plugins

Opens the plugin browser, where you can inspect, install, uninstall, enable, or disable plugins from configured marketplaces.

/skills

Shows the skills available to Codex. You can also type $ in the prompt to mention a specific skill.

$skill-creator

Starts the built-in skill creator. Use this when you want Codex to help create a reusable skill with instructions, optional scripts, and references.

/logout

Signs out of Codex from inside the interactive session.

/quit

Exits Codex. /exit works as an alternative command.

Install plugins and skills

Codex uses plugins to add reusable workflows, app integrations, MCP servers, and skills. Skills are reusable instructions and resources that Codex can load when they match a task.

Show the skill overview (simply type the numbers of the skills you want installed):

$skill-installer

Open the plugin browser from inside Codex:

/plugins

Add a plugin marketplace from the shell:

codex plugin marketplace add owner/repository

Update configured plugin marketplaces:

codex plugin marketplace upgrade

Remove a marketplace:

codex plugin marketplace remove marketplace-name

After installing or changing plugins, start a new Codex thread and ask Codex to use the plugin. You can also type @ in the prompt window to invoke a specific plugin or one of its bundled skills explicitly.

Update, authenticate, and troubleshoot

Check whether Codex is installed:

command -v codex

Update Codex with npm:

npm i -g @openai/codex@latest

If your Codex installation supports the built-in updater, you can also run:

codex update

Check login status:

codex login status

Log in again:

codex login

Log in using the device flow:

codex login --device-auth

Log out:

codex logout

Print configuration diagnostics from inside Codex:

/debug-config

Print the current session status from inside Codex:

/status

Tips for using Codex safely on a server

Codex can read files, modify code, and run shell commands. For that reason, it is worth taking a few minutes to separate your working environment from the rest of the server.

Step 1

Start a persistent terminal session before opening Codex:

tmux new -s codex

If your SSH connection drops, tmux keeps the session alive. Reconnect later with:

tmux attach -t codex

Step 2

Work inside a dedicated project directory instead of your full home directory or system paths:

mkdir -p ~/projects/example-project
cd ~/projects/example-project
codex

This keeps the scope of file access predictable and makes it easier to review what Codex can reach.

Step 3

Use an AGENTS.md file to document how Codex should work in your project:

cat > AGENTS.md <<'EOF'
# AGENTS.md

## Project instructions
- Run tests before proposing final changes.
- Prefer small, focused commits.
- Do not edit production secrets or deployment keys.
EOF

Codex reads AGENTS.md files before working, so this is a useful place to define project-specific instructions, test commands, coding style, and safety rules.

Step 4

Open the Codex permissions overview from inside Codex with:

/permissions

Codex uses sandboxing and approvals together. The sandbox controls what Codex can technically access, such as writable directories and network access. The approval policy controls when Codex must stop and ask you before continuing.

On a normal development server, keep the default approval flow unless you are operating in a deliberately isolated environment.

Step 5

Avoid running Codex as root unless you truly need system-wide changes. If you normally log in as root, create a separate user first:

adduser codex
usermod -aG sudo codex
su - codex

A separate user reduces the risk of accidental changes to system files. Use sudo only for the commands that actually need elevated privileges.

Do not use --dangerously-bypass-approvals-and-sandbox or --yolo on a server that also contains production data, deployment keys, or customer information. These modes bypass important safety controls and should only be used in an externally hardened environment, such as an isolated disposable container or runner.

Updating Codex

New versions of the Codex CLI are released regularly. If you installed Codex with npm, update it with:

npm i -g @openai/codex@latest

Some Codex installations also support the built-in updater:

codex update

After updating, restart Codex:

codex

or to resume your earlier session:

codex resume

Codex works well on a server without a GPU because the server provides the development environment while the model runs remotely through OpenAI. With a small amount of preparation, especially a dedicated user, a dedicated project directory, an AGENTS.md file, bubblewrap sandboxing, and a tmux session, you get a practical and controlled remote coding setup.