Codex Windows Remote Connect

A documented Windows-to-Windows Codex SSH transport experiment.

Warning

This repository preserves an unsupported, version-specific prototype built from Codex Store version 26.721.11231.0. It is reference material, not a current turnkey installer. Do not apply its exact-string patch to another Codex version without re-porting and testing it.

What this project demonstrates

The historical Codex desktop SSH transport assumed every remote machine had a Unix login shell. A native Windows OpenSSH target failed when Codex sent commands such as sh -c, command -v, mkdir, and pkill.

This experiment patched a separate, user-owned copy of the controller app so it could:

• detect a Windows SSH target;
• wrap remote commands in non-interactive, encoded PowerShell;
• discover codex.cmd on the target;
• start codex.cmd app-server --listen unix://;
• bridge codex.cmd app-server proxy over SSH standard streams;
• retain the original POSIX path for Linux and macOS targets.

The protected Microsoft Store installation was not edited in place, and the target machine's Codex application code was not patched.

Architecture

Windows controller                              Windows target
------------------                              --------------
Patched Codex desktop UI
        |
        | SSH + encoded PowerShell
        +--------------------------------------> codex.cmd
                                                  |-- app-server --listen unix://
                                                  `-- app-server proxy
        <-------------------------------------- SSH stdin/stdout

The visible Codex interface remains on the controller. Commands, files, tools, and the app server run on the target.

Repository contents

Path	Contents
docs/Codex-Windows-to-Windows-SSH-patch-guide.md	Full forensic guide, architecture, reproduction method, and maintenance notes.
docs/Codex-Windows-to-Windows-SSH-patch-guide.docx	Shareable Word version of the guide.
reference/26.721.11231.0	Original patch, build, launcher, inspection, verification, and cleanup scripts recovered from the controller.
reference/26.721.11231.0/CHECKSUMS.sha256	SHA-256 inventory of the preserved reference scripts.

The repository intentionally excludes:

• Microsoft Store application binaries;
• extracted or repacked app.asar archives;
• portable Codex application directories;
• user profiles, tokens, auth.json, SSH private keys, logs, and runtime sockets.

Historical build flow

1. Establish key-only SSH from the controller to the Windows target.
2. Confirm a non-interactive target session can resolve codex.cmd.
3. Extract the exact installed Codex version's app.asar into a user-owned directory.
4. Port the Windows target detection and PowerShell bootstrap into that version's Electron main bundle.
5. Validate JavaScript syntax and repack app.asar into a separate portable app copy.
6. Test with an isolated user profile.
7. Verify the app-server socket, proxy lifetime, cleanup, and reconnect behavior.
8. Only then create a launcher and shortcut for the patched copy.

The recovered scripts contain machine-specific paths and minified source markers. Read the complete guide before using them.

Current forensic status

At the August 2, 2026 review:

• the original patched source version was 26.721.11231.0;
• both normal Store installations reported 26.727.6591.0;
• target-side SSH and codex.cmd 0.144.1 still worked;
• most junctions from the old portable build into the Store package no longer resolved after the update;
• the historical SSH proxy path had been verified successfully on July 30.

The durable lesson is to make a self-contained user-owned build and re-port the patch for every Codex release. Junctions into a versioned WindowsApps package are not update-safe.

Security boundaries

• Never commit or distribute private SSH keys, Codex tokens, user profiles, or packaged application binaries.
• Use a unique SSH private key for each controller.
• Verify target host-key fingerprints before enabling non-interactive access.
• Follow the ACL requirements for Windows OpenSSH's administrators_authorized_keys.
• Treat encoded PowerShell over SSH as privileged remote execution.
• Do not run the normal and patched apps concurrently against the same user-data directory.

Why the original scripts are preserved unchanged

The files under reference/26.721.11231.0 are forensic evidence of the working experiment. Their hard-coded paths and exact replacement strings make the original behavior auditable, but also make them unsuitable for blind reuse. Future work should implement a version-aware patcher with explicit bundle discovery, backups, isolated profiles, and automated protocol tests.

License

The original scripts and repository documentation are available under the MIT License. Microsoft Store/OpenAI application binaries are not included and remain subject to their own terms.