@tumnel/codex

Standalone connector that bridges the Codex CLI agent to Tumnel web clients. It spawns the same codex binary used by ChatGPT and Codex Desktop (@openai/codex-sdk over stdio), exposes it through the Tumnel bridge protocol, and lets Tumnel web clients build and control Codex threads with the same experience as the OpenCode connector: sessions, streaming turns, tools, and pairing.

Install and run the connector

The standard setup command prepares the host identity and starts the connector:

npx @tumnel/[email protected] install

connect remains available as an explicit alias:

npx @tumnel/[email protected] connect

The connector starts the Codex agent bridge and keeps it connected to the Tumnel relay until interrupted:

npx @tumnel/codex --model gpt-5-mini --sandbox workspace-write --approval-policy on-request

If --model (or CODEX_MODEL) is omitted, the web model picker still exposes a Codex default option and the SDK resolves the model from the local Codex configuration.

It binds a pairing-only endpoint to 127.0.0.1:43817 (use --port to override). It accepts approved OpenBridge origins, returns short-lived signed proofs, and never exposes Codex API keys or model credentials over localhost.

The host identity is an Ed25519 key pair stored at ~/.config/tumnel/identity.json. When OpenCode was installed first, Codex adopts its existing identity so the computer remains one paired Tumnel host. Codex still has an isolated connector channel, project/session state, events, and preferences. Legacy Codex identities are migrated automatically when no shared or OpenCode identity exists.

Configuration

| Flag | Environment | Default | | --- | --- | --- | | --relay-url | TUMNEL_RELAY_URL | https://openbridge.jlfloressanchez01.workers.dev | | --port | TUMNEL_LOCAL_PORT | 43817 | | --model | CODEX_MODEL | Codex default | | --sandbox | CODEX_SANDBOX | workspace-write | | --approval-policy | CODEX_APPROVAL_POLICY | on-request | | — | CODEX_REASONING_EFFORT | — | | — | CODEX_WEB_SEARCH | — | | — | CODEX_NETWORK_ACCESS | false | | — | CODEX_SKIP_GIT_REPO_CHECK | false | | — | CODEX_HOME | ~/.codex |

Architecture

• buildUserMessage/itemPart map Codex thread items (agent_message, reasoning, command_execution, file_change, mcp_tool_call, web_search) to the frontend message/part shape used by the OpenCode connector.
• A turn (session.prompt) runs thread.runStreamed(input, { signal }); every thread event is relayed as a session.status / message.updated / message.part.updated / session.idle bridge event, and the observed messages are served back through session.messages.
• Projects and threads are discovered from the Codex desktop catalog (~/.codex/.codex-global-state.json and ~/.codex/session_index.jsonl) plus the persisted rollout files under ~/.codex/sessions/**/rollout-*.jsonl. This keeps project names/order and session titles aligned with the local Codex app while still allowing older rollouts to be reconstructed and resumed.

Known limitations

• session.fork is not supported (the Codex SDK has no fork API).
• Permission prompts are configured through CODEX_APPROVAL_POLICY; codex exec is non-interactive, so permission.list returns no pending approvals and the web approval cards are not shown for this connector.
• session.messages reconstructs the visible history for discovered sessions from Codex rollout JSONL files, including user/assistant text and supported tool call output.
• Only text and local file parts are forwarded; other attachment types are skipped.