Codex Gateway

Codex Gateway connects ChatGPT Web to granted local development workspaces through an OpenAI Secure MCP Tunnel. One runtime can expose a permission root such as ~/Documents/Github, select an individual repository per request, and bridge the installed Codex app-server without placing every internal schema in the model's default context.

Connect ChatGPT securely to local Codex tools, project code, task history, and skills.

Why it exists

ChatGPT cannot connect directly to localhost. Codex Gateway solves the local half of that connection while Secure MCP Tunnel provides the private transport:

ChatGPT Web
    │ custom MCP app (called a plugin/connector in some UI versions)
    ▼
OpenAI Secure MCP Tunnel
    │ outbound connection; no public local port
    ▼
Codex Gateway
    ├─ tool_search → discover relevant local capabilities
    ├─ tool_call   → invoke one discovered capability
    ├─ tool_batch  → run independent read-only capabilities concurrently
    ├─ skill_search
    ├─ skill_read
    └─ create_goal / get_goal / update_goal / clear_goal
         ▼
Granted permission root(s)
    ├─ request-scoped repository selection
    ├─ guarded files / commands / patches / images
    └─ installed Codex app-server
         └─ runtime-generated RPC catalog for the installed Codex version

The public MCP surface contains ten stable tools:

• gateway_info

• tool_search

• tool_call

• tool_batch

• skill_search

• skill_read

• create_goal

• get_goal

• update_goal

• clear_goal

Workspace, terminal, patch, image, and Codex schemas are returned only when a relevant search requests them. Codex RPC tools are generated from codex app-server generate-json-schema --experimental for the installed binary, cached by executable fingerprint, and regenerated automatically when that binary changes. Legacy convenience aliases remain available, but new Codex methods do not require a Gateway release. Skill search returns metadata first; instructions and supporting resources are loaded separately. Third-party provider catalogs such as XcodeBuildMCP are intentionally not mirrored.

Apple development is available without mirroring XcodeBuildMCP's full schema catalog. ChatGPT loads the installed xcodebuildmcp-cli skill on demand, discovers the CLI workflow with --help / tools, and runs xcodebuildmcp through the guarded command tool. This includes simulator and physical-device build, test, install, launch, debugging, and UI automation when supported by the installed CLI and host configuration.

When several discovered reads are independent, ChatGPT can send them together through tool_batch; the Gateway runs them concurrently and returns indexed results. Mutations and steps that consume earlier results stay sequential.

The four goal tools belong to ChatGPT Web, not to a Codex task. A goal is stored locally per selected workspace and survives new ChatGPT conversations and tunnel restarts. The goal and skill tools accept the same optional workspace selector used by repository calls, so a broad permission root does not mix project-local state.

Related MCP server: codex-chatgpt-bridge

Requirements

• macOS or Linux

• Bun 1.3 or newer

• git and rg

• OpenAI tunnel-client available on PATH or at ~/.local/bin/tunnel-client

• An OpenAI Secure MCP Tunnel ID and a runtime API key with Tunnels Read + Use

• ChatGPT developer mode for creating a custom MCP app

Full MCP write/modify actions currently depend on ChatGPT plan and workspace policy. See OpenAI's developer mode and MCP apps guide.

Five-minute setup

1. Install the gateway

git clone https://github.com/sleda/codex-gateway.git
cd codex-gateway
bun install

Check the local prerequisites:

bun run src/cli.mjs doctor --strict

2. Create OpenAI tunnel credentials

Create or select a tunnel in:

• OpenAI Tunnels

Create a separate runtime API key in:

• OpenAI project API keys

The long-running Gateway needs a runtime key, not an organization admin key. The runtime principal must be allowed to read and use the selected tunnel. The key authenticates the tunnel runtime; Codex task mutations and ChatGPT model usage remain separate operations.

3. Run the interactive onboarder

bun run onboard

The onboarder asks for:

1. The primary permission root to expose. For a single project, use the repository itself. To work across many sibling repositories, use their common parent such as ~/Documents/Github.

2. The existing tunnel_... ID.

3. A permission mode.

4. The runtime API key if its protected key file does not exist.

Repository selection is request-scoped. A call can target one granted repository while the next call targets another; no global workspace switch is performed.

gateway_info is the fastest routing diagnostic: one call reports the runtime identity, configured grants, and a compact list of discovered repository names/selectors. If ChatGPT has cached an older tool_call(name, arguments) schema that does not expose the newer top-level workspace field, put __gatewayWorkspace inside the tool's arguments; Gateway removes that reserved field before forwarding the request. The discoverable workspace_call / workspace_batch wrappers remain available as an explicit compatibility path.

It stores a newly entered key at ~/.config/openai/codex-gateway-runtime-key with mode 0600, creates a managed tunnel-client runtime, starts it, and verifies its status. The key value is never placed in the generated MCP command.

For unattended setup:

bun run src/cli.mjs onboard \
  --workspace /absolute/path/to/project \
  --tunnel-id tunnel_YOUR_ID \
  --runtime-key-file ~/.config/openai/codex-gateway-runtime-key \
  --mode developer \
  --yes

