Codex Web Bridge

Use ChatGPT Web as the planning UI while this local MCP bridge provides tools for files, code search, shell commands, tests, Git consistency checks, guarded writes, safe base-branch synchronization, and lightweight task/process state.

The recommended public setup is:

ChatGPT Web
  -> your HTTPS domain
  -> server reverse proxy
  -> SSH reverse tunnel
  -> local bridge on 127.0.0.1:3838
  -> local projects

This avoids ngrok and does not require exposing your Mac directly to the internet.

What It Provides

• MCP over stdio for local MCP clients.

• MCP over Streamable HTTP for ChatGPT Apps / Connectors.

• Local project tools: read, search, list, write, patch, move, delete.

• Shell/test/git tools with policy checks.

• Multi-project workspace Git settings without repository-specific defaults.

• Read-only Git preflight across local refs, live remotes, and worktrees.

• Optional single-writer task locks that cover every project write entry point.

• Fast-forward-only integration-branch synchronization with explicit confirmation.

• Workspace/task/process helpers for longer work.

• Optional HTTP token auth for /mcp.

• Audit logs for write/destructive operations.

Related MCP server: opencode-chatgpt-bridge

Quick Start

npm install
npm run build
bash scripts/test-mcp.sh

Run locally:

CODEX_WEB_AUTH_TOKEN="$(openssl rand -hex 32)" node dist/index.js --http 3838
curl -sS http://127.0.0.1:3838/health

Local macOS Service

Generate local-only config files:

bash scripts/configure-local.sh bridge

Install the bridge as a user LaunchAgent:

bash scripts/install-launchd.sh

Stop it:

bash scripts/stop-launchd.sh

Generated files such as launchd/com.codexweb.bridge.plist, launchd/com.codexweb.tunnel.plist, and bridge.policy.json are intentionally ignored by git. Do not commit them; they contain local paths and, usually, a token.

Server Setup Without ngrok

You need:

• A Linux server reachable over SSH.

• A domain with HTTPS terminating on that server.

• A reverse proxy such as nginx.

• SSH key access from your Mac to the server.

1. Start The Local Bridge

bash scripts/install-launchd.sh
curl -sS http://127.0.0.1:3838/health

2. Create An SSH Reverse Tunnel

For an interactive test:

SSH_TARGET="ubuntu@example.com" \
REMOTE_PORT=3839 \
LOCAL_PORT=3838 \
bash scripts/start-ssh-tunnel.sh

With a key:

SSH_TARGET="ubuntu@example.com" \
SSH_KEY="$HOME/.ssh/id_ed25519" \
REMOTE_PORT=3839 \
LOCAL_PORT=3838 \
bash scripts/start-ssh-tunnel.sh

For a macOS LaunchAgent:

SSH_TARGET="ubuntu@example.com" \
SSH_KEY="$HOME/.ssh/id_ed25519" \
REMOTE_PORT=3839 \
LOCAL_PORT=3838 \
bash scripts/configure-local.sh tunnel

bash scripts/install-launchd.sh

On the server, this should respond:

curl -sS http://127.0.0.1:3839/health

3. Reverse Proxy With A Secret Path

ChatGPT's app setup may not give you a place to add a custom bearer header. A practical pattern is:

• Keep CODEX_WEB_AUTH_TOKEN enabled on the local bridge.

• Use a long random path on your HTTPS domain.

• Have nginx inject the bearer token when proxying to the tunnel.

Example nginx location:

location /codex-mcp/<long-random-secret>/ {
    proxy_pass http://127.0.0.1:3839/;
    proxy_http_version 1.1;
    proxy_set_header Authorization "Bearer <your-local-bridge-token>";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
}

Then test:

curl -sS https://your-domain.example/codex-mcp/<long-random-secret>/health

The MCP URL for ChatGPT is:

https://your-domain.example/codex-mcp/<long-random-secret>/mcp

In ChatGPT, choose No Auth for the app authentication if nginx is injecting the bearer token.

ChatGPT App Setup

1. Open ChatGPT Web.

2. Go to Apps -> Manage -> Create app.

3. Use Server URL.

4. MCP Server URL:

https://your-domain.example/codex-mcp/<long-random-secret>/mcp

5. Authentication: No Auth if your reverse proxy injects the bearer token.

6. Accept the custom MCP server risk notice.

7. Create and connect the app.

