codex-from-chatgpt

Use your local Codex from ChatGPT. This project is a personal, single-user MCP bridge: ChatGPT sends an instruction, the local service translates it into a codex app-server --stdio thread, and returns a compact summary of what Codex did.

Community project, not official: this is not an official OpenAI or ChatGPT integration.

The product boundary is deliberately small:

ChatGPT (through a Secure MCP Tunnel)
  -> MCP Streamable HTTP (/mcp)
  -> compact job API
  -> codex app-server --stdio (JSONL)
  -> local Codex

It does not use codex mcp-server, does not expose shell or filesystem as MCP tools, and implements no broker, worker farm, multi-agent orchestration, or external storage.

Requirements

• Node.js 20 or later.

• codex-cli 0.147.0 on your PATH, installed and authenticated locally.

• A workspace directory under the allowed administrative root. That root defaults to ~/workspace and must exist:

  mkdir -p ~/workspace

• An OpenAI Platform account that can create tunnels, and a ChatGPT workspace where you can enable developer mode (see Plan availability).

Check your local Codex before wiring anything up:

codex --version

Related MCP server: codex-mcp-server

Setup overview

The full path from a clean clone to a working Codex job:

clone -> install -> configure -> run locally
      -> install tunnel-client -> configure tunnel -> doctor -> run tunnel
      -> connect in ChatGPT -> verify tools -> first Codex job

Each step below corresponds to one stage of that sequence.

1. Clone, install, run locally

git clone https://github.com/joseanu/codex-from-chatgpt.git
cd codex-from-chatgpt
npm install
npm run build
npm start

The process listens on loopback only by default:

• MCP: http://127.0.0.1:8787/mcp

• health: http://127.0.0.1:8787/healthz

• readiness: http://127.0.0.1:8787/readyz

2. Verify the local service

In a second terminal, confirm both the service and the Codex app-server are up. /readyz returns 503 until the app-server has initialized:

curl -fsS http://127.0.0.1:8787/healthz
curl -fsS http://127.0.0.1:8787/readyz

To use a different administrative root or port:

CODEX_WORKSPACE_ROOT=/absolute/path/to/workspaces PORT=8787 npm start

Leave this process running. Everything below assumes it is up.

3. Install tunnel-client

ChatGPT does not connect directly to 127.0.0.1. OpenAI's supported path for a local MCP server is the Secure MCP Tunnel, run by tunnel-client — a customer-run agent that bridges a private or localhost MCP server to ChatGPT and Codex over long-polling HTTPS, keeping the server off the public internet.

ChatGPT
  -> OpenAI control plane
  -> tunnel-client (on your machine)
  -> http://127.0.0.1:8787/mcp
  -> codex-from-chatgpt
  -> codex app-server --stdio

Get the binary from the OpenAI Platform under Tunnels, or from the release archives. Docker images are published at ghcr.io/openai/tunnel-client. To build from source:

go build -o bin/tunnel-client ./cmd/client

OpenAI recommends starting with the built-in guide:

tunnel-client help quickstart

Credentials, and where each one comes from

Do not use the admin key as the daemon credential — OpenAI's docs call this out explicitly. CONTROL_PLANE_API_KEY is the preferred variable; OPENAI_API_KEY is only a fallback when it is unset.

4. Configure the tunnel

Export the two runtime values:

export CONTROL_PLANE_API_KEY="sk-..."
export CONTROL_PLANE_TUNNEL_ID="tunnel_0123456789abcdef0123456789abcdef"

This project is an HTTP MCP server that is already running, so initialize from the remote-HTTP sample and bind the main channel to its local URL:

tunnel-client init --sample sample_mcp_remote_no_auth \
  --profile codex-from-chatgpt \
  --tunnel-id "$CONTROL_PLANE_TUNNEL_ID" \
  --mcp-server-url http://127.0.0.1:8787/mcp

The resulting profile is YAML, and the main channel is required:

config_version: 1
control_plane:
  tunnel_id: tunnel_0123456789abcdef0123456789abcdef
  api_key: env:CONTROL_PLANE_API_KEY
  base_url: https://api.openai.com