Use --dry-run to inspect the resolved setup without writing files or starting a runtime.

4. Create the ChatGPT app

Open ChatGPT Apps settings. Depending on the current UI, the same feature may be labeled App, Connector, or Plugin.

1. Enable Developer mode in ChatGPT's advanced Apps settings.

2. Choose Create app / Create custom MCP connector.

3. Name it Codex Gateway.

4. Use this description:

   Connect ChatGPT securely to local Codex tools, project code, task history, and skills.

5. Upload assets/codex-gateway-icon.png. It is a 256×256 PNG under 10 KB.

6. Select Tunnel as the connection type and choose the tunnel used during onboarding.

7. Select None for authentication. The Secure MCP Tunnel already authenticates the runtime.

8. Scan/refresh actions and finish creating the app.

9. For a trusted personal development workspace, allow all ten Gateway actions. Local Gateway policy still guards writes, commands, sensitive files, external paths, and Codex mutations independently.

Open a new ChatGPT conversation, select Codex Gateway from the tools menu, and try:

Use Codex Gateway to inspect the connected workspace. Search for only the tools you need and summarize the repository before making changes.

For persistent Web work, try:

Use Codex Gateway to create a goal for reviewing this repository. Work through the goal with the Web model, save checkpoints as you progress, and mark it complete only when verified.

The app scan should show exactly eleven public actions. If it shows an older catalog, refresh the app actions or recreate the draft app while the tunnel runtime is running. An older five-action app can still discover and invoke the goal and batch tools through tool_search and tool_call, but refreshing provides the intended direct experience.

If ChatGPT reports Session terminated, restart the workspace runtime and wait for readiness with one command:

codex-gateway restart

The CLI selects codex-gateway-<workspace-name> from the current directory, restarts its tunnel session, and exits only after /readyz reports ready. Use --profile <name> when the profile has a custom name.

Permission modes

The onboarder applies one of three local policies:

Even in full mode:

• paths remain confined to the selected workspace inside the configured permission grants;

• sensitive files such as .env remain blocked unless separately enabled;

• commands are executed without an arbitrary shell and must be allowlisted;

• workspace and Codex mutation tools require confirmation: true; goal checkpoints do not modify the repository;

• the outer ChatGPT workspace can apply additional action controls and confirmations.

The default command allowlist includes xcodebuildmcp but not raw xcodebuild, xcrun, or simctl. This keeps Apple workflows on the structured, help-discoverable CLI surface. Override the complete allowlist with CODEX_GATEWAY_COMMAND_ALLOWLIST only when a workspace requires a different policy.

For xcodebuildmcp, Gateway resolves a full Xcode developer directory without changing the machine-wide xcode-select setting. It first honors CODEX_GATEWAY_XCODE_DEVELOPER_DIR or a valid DEVELOPER_DIR, then scans /Applications, ~/Applications, and ~/Downloads, preferring a valid Xcode Beta bundle when present. Apple system tool directories are placed ahead of user-local shims for that child process, preventing stale xcrun wrappers from reintroducing an old DEVELOPER_DIR. gateway_info runs a real xcodebuildmcp simulator list readiness probe rather than reporting configuration-only readiness.

Work across repositories

Prefer one runtime per permission boundary, not one runtime per repository. For a personal development folder containing sibling Git repositories, onboard the common parent once:

bun run src/cli.mjs onboard \
  --workspace ~/Documents/Github \
  --tunnel-id tunnel_YOUR_ID \
  --runtime-key-file ~/.config/openai/codex-gateway-runtime-key \
  --alias codex-gateway-self \
  --profile codex-gateway-self \
  --mode full \
  --yes

workspace_list discovers Git repositories under the grant. tool_call, tool_batch, goal tools, and skill tools can then select one with workspace: "repo-name" or a canonical path inside an explicit grant. Selection uses real paths and AsyncLocalStorage, so concurrent calls do not race by mutating global process state.

CODEX_GATEWAY_ROOT is the primary grant. CODEX_GATEWAY_WORKSPACE_ROOTS can add colon-separated permission roots when projects do not share one parent. Paths, symlinks, dynamic Codex filesystem RPCs, and command working directories remain confined to the selected grant.

Do not run several local runtimes against the same tunnel. The onboarder detects that ambiguity and refuses it unless --replace-tunnel-runtime is explicit. codex-gateway handover exists for a live self-upgrade: it returns control first, then a detached worker replaces the current runtime after a short delay.

Runtime operations

The onboarder uses tunnel-client runtimes connect, which provides managed local supervision. No nohup, background shell, or permanent terminal window is required.

# List runtimes
tunnel-client runtimes list

# Inspect health and readiness
tunnel-client runtimes status codex-gateway-my-project

# Stop without deleting the remote tunnel
tunnel-client runtimes stop codex-gateway-my-project

# Disconnect the managed runtime
tunnel-client runtimes disconnect codex-gateway-my-project

Run onboarding again with the same alias and tunnel to reconnect or update its workspace command.

