Codex CLI Remote Login Automator

English | 简体中文

An elegant, zero-dependency bash script to seamlessly authenticate the Codex CLI on remote or headless servers using an ephemeral SSH tunnel.

The Problem

When using Codex CLI on a remote virtual machine or VPS, running codex login requires a local browser to complete the OAuth flow. The authentication callback is sent to http://localhost:1455 on the remote machine. Because your browser is on your local machine, the callback fails, leading to state mismatch errors or "Bad Request" screens.

While there are alternative methods (like exporting your local configuration files into a .tar.gz and SCPing them to the remote server), these methods are cumbersome, manual, and insecure if the tarball is mishandled.

The Elegant Solution

This script automates the native network tunneling approach. It runs entirely on your local machine and does the following in one step:

1. Connects to your remote server and cleans up any stalled codex processes.
2. Silently establishes a background SSH tunnel mapping your local 1455 port to the remote 1455 port.
3. Automatically triggers codex login on the remote server and displays the Authorization URL in your local terminal.
4. Magic: When you click the URL and authenticate in your browser, the traffic flows securely through the tunnel to the remote server, completing the login.
5. Gracefully tears down the SSH tunnel the moment you are done. No lingering background processes, no manual port forwarding commands!

Prerequisites

• SSH access to your target remote server.
• The codex CLI tool installed on the remote server.

Installation

Simply download the script to your local machine and make it executable:

git clone https://github.com/codertesla/codex-remote-login.git
cd codex-remote-login
chmod +x codex-remote-login.sh

Usage

Run the script on your local machine, passing the SSH connection details for your remote server:

./codex-remote-login.sh <ssh_target>

Examples

Using a standard SSH user and IP:

./codex-remote-login.sh ubuntu@192.168.1.100

Using an SSH alias defined in your ~/.ssh/config:

./codex-remote-login.sh my-dev-server

Passing an explicit SSH key:

./codex-remote-login.sh -i ~/.ssh/my_private_key root@example.com

How it works behind the scenes

1. ssh <target> "pkill -f codex": Prevents state mismatch errors caused by previous failed login attempts.
2. ssh -M -S <socket> -fnNT -L 1455:127.0.0.1:1455 <target>: Creates an active background SSH tunnel bound to a UNIX control socket.
3. ssh -t <target> "codex login": Starts the interactive login prompt.
4. trap cleanup EXIT: Catches script termination (successful login or Ctrl+C) and commands the SSH control socket to terminate the tunnel.