mcp:
  server_urls:
    - channel: main
      url: http://127.0.0.1:8787/mcp

Profiles are discovered under $XDG_CONFIG_HOME/tunnel-client or ~/.config/tunnel-client; a single config file can also be passed with --config or TUNNEL_CLIENT_CONFIG.

5. Doctor, then run the tunnel

Validate before starting the daemon:

tunnel-client doctor --profile codex-from-chatgpt --explain

Then run it in the foreground, in its own terminal:

tunnel-client run --profile codex-from-chatgpt

Host header: /mcp validates the Host header against the configured HOST:PORT and rejects anything else with 403 (see Security and limits). If your tunnel forwards its own hostname instead of the loopback upstream, add it with CODEX_AGENT_ALLOWED_HOSTS and restart this service.

6. Connect it in ChatGPT

Full MCP connectors live behind developer mode. An admin or owner enables it in Workspace Settings → Permissions & Roles → Connected Data → Developer mode / Create custom MCP connectors. Then create the custom MCP app pointing at your tunnel, let ChatGPT scan the tools, and enable it for your chats. Do not enter a 127.0.0.1 URL in ChatGPT — it cannot reach it.

Plan availability

Full MCP support including write actions is in beta for ChatGPT Business, Enterprise, and Edu on ChatGPT web. Pro users can build apps with the Apps SDK and use custom apps in deep research, but for read/fetch actions only.

This matters here: the five tools below are not read-only — they start Codex turns that run commands and change files. On a plan limited to read/fetch, this bridge will not work as intended. This project promises no universal support; only the capabilities your connected ChatGPT environment exposes will be available.

7. Verify the tools

After the scan, ChatGPT should list exactly five tools: codex_start, codex_get, codex_continue, codex_interrupt, and codex_respond_approval. If they are missing, re-check tunnel-client doctor and /readyz before touching anything in ChatGPT.

8. First Codex job

Ask for something read-only first, with an absolute workspace path under the allowed root:

Use codex_start in the workspace "/Users/you/workspace/my-project"
to inspect the git status without modifying any files. Give me the job_id,
then check the result with codex_get.

The normal flow is:

1. codex_start creates the persistent thread and begins the first turn.

2. codex_get returns the compact job snapshot.

3. When a turn finishes, codex_continue sends the next instruction to the same thread.

4. If Codex asks for an approval, codex_respond_approval answers it using the exact request_id from pending_approvals.

5. codex_interrupt stops an active turn when needed.

MCP tools

The public surface is exactly this:

codex_get returns status, job_id, thread_id, turn_id, final_message, latest_diff, files_changed, commands_executed, error, pending_approvals, and — for compatibility — pending_approval as an alias for the first approval. It never returns the raw JSONL stream.

Approvals accept only the values and objects defined by the installed protocol for command execution, file changes, permissions, and legacy approvals. request_id is mandatory: two approvals can be pending at once, and one is never answered by position or by "the last one received".

Lifecycle, persistence, and recovery

States are starting, running, awaiting_approval, interrupting, completed, interrupted, failed, and recovery_required.

v0.2 allows a single active turn per process/app-server. A concurrent start or continue returns a semantic backend-busy error; interrupt remains available for the active turn. A process failure or a timeout with an uncertain outcome leaves the job in recovery_required — never in an invented completed.

The minimal job_id → thread_id index, workspace, last turn, and summary are written atomically to a local file. Its location can be set with CODEX_AGENT_STATE_FILE. Its contents may include final messages, diffs, files, commands, and errors, so treat it as potentially sensitive.

On app-server initialization, persisted jobs are rehydrated via thread/read and, where applicable, thread/resume. If the state cannot be proven, the job stays in recovery_required rather than silently becoming completed.

Security and limits

• The service binds to 127.0.0.1 by default.

• /mcp validates the Host header against the configured HOST:PORT and answers 403 to anything else. This closes DNS rebinding: a website the user visits cannot resolve its own domain to 127.0.0.1 and talk to the local service. Add extra hostnames with CODEX_AGENT_ALLOWED_HOSTS if the tunnel rewrites Host.