Try a read-only prompt first:

Use Local Codex Bridge. Run project.snapshot for /absolute/path/to/my/project and summarize the project type, git status, and scripts.

Stdio Config

For local MCP clients that support stdio:

{
  "mcpServers": {
    "codex-web-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/codex-web/dist/index.js"],
      "env": {
        "CODEX_WEB_DATA_DIR": "~/.codex-web",
        "CODEX_WEB_POLICY_PATH": "/absolute/path/to/codex-web/bridge.policy.json"
      }
    }
  }
}

Policy

bridge.policy.json controls what local paths and shell commands are allowed.

Default template:

{
  "allowedProjectRoots": ["/Users/example/Projects"],
  "denyGlobs": [
    "**/.env",
    "**/.env.*",
    "**/*.pem",
    "**/*.key",
    "**/*.p12",
    "**/*.pfx",
    "**/.npmrc",
    "**/.netrc",
    "**/.ssh/**",
    "**/id_rsa",
    "**/id_ed25519"
  ],
  "shell": {
    "enabled": true,
    "denyPatterns": [
      "sudo",
      "rm\\s+-rf\\s+/",
      "chmod\\s+-R",
      "chown\\s+-R",
      "security\\s+find-",
      "launchctl\\s+bootout\\s+system",
      "\\bgit\\s+pull\\b",
      "\\bgit\\s+merge\\b",
      "\\bgit\\s+rebase\\b",
      "\\bgit\\s+reset\\b",
      "\\bgit\\s+clean\\b.*(?:^|\\s)-[^\\s]*f",
      "\\bgit\\s+push\\b.*(?:--force(?:-with-lease)?|(?:^|\\s)-f(?:\\s|$))"
    ]
  }
}

The built-in default is fail-closed: if no allowedProjectRoots are configured, project tools are denied. Replace the neutral example path with the smallest local root or exact project directories you intend to expose. Existing local bridge.policy.json files are not rewritten.

Shell denyPatterns, including the built-in Git patterns, are best-effort guardrails against accidental direct commands. They are not a security boundary or a complete shell parser. Scripts, variables, aliases, command construction, and forms such as git -C <path> ... can bypass simple regular expressions. Keep allowed roots narrow, use guarded write tasks, and prefer the dedicated Git tools instead of relying on shell regexes for adversarial isolation.

Tools

The server exposes these MCP tools:

Multi-project Git Safety

Workspace Git settings are stored only in the local runtime data directory (workspaces.json). They are not source-controlled.

Register each project with its own verified integration branch:

{"name":"project-a","projectPath":"/Users/example/Projects/project-a","remote":"origin","integrationBranch":"main","writeMode":"guarded"}
{"name":"project-b","projectPath":"/Users/example/Projects/project-b","remote":"origin","integrationBranch":"develop","writeMode":"guarded"}
{"name":"project-c","projectPath":"/Users/example/Projects/project-c","remote":"upstream","integrationBranch":"release/current","writeMode":"guarded"}

workspace.add is an upsert. Older workspaces.json records containing only name, path, timestamps, and default state remain readable. Missing Git fields behave as:

• remote: origin;

• integration branch: unresolved until supplied by the call, workspace configuration, or the remote HEAD symref;

• write mode: legacy, preserving existing unguarded behavior.

Creating a workspace and upgrading legacy to guarded remain simple operations. Changing an existing guarded workspace's writeMode requires its active write taskId. A guarded workspace cannot change projectPath; register a new workspace name instead. Adding a workspace alias for a target that is already guarded or has an active write lock also requires that target's active write taskId.

For guarded operation, start one write task and pass its taskId to every project-writing call:

{"title":"Implement feature","workspace":"project-a","mode":"write","leaseMinutes":120}
{"projectPath":"/Users/example/Projects/project-a","file":"src/example.ts","content":"export {};\n","taskId":"task_..."}
{"taskId":"task_...","status":"done","note":"Validated and complete"}

The atomic lock is keyed by the canonical Git repository plus canonical worktree. It applies even if another caller uses the physical path instead of the workspace name. It covers file creation/modification/deletion, shell commands, test runs, Git revert/sync, managed process start/stop, and guarded workspace setting changes. Durable in-flight markers include the bridge PID and, for shell/test calls, the spawned shell PID and process group. Recovery stays fail-closed while any of them may still be alive. A task also cannot finish while one of its managed processes is still active.

