Bridge (Windows-hosted ChatGPT session → Linux clients)

July 2, 2026 · View on GitHub

Oracle’s bridge workflow lets you keep an authenticated ChatGPT session on a Windows machine while running Oracle (CLI + oracle-mcp) from Linux boxes (often over SSH), without exporting browser cookies off Windows.

Concepts

  • Host (Windows): runs oracle bridge host and holds the signed-in ChatGPT session.
  • Client (Linux): stores the host connection once and routes browser runs (and MCP browser runs) through the host.

Generated artifact transfer

Bridge runs now keep the Windows browser host and Linux client separated while still returning ChatGPT-generated files, such as ZIP, CSV, PDF, wheels, and source distributions, to a cloud-readable path. The host advertises artifact-transfer support from the token-protected GET /health response. The Linux client uses that capability signal in oracle bridge client --test and oracle bridge doctor; older hosts remain usable for text responses, but generated files require manual copy from the Windows browser until both sides are upgraded.

The transfer protocol is pull-based and keeps secrets local to the host:

  1. The browser host saves the ChatGPT file to its local session artifacts directory as before.
  2. The host emits only a redacted artifact descriptor over the existing NDJSON run stream: artifact id, safe filename, MIME type, byte size, SHA-256, validation status, and coarse source kind. It does not expose cookies, bearer tokens, signed ChatGPT download URLs, or Windows filesystem paths.
  3. The Linux client fetches GET /runs/<runId>/artifacts/<artifactId> with the same bridge bearer token, writes to ~/.oracle/sessions/<sessionId>/artifacts/, verifies size and SHA-256, validates ZIP structure when applicable, and only then publishes the final path in session metadata.
  4. If transfer fails, Oracle keeps the text response and records a warning with manual fallback instructions. Open the ChatGPT browser on the Windows host, use the visible download button/link in the current assistant response, and copy the file to a cloud-readable path yourself.

Operational notes:

  • Run the same patched Oracle version on both Windows host and Linux client before relying on automatic file transfer. Mixed versions remain backward compatible for text-only runs.
  • oracle bridge doctor reports Artifact transfer: bridge v1 when the host supports the protocol, including the advertised maximum artifact size.
  • The default bridge transfer size limit is 512 MiB. Larger files stay on the browser host and require manual copy.
  • Session inspection prints artifact path, size, SHA-256 prefix, validation status, and transfer status so agents can verify whether the returned path is local to the Linux client.

Run this on the Windows machine that’s signed into ChatGPT:

oracle bridge host --token auto --ssh user@your-linux-host

What it does:

  • Starts a local oracle serve instance bound to 127.0.0.1:9473 by default.
  • Generates an access token (stored to disk; not printed unless you ask).
  • Starts an SSH reverse tunnel so the Linux host can reach the Windows service at 127.0.0.1:9473.
  • Writes a connection artifact to ~/.oracle/bridge-connection.json (contains host + token).

Useful flags:

  • Bind a different local port: --bind 127.0.0.1:9474
  • Use a specific token: --token <value>
  • Print the connection string (includes token): --print
  • Print only the token: --print-token
  • SSH port/custom args: --ssh-extra-args "-p 2222"
  • Background mode (writes pid/log files under ~/.oracle): --background

2) Linux: configure the client once

Copy the connection artifact from Windows to Linux (example from Windows → Linux):

scp "$env:USERPROFILE\.oracle\bridge-connection.json" user@your-linux-host:~/bridge-connection.json

Then on the Linux host:

oracle bridge client --connect ~/bridge-connection.json --write-config --test

This writes:

  • ~/.oracle/config.json → browser.remoteHost and browser.remoteToken

Now browser runs automatically route through the host:

oracle --engine browser -p "hello" --file README.md

2b) Linux desktop: local manual-login (no bridge)

If you’re physically on a Linux desktop and just want Oracle to reuse a local signed-in Chrome profile (no Windows bridge):

  1. Run a browser session once and sign in when Chrome opens:
ORACLE_HOME_DIR=~/.oracle-local \
ORACLE_BROWSER_PROFILE_DIR=~/.oracle-local/browser-profile \
oracle --engine browser --browser-manual-login --browser-keep-browser -p "hello"
  1. After you’re signed in, reuse the same env vars for future runs (no more login prompts).

Optional: use the helper wrapper scripts/oracle-local-browser.sh to avoid repeating flags/env vars:

chmod +x ./scripts/oracle-local-browser.sh
./scripts/oracle-local-browser.sh -p "hello" --file README.md

3) Codex CLI (MCP) integration

On the Linux machine where Codex runs:

oracle bridge codex-config

Paste the printed snippet into ~/.codex/config.toml.

3b) Claude Code (MCP) integration

On the Linux machine where Claude Code runs:

oracle bridge claude-config > .mcp.json

Then start Claude Code with that config (or register it via claude mcp add depending on your setup).

Notes:

  • The snippet includes ORACLE_ENGINE="browser" so MCP consult calls use browser mode even if OPENAI_API_KEY is set.
  • By default the snippets leave ORACLE_REMOTE_TOKEN as <YOUR_TOKEN> to avoid printing secrets; rerun with --print-token if you explicitly want it included.

macOS local browser: Let Them Fight

If Claude Code and the signed-in Chrome profile are on the same Mac, skip the remote bridge and generate a local config:

oracle bridge claude-config --local-browser > .mcp.json

This points Claude Code at oracle-mcp, sets ORACLE_ENGINE="browser", and reuses the shared manual-login profile at ~/.oracle/browser-profile. From Claude Code, call consult with preset:"chatgpt-pro-heavy" for the “Let Them Fight” workflow: Claude asks Oracle, Oracle asks ChatGPT Pro Extended in browser mode, and the answer comes back through MCP. Use dryRun:true first when you only want to validate the resolved request.

For long Pro runs, keep the Oracle session id visible in the agent transcript and inspect oracle status / oracle session <id> before retrying. Browser consults may wait on ChatGPT for several minutes; the dry-run/browser control plan is the operator-facing signal for whether Oracle will attach to an existing browser, use remote Chrome, or launch a visible window.

Override local paths when needed:

oracle bridge claude-config \
  --local-browser \
  --oracle-home-dir ~/.oracle \
  --browser-profile-dir ~/.oracle/browser-profile > .mcp.json

4) Troubleshooting

Run:

oracle bridge doctor

It checks:

  • Whether a remote host/token is configured
  • TCP reachability to the remote host
  • Remote auth via GET /health (token-protected)
  • If no remote is configured, it probes local Chrome + cookie DB detection and suggests --browser-chrome-path / --browser-cookie-path

Security notes

  • Tokens are not printed by default.
  • The connection artifact and config file contain secrets; keep them private (Oracle writes them with restrictive permissions on Unix).
  • Bridge does not extract/decrypt cookies from arbitrary profiles; the Windows machine keeps the authenticated session locally.