Manual tunnel setup

The CLI is recommended, but the underlying setup is intentionally transparent. A tunnel profile starts Gateway over stdio with an explicit workspace:

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile codex-gateway-my-project \
  --tunnel-id tunnel_YOUR_ID \
  --control-plane-api-key-ref file:/absolute/path/to/runtime-key \
  --health-listen-addr 127.0.0.1:0 \
  --mcp-command "/usr/bin/env CODEX_GATEWAY_ROOT=/absolute/path/to/project CODEX_GATEWAY_ENABLE_CODEX=1 CODEX_GATEWAY_ALLOW_WRITES=1 CODEX_GATEWAY_ALLOW_COMMANDS=1 bun run /absolute/path/to/codex-gateway/src/server.mjs --transport stdio"

tunnel-client doctor --profile codex-gateway-my-project --explain
tunnel-client run --profile codex-gateway-my-project

Keep the foreground run process open when using the manual path. For long-lived use, prefer the managed runtime created by codex-gateway onboard.

Direct local development

Start stdio MCP without a tunnel:

CODEX_GATEWAY_ROOT=/absolute/path/to/project \
CODEX_GATEWAY_ENABLE_CODEX=1 \
bun run src/server.mjs --transport stdio

Or start authenticated loopback HTTP:

CODEX_GATEWAY_ROOT=/absolute/path/to/project \
CODEX_GATEWAY_TOKEN="$(openssl rand -hex 32)" \
bun run src/server.mjs --transport http --host 127.0.0.1 --port 8787

HTTP binds to loopback by default. Secure MCP Tunnel normally owns the stdio child process, so a second HTTP server is unnecessary for ChatGPT.

Skills

skill_search discovers metadata from these roots by default:

• <workspace>/.agents/skills

• ~/.agents/skills

• $CODEX_HOME/skills or ~/.codex/skills

• installed Codex plugin cache

skill_read first loads the selected SKILL.md; supporting files are requested separately. Reads are size-bounded and confined to the discovered skill directory. Logical duplicates are collapsed by source precedence unless includeAlternatives: true is requested. The catalog is cached in memory and on disk with stale-while-refresh behavior, avoiding repeated plugin-tree scans; refresh: true forces a synchronous refresh. Set CODEX_GATEWAY_SKILL_ROOTS to a colon-separated list only when you want to replace the defaults explicitly.

Troubleshooting

ChatGPT cannot find the app

• Confirm the runtime is running with tunnel-client runtimes status <alias>.

• Confirm ChatGPT developer mode is enabled for your account/workspace.

• Create or scan the app only while the tunnel runtime is online.

• Start a new chat and select the app for the message that needs local access.

The app shows old tools

Gateway exposes eleven public actions. Refresh actions in the ChatGPT app's management screen. If the draft still caches the older five-action schema, recreate it against the running tunnel. Until refreshed, ask ChatGPT to find create_goal or tool_batch through tool_search and invoke it through tool_call.

Session terminated or disconnected streams

Check the managed runtime first:

tunnel-client runtimes status <alias> --json

Then run local diagnostics:

CODEX_GATEWAY_ROOT=/absolute/path/to/project bun run doctor --strict

Do not add a public reverse proxy as a workaround; the supported local/private path is Secure MCP Tunnel.

ChatGPT can read but cannot edit

First call gateway_info and inspect connectorCompatibility.publicActionContract. Gateway advertises eleven public actions: six read-only actions and four write-capable actions. If ChatGPT exposes only the six read-only actions, the host is filtering write-capable MCP actions rather than the Gateway losing tool_call.

Check all three layers before changing the server: the ChatGPT plan/workspace must support full MCP write actions, the app's action controls must enable the write-capable actions, and the local runtime must allow the requested mutation (developer or full mode as appropriate). Current ChatGPT product availability is plan-dependent, so confirm it in the latest OpenAI developer-mode documentation. Do not mark tool_call read-only merely to make it appear: it routes guarded file writes, commands, and Codex mutations and must remain write-capable. Sensitive-file and external-path access stay disabled unless explicitly configured.

Preview release status

Version 0.4.1 is a pre-release. See the release notes for verified capabilities, the remaining downstream accessibility case, and trusted-host execution boundaries.

Development and verification

bun test runs the portable suite. The eight installed Codex/Xcode integration checks require an explicitly configured Mac and are enabled with bun run test:live. After bun run build, run bun run smoke:binary to verify the standalone executable outside the source checkout.

bun run typecheck
bun test
bun run doctor --strict
bun run smoke:live -- /absolute/path/to/workspace
bun run eval:github
CODEX_GATEWAY_EVAL_NATIVE=1 bun run scripts/eval-live.ts ~/Documents/Github
bun run build

The compiled binary is written to dist/codex-gateway. The repository also contains a Codex-local plugin manifest for users who want Gateway inside Codex itself; that plugin is optional and is not the ChatGPT custom app described above.

See docs/architecture.md, SECURITY.md, and CHANGELOG.md for implementation and release details.

License

MIT