workspaces.json, tasks.json, and processes.json use small cross-process file locks around each complete read-modify-write transaction, while final writes still use a temporary file plus atomic rename. A lock is reclaimed automatically only when its metadata is readable, its owner PID is proven stopped, and it is older than the conservative stale threshold. Unreadable or ambiguous locks fail closed instead of being overwritten.

Read-only tasks do not acquire a lock. Expired locks remain blocking until explicitly recovered:

{"taskId":"task_...","reason":"The previous client crashed and the lease expired","confirm":true}

Use task.recover_lock only for an orphaned lock whose task record is no longer active or readable. Both recovery paths append an audit event.

Git preflight

Run preflight before editing or synchronizing:

{"workspace":"project-a"}

Integration branch resolution is fail-closed and uses this priority:

1. explicit integrationBranch call argument;

2. workspace integrationBranch;

3. the selected remote's advertised HEAD symref.

It never guesses main or master. Remote selection uses the explicit call argument, then workspace configuration, then the neutral origin default.

git.preflight does not fetch or change refs. It reports full SHAs, dirty/staged/untracked/conflict state, upstream, local and remote-tracking refs, live remote SHA, ahead/behind when locally verifiable, every worktree, duplicate branch checkouts, active write tasks, and a machine-readable verdict. If the remote cannot be reached or its live commit is not locally verifiable, the result is unknown/unverified, never “clean by assumption.”

Fast-forward-only base sync

{"workspace":"project-a","taskId":"task_...","confirm":true}

git.sync_base may fetch only the selected remote and may update only the currently checked-out integration branch via --ff-only. It refuses dirty worktrees, detached HEAD, a different checked-out branch, local-only commits, divergence, stale/unverified remote state, another worktree checking out the integration branch, or write-lock conflicts. It never falls back to force, reset, merge commits, rebase, or history rewriting.

ChatGPT Web and Codex App together

Treat a physical worktree as single-writer:

• use guarded mode whenever both clients can reach the same project;

• let only the active write task mutate that worktree;

• use separate Git worktrees for genuinely parallel implementation;

• run git.preflight before handing writing control from one client to the other;

• finish or explicitly recover the old write task before starting the next writer.

Separate worktrees can have separate write locks, but Git still prevents the same branch from being checked out normally in two worktrees. Preflight reports any conflicting branch checkout instead of trying to repair it.

Security Notes

• Do not expose /mcp publicly without auth or a protected reverse proxy path.

• Do not commit generated plist files, tokens, SSH key paths, logs, or real domains if they are private.

• Prefer a long random URL segment even when token injection is enabled.

• Keep CODEX_WEB_AUTH_TOKEN enabled for public HTTP use.

• Keep .env, .ssh, key files, .npmrc, and .netrc denied.

• Keep allowedProjectRoots narrow; the default with no configured roots denies project access.

• Use read-only tools first before write/shell tools.

• Prefer git.sync_base over shell-driven pull/merge/rebase. Built-in shell patterns catch common direct spellings of destructive or history-rewriting Git commands, but remain best-effort and bypassable rather than a security boundary.

• Treat shell output and logs as potentially sensitive.

• For long-term use, rotate the secret path and token if they are ever pasted into a public place.

• If your Mac is asleep/offline, ChatGPT cannot reach the local bridge through the tunnel.

• macOS LaunchAgents start after user login, not before login.

Restart Behavior

Server reboot:

• nginx/systemd usually comes back automatically.

• The Mac-side SSH LaunchAgent reconnects when the server is reachable.

• No ChatGPT app reconfiguration is needed if the domain and secret path stay the same.

Mac reboot:

• The LaunchAgents start after you log in.

• The tunnel reconnects if SSH credentials still work.

You need to reconfigure only if the domain, secret path, bridge token, SSH target, SSH key, or ChatGPT app is changed or deleted.

Validation

Local:

curl -sS http://127.0.0.1:3838/health

Server:

curl -sS http://127.0.0.1:<remote-port>/health

Public:

curl -sS https://your-domain.example/codex-mcp/<long-random-secret>/health

MCP initialize:

curl -sS https://your-domain.example/codex-mcp/<long-random-secret>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"verify","version":"1.0"}}}'

Development

npm run typecheck
npm run build
bash scripts/test-mcp.sh