Skip to main content

Codex CLI

Connect OpenAI's Codex CLI to TermFlow so it can open terminals, split panes, run commands, and read output through TermFlow's built-in MCP server. This page gives you the exact config.toml block to paste, tells you where that file lives, and explains when the auth token is actually required.

Before you start

TermFlow must be running, and its MCP server must be healthy. Open Settings → Connections and confirm the health dot is green. By default TermFlow serves MCP at http://127.0.0.1:42032/mcp, bound to 127.0.0.1 (localhost only). You bring your own Codex install and your own model keys — TermFlow ships no AI.

The config block​

Codex configures MCP servers in its config.toml. Add this table, exactly as shown:

[mcp_servers.auto-terminal]
url = "http://127.0.0.1:42032/mcp"
http_headers = { "Authorization" = "Bearer <token>" }
env_http_headers = { "X-Termflow-Terminal-Id" = "TERMFLOW_TERMINAL_ID" }

This is the paste-ready output of TermFlow's in-app Connect an AI agent modal (Settings → Connections). Copying it from there fills in your real token automatically.

The server key is the literal string auto-terminal — that is TermFlow's MCP server identifier, and it is what you will see referenced when Codex lists connected servers.

What each line does​

LinePurpose
[mcp_servers.auto-terminal]Registers a streamable-HTTP MCP server under the key auto-terminal.
urlTermFlow's MCP endpoint. Prod default is http://127.0.0.1:42032/mcp (MCP port 42032).
http_headersStatic request headers. Here it carries the Authorization: Bearer <token> credential.
env_http_headersHeaders whose value is read from an environment variable at launch. Here X-Termflow-Terminal-Id is populated from the TERMFLOW_TERMINAL_ID variable.
note
env_http_headers maps a header to a variable name

The right-hand side "TERMFLOW_TERMINAL_ID" is the name of an environment variable, not a literal value and not ${...} syntax. At startup Codex reads the current value of TERMFLOW_TERMINAL_ID from its own environment and sends it as the X-Termflow-Terminal-Id header. See The identity header below for why this matters.

Where Codex reads config.toml​

Codex loads configuration from config.toml inside its home directory, CODEX_HOME, which defaults to a .codex folder in your user home:

PlatformPath
Windows%USERPROFILE%\.codex\config.toml
macOS~/.codex/config.toml
Linux~/.codex/config.toml

If the file does not exist yet, create it. If you have set the CODEX_HOME environment variable to relocate Codex's config, the file lives at $CODEX_HOME/config.toml instead. After editing, restart Codex (or reload its MCP configuration) so it picks up the new server.

When you actually need the token​

TermFlow's auth model is deliberately quiet on localhost:

  • Default (localhost only): every TermFlow endpoint is unauthenticated. This is safe because the server is bound to 127.0.0.1 and never leaves your machine. You can drop the http_headers line entirely, or leave the placeholder in — nothing checks it.
  • Exposed on LAN: if you turn on Expose on local network in Settings → Connections, the bearer token becomes required. Replace <token> with the value shown in Settings → Connections (the masked authToken field — use its reveal/copy control).

So the minimal localhost config is simply:

[mcp_servers.auto-terminal]
url = "http://127.0.0.1:42032/mcp"
env_http_headers = { "X-Termflow-Terminal-Id" = "TERMFLOW_TERMINAL_ID" }
Rotating the token

The token in Settings → Connections can be rotated at any time (no restart needed for TermFlow's own UI). If you rotate it while exposed on LAN, update the Bearer <token> value in config.toml to match, then restart Codex.

The identity header​

When TermFlow spawns a shell, it injects a TERMFLOW_TERMINAL_ID environment variable into that terminal. The env_http_headers line turns that variable into the X-Termflow-Terminal-Id request header, which lets Codex ask MCP tools about its own terminal — for example the get_my_terminal tool, or passing the shorthand "me" wherever a terminal id is expected.

This only carries meaning when Codex is launched from inside a TermFlow terminal pane, because that is where TERMFLOW_TERMINAL_ID is set. If you run Codex in an ordinary terminal outside TermFlow, the variable isn't present, and the self-identification tools simply have nothing to resolve to — the other tools (list, create, execute, read output) still work fine. If you never launch Codex inside TermFlow, you can omit the env_http_headers line.

How the connection flows​

Verify it works​

  1. Save config.toml and restart Codex.
  2. Ask Codex to list your terminals — it should call the list_terminals MCP tool and return the terminals currently open in TermFlow.
  3. Ask it to open a terminal and run a command; the new terminal should appear in the TermFlow window.

If Codex reports it cannot reach the server, re-check the health dot in Settings → Connections, confirm the port is 42032, and confirm you are using http://127.0.0.1:42032/mcp (note the /mcp path).

An honest note: hosting an agent inside TermFlow (the ACP direction) is on the roadmap, not shipped. Today the relationship is the other way around — Codex is an MCP client that drives TermFlow. TermFlow bundles no AI and no keys; Codex uses its own.

Next steps​