Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(codex): explain why wrapped Codex runs without the shared server (#3899)

Sudhindra Desai1982b3a77309
diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdx
index ffc1dc9d3..f4476b938 100644
--- a/docs/content/docs/proxy.mdx
+++ b/docs/content/docs/proxy.mdx
@@ -803,6 +803,22 @@ headroom wrap cursor
headroom wrap grok-build
```
+`headroom wrap codex` keeps routing scoped to the Codex process it launches: it
+passes the proxy URL as a `--config` override and never writes it to
+`~/.codex/config.toml`. Codex runs any session started with command-line
+overrides in embedded mode, so a wrapped session does not use Codex's shared
+background server and Codex prints "Running without the shared background
+server". If you want the shared server, write the proxy routing to Codex's own
+config instead, then start `codex` directly:
+
+```bash
+headroom init codex # this project's .codex/config.toml (trusted projects)
+headroom init -g codex # ~/.codex/config.toml, for every project
+```
+
+That routing is persistent: it applies to every Codex session in that scope
+until you remove it.
+
Cursor reads model endpoints from its settings UI, so `headroom wrap cursor`
does not rewrite Cursor configuration or launch the app. After it starts the
proxy, copy the printed base URL into Cursor's model settings.
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 210b1b368..c5428b94f 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -2915,6 +2915,13 @@ def _codex_dotted_key(*parts: str) -> str:
)
+_CODEX_EMBEDDED_MODE_NOTE = (
+ "Note: session-scoped routing runs Codex without its shared background server "
+ "(embedded mode). To keep the shared server, route through Codex config instead: "
+ "run `headroom init codex` (or `headroom init -g codex`) once, then start `codex` directly."
+)
+
+
def _codex_session_launch_settings(
*, port: int, codex_args: tuple[str, ...], environ: dict[str, str]
) -> tuple[tuple[str, ...], dict[str, str], list[str]]:
@@ -2974,6 +2981,11 @@ def _codex_session_launch_settings(
if project and "HEADROOM_PROJECT" not in env:
env["HEADROOM_PROJECT"] = project
+ # Routing is passed as ``--config`` so it stays scoped to this process, and
+ # Codex runs any session with command-line overrides in embedded mode,
+ # without its shared background server (#3888). Say so up front, and point
+ # at the persistent alternative that leaves the shared server in play.
+ display.append(_CODEX_EMBEDDED_MODE_NOTE)
config_args = tuple(item for override in overrides for item in ("--config", override))
return (*config_args, *codex_args), env, display
diff --git a/tests/test_cli/test_wrap_codex.py b/tests/test_cli/test_wrap_codex.py
index 8a2dbd96f..95ccffe0d 100644
--- a/tests/test_cli/test_wrap_codex.py
+++ b/tests/test_cli/test_wrap_codex.py
@@ -1448,7 +1448,10 @@ def test_codex_session_launch_settings_keep_routing_process_local(
)
assert env["CODEX_HOME"] == str(codex_home)
assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9898/v1"
- assert display == ["OPENAI_BASE_URL=http://127.0.0.1:9898/v1"]
+ assert display == [
+ "OPENAI_BASE_URL=http://127.0.0.1:9898/v1",
+ wrap_mod._CODEX_EMBEDDED_MODE_NOTE,
+ ]
assert config_file.read_text(encoding="utf-8") == original_config
@@ -1467,7 +1470,7 @@ def test_codex_session_launch_settings_preserve_custom_provider_identity(
)
config_file.write_text(original_config, encoding="utf-8")
- args, env, _ = wrap_mod._codex_session_launch_settings(
+ args, env, display = wrap_mod._codex_session_launch_settings(
port=9898,
codex_args=("--profile", "work"),
environ={"CODEX_HOME": str(codex_home)},
@@ -1482,6 +1485,8 @@ def test_codex_session_launch_settings_preserve_custom_provider_identity(
'="HEADROOM_CODEX_UPSTREAM_BASE_URL"'
) in args
assert env[wrap_mod._UPSTREAM_BASE_URL_ENV_VAR] == "https://api.example.test/v1"
+ # Custom-provider routing also goes through --config, so the note applies (#3888).
+ assert display[-1] == wrap_mod._CODEX_EMBEDDED_MODE_NOTE
assert config_file.read_text(encoding="utf-8") == original_config