ChatGPT Codex Bridge

ChatGPT Codex Bridge is a self-hosted MCP server that lets ChatGPT work with your local codebase through explicit tools. It can read, edit, search, run terminal commands, show change summaries, and optionally delegate larger engineering jobs to the local Codex CLI.

The project is designed for people who want ChatGPT to behave more like a local coding agent while keeping the actual source files, terminal, credentials, and tooling on their own machine.

What It Does

• Exposes selected local folders to ChatGPT through MCP.
• Provides workspace-scoped tools for reading, editing, writing, searching, and inspecting files.
• Runs Bash and Windows PowerShell commands for tests, builds, git, package scripts, and local diagnostics.
• Supports permission modes from read-only to full local development access.
• Adds audit snapshots, change summaries, and session rollback for edits made through the bridge.
• Loads project instructions from AGENTS.md and CLAUDE.md.
• Discovers local skills from bundled and user-configured skill directories.
• Supports ChatGPT Apps-compatible tool cards and workspace UI metadata.
• Can delegate larger tasks to codex exec with configurable model, reasoning, sandbox, speed, plan policy, and goal policy.
• Includes a local settings page for roots, public URL, permission mode, audit, and Codex delegation defaults.

Detailed feature notes are in docs/features.md.

Install

Requirements:

• Node >=20.12 <27; Node 22 LTS is recommended.
• npm.
• Git.
• Bash, such as Git Bash or WSL on Windows.
• A public HTTPS tunnel or reverse proxy when connecting from ChatGPT.
• Optional: OpenAI Codex CLI if you want to use delegate_to_codex.

Install from a local checkout:

npm install --include=dev
npm run build
node dist/cli.js init
node dist/cli.js serve

After publishing to npm, the same app can be installed globally:

npm install -g chatgpt-codex-bridge
codex-bridge init
codex-bridge serve

The legacy devspace command is also kept as a compatibility alias.

Quick Start

1. Start an HTTPS tunnel to the local server port, usually 7676.

   cloudflared tunnel --url http://127.0.0.1:7676
   

2. Initialize the bridge.

   codex-bridge init
   

   During setup, enter:

   • the local folders ChatGPT may open;
   • the local port, usually 7676;
   • the public HTTPS origin, without /mcp.

3. Start the MCP server.

   codex-bridge serve
   

4. Add this MCP endpoint to ChatGPT or another MCP host:

   https://your-tunnel-host.example.com/mcp
   

5. Approve the connection with the Owner password printed by init.

The default local settings page is:

http://127.0.0.1:7676/settings

Full deployment instructions are in docs/deployment.md.

Configuration

The bridge stores local config and auth files under:

~/.devspace/config.json
~/.devspace/auth.json

The ~/.devspace path is intentionally retained for backward compatibility. You can override it with DEVSPACE_CONFIG_DIR.

Common settings:

Setting	Default	Purpose
DEVSPACE_ALLOWED_ROOTS	current directory during setup	Filesystem roots ChatGPT may open.
DEVSPACE_PUBLIC_BASE_URL	required	Public origin, without /mcp.
DEVSPACE_PERMISSION_MODE	safe_shell	Tool permission policy.
DEVSPACE_CODEX_DELEGATION	1	Enables delegate_to_codex.
DEVSPACE_CODEX_DEFAULT_MODEL	gpt-5.5	Default Codex model.
DEVSPACE_CODEX_DEFAULT_REASONING_EFFORT	xhigh	Default reasoning effort.
DEVSPACE_CODEX_DEFAULT_SPEED	normal	Codex service tier, normal or fast.

See docs/configuration.md for the full reference.

Security Model

This bridge gives a remote MCP client access to local development capabilities. Treat it like granting a trusted coding partner access to your machine.

The safety model is based on:

• a narrow filesystem allowlist;
• an Owner password approval flow;
• OAuth-protected MCP sessions;
• Host header validation;
• permission modes for edits, shells, and Codex delegation;
• audit logs and rollback support for bridge-made file edits.

Do not expose it with broad roots like ~, /, or C:\ unless you understand the risk. Keep ~/.devspace/auth.json private.

More details are in docs/security.md.

Package

Create a distributable npm tarball:

npm run build
npm pack

The package includes dist, docs, scripts, and README.md.

Local Development

npm install --include=dev
npm run dev
npm run typecheck
npm test
npm run build
npm run start

License

MIT