Handback

Codex login on a headless server

Updated · Jere & CO

codex login signs you in with your ChatGPT account through the browser. On your own computer that’s one click. On a box you reached over SSH, the browser opens on the box or nowhere, and if you open the link on your laptop instead, the sign-in redirects to localhost:1455 on the laptop, where nothing is listening. The terminal on the box waits.

The Codex docs list four ways out. In order of preference:

1. Device code authentication

Device code login skips the redirect entirely: Codex shows a link and a one-time code, you enter the code in any browser, and Codex picks up the result by itself. The docs recommend it for remote and headless machines. It’s marked beta, and it has to be switched on first.

  1. Turn on device code login in your ChatGPT security settings (personal account) or in the workspace permissions (if you’re a workspace admin).
  2. On the box, run this (or choose “Sign in with Device Code” in the interactive login):
codex login --device-auth
  1. Open the link on your laptop or phone, sign in, and enter the code.

If your account or workspace doesn’t offer it, use one of the next three.

2. Forward port 1455 over SSH

The normal browser login redirects to Codex’s callback server, by default on localhost:1455. Make your laptop’s port 1455 lead to the box, and the normal flow works:

  1. From your laptop, connect with the forward:
ssh -L 1455:localhost:1455 you@your-box
  1. In that SSH session, run codex login.
  2. Open the printed address in the browser on your laptop and sign in. The redirect to localhost:1455 goes through the tunnel to the box.

Two things to watch: nothing else on the laptop may be using port 1455 (a local codex login in progress, say), and the browser has to be on the machine holding the tunnel, so this doesn’t help from a phone.

3. An API key, on standard input

For CI and other programmatic use, the docs suggest an OpenAI API key, piped in so it never lands in your shell history:

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

This signs Codex in with the API key rather than your ChatGPT account. (On a machine where coding agents run, consider keeping the key under a less standard variable name, so other tools don’t pick it up by accident.)

4. Copy auth.json from a machine with a browser

If none of the above fits, sign in where a browser works and copy the result:

  1. On your laptop, run codex login and finish it in the browser.
  2. Check that ~/.codex/auth.json exists. If your system keeps Codex’s credentials in the OS keychain instead, there’s no file to copy and this method doesn’t apply.
  3. Copy it to the box:
ssh you@your-box 'mkdir -p ~/.codex'
scp ~/.codex/auth.json you@your-box:~/.codex/auth.json

Treat that file like a password: it holds access tokens. Where Codex keeps credentials is set by cli_auth_credentials_store in its config (file, keyring, auto or ephemeral).

Which one to use

Device code if you have it; the tunnel if you’re at a laptop anyway; an API key for automation. The auth.json copy works but leaves a long-lived secret on another machine. And all four assume you’re at a terminal when the login starts. When an agent on the box runs into a sign-in while you’re away, the general version of this problem is in OAuth redirect to localhost on a remote server.

The permanent fix

Handback catches the sign-in link codex login opens on the box (through $BROWSER and xdg-open with the free Engine on Linux, or Engine mode in the Handback app when the box is a Mac) and hands it to the iPhone, iPad or Mac in your hand. It sees the localhost:1455 redirect, binds that port on your device and tunnels the callback back to the box, so the plain browser login finishes with no tunnel to set up and no file to copy. That's the flow in the demo on the home page. On an iPhone the sign-in opens in a sheet inside the app, which receives while it's on screen; links that arrive meanwhile wait on the box for 24 hours.

$7.99 / €7.99 · Mac, iPhone & iPad, one purchase

Sources

Every flag above was checked against these on 15 October 2026.