How to run Codex on a server

Steps

1. Get a server and a user for the agent

   Take Ubuntu 20.04 or newer, or Debian 10 or newer. Codex asks for 4 GB of memory at least and recommends 8 GB. Do not run it as root: a separate user keeps its mistakes inside one home folder.

   $ ssh [email protected]
   $ adduser dev
   $ usermod -aG sudo dev
   $ su - dev

2. Install Codex

   The official installer works on Mac and Linux. If you prefer npm, npm install -g @openai/codex does the same.

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

3. Start a tmux session

   tmux keeps programs running after you disconnect. Everything you start inside it survives a closed SSH window.

   $ sudo apt install -y tmux git
   $ tmux new -s codex

4. Sign in with a one-time code

   Run the command, open the link it prints in the browser on your laptop and enter the code. The server needs no browser. Then check the result.

   $ codex login --device-auth
   $ codex login status

   Using an API key instead? Pipe it in rather than typing it as an argument:

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

5. Open your project and start Codex

   Clone the repository and run codex in it. Describe the task as you would to a colleague.

   $ git clone https://github.com/you/your-project.git && cd your-project
   $ codex

   For a one-off job that needs no conversation, codex exec runs without a chat window and prints the result.

   $ codex exec "run the tests and fix what fails"

6. Detach and close the laptop

   Press Ctrl+B, then D. You leave tmux, and Codex keeps working. Close the laptop.

Check that it works

Connect again later, attach to the same session and you see Codex where it is now. If you started it outside tmux by mistake, codex resume continues the last session.

$ ssh [email protected]
$ tmux attach -t codex
# or, to pick up the last conversation:
$ codex resume

If the one-time code is not available

Device sign-in must be switched on in your ChatGPT security settings or in the workspace permissions. If it is off, or you cannot change it, there are three other ways in.

The commands for the two middle ways. Run both on the laptop:

# port forward: keep this SSH window open, then run "codex login" in it
$ ssh -L 1455:localhost:1455 [email protected]
# copy the cache
$ ssh [email protected] 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

What Codex may do on its own

An agent that works while you sleep needs limits. Two flags set them: --sandbox takes read-only, workspace-write or danger-full-access, and --ask-for-approval decides when Codex stops to ask you (for example on-request or never). Start with workspace-write. Keep API keys and cloud credentials out of the home folder of the user that runs the agent.

Common problems