Skip to content
LayerbaseLayerbase

How to Run OpenAI Codex CLI on a Remote Server

4 min readWorkspacesTutorial

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 Workspace 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. Workspaces is 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 workspace 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 workspace pays for the machine; Codex usage goes to your ChatGPT plan or your API key, under their own limits.

1. Install Codex

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

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

Then check that the shell can find it:

bash
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:

bash
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:

text
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:

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

Either way, confirm the result:

bash
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:

bash
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:

bash
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 workspace connected to the Layerbase GitHub App, the layerbase-clone helper does the clone and the worktree in one step:

bash
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:

bash
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:

bash
codex
text
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 workspace, 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 workspace, 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.

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. For the product overview, read Introducing Layerbase Workspaces.

Keep reading