How to Run OpenAI Codex CLI on a Remote Server

Codex is happy to run for a long time on a big task. Your laptop is less happy about it: close the lid and the session dies, and a second task in the same checkout steps on the first. Moving Codex to a remote server fixes both. The server holds the repo and runs the CLI, and you approve account sign-in from your own browser.

This walkthrough uses a Layerbase Agent Server named codex-box. The steps that matter (device code sign-in, checking for a stray API key, working in a worktree) apply to any Linux server you control. Agent Servers are in beta under the early adopter terms, so start with a development project and keep your code pushed to GitHub.

What you need

• A Linux server with a shell. Here, a server running Ubuntu 24.04.
• A ChatGPT account whose plan includes Codex, or an OpenAI API key.
• A browser on your own computer for approving sign-in.

The server and the model are billed separately. A server pays for the machine; Codex usage goes to your ChatGPT plan or your API key, under their own limits.

1. Install Codex

On a server, choose Codex in the agents panel and the server installs it. On any other server, use OpenAI's installer:

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

Then check that the shell can find it:

codex --version

If the command is not found, open a new shell so your PATH picks up the install, and wait for any installer still running to finish before starting another.

2. Sign in with a device code

The default codex login flow opens a browser on the same machine and waits for a callback on localhost:1455. A remote server has no browser, so use the device code flow instead.

First, once per ChatGPT account: open ChatGPT, go to Settings > Security and login, and turn on Enable device code sign-in for Codex, Excel, PowerPoint, and Word.

Then, in the server's terminal:

codex login --device-auth

Codex prints a short code. On your own computer, open auth.openai.com/codex/device, pick your ChatGPT account, and enter the code. It expires after 15 minutes. When it works, the terminal prints:

Successfully logged in

Only enter a device code you started yourself, and never paste one into a chat, a ticket, or a project file. If it expires, run the command again for a fresh one.

If you would rather use the regular browser flow, forward the callback port over SSH from your computer and run codex login inside that session:

ssh -L 1455:localhost:1455 ubuntu@<your-server>
codex login

Either way, confirm the result:

codex login status

3. Check for an API-key override

An OPENAI_API_KEY in the environment changes who pays. If you meant to use your ChatGPT plan, check for one without printing it:

if [ -n "${OPENAI_API_KEY:-}" ]; then
  printf '%s\n' 'An API key is set in this shell.'
else
  printf '%s\n' 'No API key is set in this shell.'
fi

If you do want API billing, that is a supported path too. Log in with the key instead of your account:

printenv OPENAI_API_KEY | codex login --with-api-key

If a key keeps coming back after unset, look for it in your shell startup files. Do not paste your environment into a support request to find it.

4. Put your repo in a worktree

Give each task its own git worktree so two Codex runs never share a working tree. On a server connected to the Layerbase GitHub App, the layerbase-clone helper does the clone and the worktree in one step:

layerbase-clone acme/web --worktree fix/login-redirect
cd ~/worktrees/acme/web/fix-login-redirect

The home checkout lives at ~/dev/acme/web, and each branch gets a folder under ~/worktrees, with slashes in the branch name turned into hyphens. On another server, plain git does the same job:

git clone git@github.com:acme/web.git ~/dev/acme/web
cd ~/dev/acme/web
git worktree add -b fix/login-redirect ~/worktrees/acme/web/fix-login-redirect
cd ~/worktrees/acme/web/fix-login-redirect

Now start Codex with a bounded first task:

codex

Find why /login redirects to / instead of the original page after sign-in.
Fix it, add a test that covers the redirect, and run the existing test suite.
Do not change unrelated files.

Review what it proposes, approve what you want, and read the diff before you commit.

5. Keep project rules where Codex reads them

Codex reads AGENTS.md files for instructions: a global one at ~/.codex/AGENTS.md, plus any in the repository. Put the rules you would otherwise repeat in every prompt there, such as the test command, the package manager, and which branches are off limits. On a server, rules you write once in the dashboard are added to each supported agent's instruction file, so Codex and Claude Code follow the same ones.

6. Disconnect and come back

On a server, the browser terminal keeps its session running on the server. Close the tab, reopen the Terminal tab later, and you are back in the same shell with Codex where you left it. On your own server, run Codex inside tmux to get the same effect over SSH.

Two limits to know. A task waiting for your approval stays waiting; closing the tab does not answer it. And stopping or rebooting the machine ends running processes, so a surviving session is not a promise of uninterrupted work.

For uploads and connection details, see the web terminal docs.

Bring the session to your phone

Codex can stay on the VM while you leave your desk. From your phone, open the server and select its existing named terminal session. That can mean investigating a critical outage from dinner or preparing a small feature for review.

First-time setup is easier on a computer while you connect GitHub, select repositories, and sign in to your agent subscriptions. Afterward, open Agent Servers on your phone and select the existing session. Layerbase is a PWA you can add to your home screen, not a native mobile app. Terminal access needs internet; the mobile experience will keep improving during beta. The browser uses the actual CLI interface, with a familiar terminal workflow and extra keys for phone keyboards.

You can also use Cursor CLI, Devin CLI, Gemini CLI, Grok Build, or other compatible Linux CLI tools. Devin Desktop is the editor formerly called Windsurf; this workflow uses Devin CLI. Without an agent subscription, install OpenCode and select an available free model, subject to changing availability and limits. VM charges and paid model usage remain separate.

For work and personal subscriptions, keep separate VMs signed in to the appropriate agent accounts, with the intended repositories selected for each. Terminal tabs on one VM share its user environment and do not isolate credentials. Follow the mobile setup walkthrough before you need it on the go.

Before you walk away

Push the branches you want to keep and remove worktrees you are done with (git worktree remove <path>). The machine keeps billing while it sits idle, and stopping it does not cancel the monthly renewal.

If you use Claude Code as well, the same setup works for it: see How to Run Claude Code on a VPS. To bring file uploads, repository setup, and code review into the same workflow, follow the browser coding walkthrough.

Your next task can start in the same environment, without setting up another computer. Explore Agent Servers for current sizes. Agent Server and agent charges are separate; Layerbase managed databases still have a free tier.