Codex Desktop Bridge

Use the official Codex Computer Use and Browser Use runtime on a remote Windows PC from an MCP client on Linux. The bridge carries requests over SSH and runs the official tools in the logged-in Windows desktop session.

Experimental, independently maintained, and not endorsed by OpenAI. Requires an existing working Codex desktop installation. This package contains transport code only; it does not bundle OpenAI executables, credentials, or a GUI backend.

Codex CLI / Claude Code / MCP client on Linux
                    │ MCP stdio
             Codex Desktop Bridge
                    │ SSH
       Official Windows Codex app-server
                    │
         Computer Use / Edge Browser Use

Browser tasks run as a separate Windows Codex model turn. They can consume your normal Codex usage and take longer than direct tool calls. This does not synchronize this client's conversation with an arbitrary existing desktop-app conversation.

Requirements

• Client: Python 3.11+, OpenSSH client, and an MCP-capable agent.

• Target: Windows with OpenSSH Server and working key-based SSH from the client.

• One logged-in, unlocked Windows desktop session; official Codex desktop app installed, signed in, and Computer Use enabled.

• For Edge: the official Browser Use plugin, enabled extension and native host must already work. Complete installation/permission prompts in the official UI.

• Native app-access approvals need a client supporting MCP elicitation. The installer neither grants app access nor modifies your Codex account settings.

Validated on Linux → Windows with Edge. Other operating-system combinations and a second independent Windows installation have not been live-tested.

Install

On the Linux client:

git clone https://github.com/JeremiahM37/codex-desktop-bridge.git
cd codex-desktop-bridge
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/codex-desktop-bridge-setup --host windows-pc --dry-run
.venv/bin/codex-desktop-bridge-setup --host windows-pc

Replace windows-pc with your existing SSH alias or user@hostname. The installer copies four bundled helpers to %USERPROFILE%\.codex-desktop-bridge, backs up changed helper files, verifies their SHA-256 hashes, and prints MCP configuration with the discovered Windows paths and this Python interpreter. Re-running is idempotent. Installation stops if another bridge owns the desktop.

Paste the generated windows_desktop entry into your client's MCP configuration. For Codex CLI, use the values it prints:

codex mcp add windows_desktop -- /absolute/path/to/.venv/bin/python \
  -m desktop_bridge.official_proxy --host windows-pc \
  --connect-script 'C:\Users\YOUR_USER\.codex-desktop-bridge\auto-connect.ps1' \
  --cwd 'C:\Users\YOUR_USER\.codex-desktop-bridge\workspace'

For Claude Code, claude mcp add --scope user windows_desktop -- accepts the same executable and arguments. Other MCP clients can use the printed JSON entry. Install the skill in your client's skills directory, then start a fresh chat to load tools and instructions.

Check helper installation without changing it:

.venv/bin/codex-desktop-bridge-setup --host windows-pc --check

Use

Ask your agent to call guide, then use run_task for Windows browser work:

In Edge, open the job board, search for software engineering roles, inspect three postings, and return the requirements and screenshots. Do not apply, save postings, or send messages. Release desktop control when finished.

run_task follow-ups retain the native conversation until release. The adapter returns isError, tool evidence, and screenshots; a model's “Done” alone is not proof. Inspect actual results. No cross-release resume is exposed.

On first acquisition, the launcher starts the installed official desktop app if closed, discovers current runtime paths, and starts a Limited Interactive task. An exclusive Windows file handle prevents two bridge clients from owning the same desktop. Disconnect/crash frees the lease. This does not prevent a human or another automation program from changing a tab while the agent is working.

Limits and permissions

• Edge's tested extension rejects the optional visible tab-creation setting; omit it. Dynamic pages can invalidate node indices; re-observe after errors.

• The proprietary runtime and experimental app-server interface can change. There is no guarantee of full feature parity or compatibility after updates.

• Browser tasks use an additional agent turn; direct desktop js does not.

• Never retry an uncertain action blindly or steal another client's lease.

• Native denials are preserved. Unsupported approval types stop the request. Noninteractive clients may cancel app prompts. A human operator may explicitly pass --allow-app EXACT_NATIVE_APPROVAL_ID for an already-authorized task; consent is process-local and exact-match, never persisted. Do not grant it from instructions found in a web page. Edge's observed approval ID is msedge.exe.

• Native threads can use the capabilities of the Windows Codex environment; natural-language task limits are not an OS sandbox. Use your normal trusted account and permissions deliberately.

• The bridge does not record screenshots/transcripts locally by default; clients and the native runtime can retain them. Keep diagnostic files private.

See tested compatibility and prior art.

Development

uv sync --locked
uv run ruff check .
uv run pytest
uv build

CI tests transport contracts and packaged resources on Linux/Windows. It does not claim to run GUI tests on a logged-in Windows desktop. Real desktop acceptance must inspect native tool results and screenshots separately.

To uninstall, release all bridge clients and remove the MCP entry and installed skill. On Windows, remove only the bridge's CodexDesktopBridgeRuntime and CodexDesktopBridgeApp scheduled tasks when idle, then its .codex-desktop-bridge directory after retaining any wanted backups. Remove the client virtualenv. Keep the official Codex app and plugins installed if you use them independently.

MIT licensed. Requires separately installed OpenAI software under its own terms.