Local Codex Bridge

Frozen experimental reference. This repository is intended to remain read-only and is not production-ready or supported. It did not complete authenticated Tunnel, macOS real-device, or Android ChatGPT Work validation. See EXPERIMENTAL.md.

Local Codex Bridge is a narrow MCP control plane for Codex native sessions on a user-approved Windows or macOS host. It is designed for authenticated access through OpenAI Secure MCP Tunnel.

The bridge translates eight explicit operations. Codex native threads remain the only source of truth for session identity, history, runtime state, and results.

Status

Development is frozen. The source is published only to preserve the protocol, security-boundary, and testing work as an experimental reference. No runnable release artifact is provided.

Related MCP server: subcodex-mcp

Security boundary

• No arbitrary shell, process, filesystem, archive, delete, fork, or rollback tool is exposed.

• Callers choose a locally approved workspace identifier, never an arbitrary machine path.

• Callers cannot override the configured permission profile, sandbox, network policy, model-provider configuration, or App Server configuration.

• The bridge has no session database, transcript mirror, task registry, or durable pending-request store.

• Secrets belong in Windows DPAPI-protected storage or macOS Keychain and must not enter repository files, command arguments, logs, screenshots, or fixtures.

See the threat model and protocol decisions before operating the bridge. The architecture notes describe state ownership, the fixed process boundary, and restart behavior. Platform setup documents credentials, launchers, managed tunnel supervision, and recovery. The real-device acceptance runbook defines the Windows, macOS, Tunnel, and Android evidence procedure without retaining native identities or private host metadata beyond its explicit public-version allowlist. Its sanitized report format preserves a historical, uncompleted runtime-release gate; it is not evidence for this frozen source publication. The release runbook defines the fail-closed publication gate.

Development

Requires Node.js 24 or newer, npm, Codex CLI, and gitleaks.

npm ci
npm run check
npm run secret:scan

The commands above are for source inspection and test reproduction, not an installation or deployment recommendation.

Non-goals

V1 does not wake dormant ChatGPT conversations, implement Workspace Agents API triggers, control turns owned by another App Server runtime, or provide a general remote shell.

License

MIT.