• The workspace must be absolute, existing, and under the allowed root.

• NUL bytes, .. segments, invalid roots, and symlink escapes after realpath are rejected.

• The remote client cannot choose config, model, sandbox, or permissions; environment overrides are administrative and local to the process.

• These tools are not read-only. Review Codex approvals before accepting commands, file changes, or permissions.

• Non-loopback binds require the explicit opt-in CODEX_AGENT_ALLOW_NON_LOOPBACK=1, and only when a tunnel covers the whole transport. The tunnel is not part of this repository.

Administrative configuration

• HOST and PORT: default 127.0.0.1:8787.

• CODEX_AGENT_ALLOW_NON_LOOPBACK=1: permits a non-loopback bind, only with equivalent external protection.

• CODEX_AGENT_ALLOWED_HOSTS: comma-separated extra hostnames accepted in the Host header on /mcp. Only needed if the tunnel forwards its own Host instead of the loopback upstream.

• CODEX_BIN: local binary; defaults to codex.

• CODEX_RPC_TIMEOUT_MS: generic RPC timeout; defaults to 30000 ms.

• CODEX_SHUTDOWN_TIMEOUT_MS: graceful shutdown wait; defaults to 2000 ms.

• CODEX_AGENT_STATE_FILE: optional state JSON location.

• CODEX_WORKSPACE_ROOT: optional administrative root; defaults to ~/workspace. Must be an existing absolute path.

• CODEX_AGENT_MODEL and CODEX_AGENT_REASONING_EFFORT: optional local overrides; without them Codex uses its own local configuration.

Protocol compatibility

The implementation is pinned against the observed protocol of codex-cli 0.147.0, app-server v2. The installed binary is the authority: OpenAI/Codex can change independently of your local CLI.

The client uses initialize → initialized, bidirectional JSONL, and the required RPCs thread/start, thread/resume, thread/list, thread/read, turn/start, and turn/interrupt, plus server-initiated approvals.

The generated TypeScript bindings in protocol/codex-0.147.0-ts/ are tracked because the code imports them for build-time type safety.

The JSON schemas are not tracked — nothing in the runtime or the build consumes them, so the repository does not carry hundreds of derived files. If you want them as a protocol reference, generate them against your installed binary:

codex app-server generate-json-schema --out protocol/codex-0.147.0-json-schema

That directory is in .gitignore. To move the pin to another version, install and verify the new CLI and regenerate the bindings:

codex app-server generate-ts --out protocol/codex-<version>-ts

Then review imports, approvals, and tests against the installed binary.

Local validation

npm run typecheck
npm test
npm run build
git diff --check

The optional integration test against the installed binary:

CODEX_REAL_APP_SERVER=1 npm test -- --test-name-pattern='installed codex'

Built using itself

codex-from-chatgpt was built and validated through the same loop it exposes: ChatGPT coordinated tasks over MCP, the bridge created local Codex threads, and the app-server returned snapshots to review the result. That loop was used for the implementation, follow-ups, independent reviews, and for answering Codex approvals.

It also works for maintaining the project:

1. Use codex_start to investigate a change and its risks.

2. Use codex_continue to implement or fix one concrete part.

3. Use codex_get to review the diff, files, commands, errors, and pending approvals.

4. Use codex_respond_approval to answer specific approvals via their exact request_id.

5. Run independent reviews, then npm run typecheck, npm test, and git diff --check before calling a change done.

The idea is that the bridge is both the development tool and the artifact that documents how it is used.

Documentation and sources

Official OpenAI documentation this project is built against:

• Secure MCP Tunnel guide

• openai/tunnel-client

• tunnel-client onboarding

• tunnel-client configuration reference

• tunnel-client permissions

• tunnel-client troubleshooting

• Developer mode and MCP apps in ChatGPT

• MCP in ChatGPT

• Codex App Server

Everything outside those interfaces — the job model, the compact snapshot, the approval routing by request_id, the recovery semantics, and the workspace validation — is this project's own design.

License

MIT. See LICENSE.