Authenticating Codex CLI on a Remote Linux Server from Windows
Fix Codex CLI OAuth login failures on a remote Linux server using SSH port forwarding (ssh -L 1455) to tunnel the localhost:1455 callback back to Windows.
Overview
When using Codex CLI on a remote Linux server accessed from a Windows machine (via SSH), authentication can fail during login. The most common symptom is:
After signing in via the browser, the redirect goes to
http://localhost:1455/auth/callback?...
and authentication never completes.
This article explains why this happens and provides a reliable, production-safe solution using SSH port forwarding.
The Problem Explained
Typical Setup
- Local machine: Windows
- Remote machine: Linux server
- Access method: SSH
- Tool: Codex CLI
- Authentication method: Browser-based OAuth
What Codex CLI Does During Login
- You run:
codex login - Codex CLI starts a temporary local web server on the machine where it runs (the remote Linux server), usually:
http://localhost:1455 - You are asked to open a login URL in your browser.
- After signing in, the browser redirects to:
http://localhost:1455/auth/callback?code=XXXX
Why This Fails on a Remote Server
- The CLI is running on the remote Linux server
- Your browser is running on your Windows machine
localhostin the browser refers to Windows, not the server- Nothing is listening on
localhost:1455on Windows - Result: authentication never completes
This is expected behavior — not a bug.
The Correct Solution: SSH Port Forwarding
What Port Forwarding Does
SSH port forwarding makes your Windows localhost port act as a tunnel to the remote server’s localhost port.
So when your browser hits:
http://localhost:1455
It is silently forwarded to:
remote-server then localhost:1455
Exactly where Codex CLI is listening.
Step-by-Step Solution (Recommended)
Assumptions (Dummy Data)
- Remote server IP:
203.0.113.10 - Remote user:
developer - OAuth callback port:
1455
Step 1: Open SSH with Port Forwarding (from Windows)
In PowerShell / Windows Terminal:
ssh -L 1455:127.0.0.1:1455 [email protected]
Important:
- Do NOT open a second SSH session
- Keep this terminal open until login completes
Step 2: Run Codex Login on the Remote Server
Inside the same SSH session:
codex login
You’ll see a message like:
Please open the following URL in your browser to authenticate:
https://chatgpt.com/auth/...
Step 3: Open the Login URL in Your Windows Browser
- Copy the login URL
- Open it in Chrome / Edge / Firefox
- Sign in normally
After successful login, the browser redirects to:
http://localhost:1455/auth/callback?code=ac_XXXX
This now works because SSH forwards the request to the remote server.
Step 4: Verify Success
Back in your SSH terminal, you should see:
Login successful!
Codex CLI is now authenticated on the remote server.
Common Mistakes (and How to Avoid Them)
Opening the Callback URL Manually
Do not paste the localhost:1455/auth/callback URL yourself.
Let the browser redirect naturally after login.
Running SSH Without Port Forwarding
This will never work:
ssh [email protected]
You must include -L.
Port 1455 Already in Use on Windows
Check:
netstat -ano | findstr :1455
If occupied:
- Stop the conflicting process, or
- Reboot, then retry
Codex usually expects port 1455, so changing it is not always supported.
Optional Alternative: Copy Credentials Manually
If SSH tunneling is blocked by policy:
- Run
codex loginon your local machine - Complete login
- Copy the credentials file:
- Windows:
%USERPROFILE%.codexauth.json
- Windows:
- Transfer it to the server:
scp auth.json [email protected]:~/.codex/auth.json
Use only in trusted environments.
Security Notes
- OAuth tokens are short-lived and scoped
- SSH tunneling encrypts all traffic
- No public ports are exposed
- The callback server is temporary and local-only
This method is safe for enterprise and production use.
Summary
| Issue | Cause | Solution |
|---|---|---|
| OAuth redirect to localhost fails | CLI runs remotely | SSH port forwarding |
| Browser cannot reach callback | Wrong machine | Tunnel localhost:1455 |
| Login hangs forever | No tunnel | Reconnect with -L |
Final Takeaway
This is not a Codex bug.
It’s a standard OAuth + remote CLI scenario.
Once SSH port forwarding is used correctly, Codex authentication works flawlessly on remote Linux servers from Windows.