Authenticating Codex CLI on a Remote Linux Server from 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

1. You run:codex login
2. Codex CLI starts a temporary local web server on the machine where it runs (the remote Linux server), usually:http://localhost:1455
3. You are asked to open a login URL in your browser.
4. 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
• localhost in the browser refers to Windows, not the server
• Nothing is listening on localhost:1455 on 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 → 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:

1. Run codex login on your local machine
2. Complete login
3. Copy the credentials file:
   • Windows: %USERPROFILE%\.codex\auth.json
4. 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.