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

## Description

`headroom wrap codex` passes proxy routing as a `--config` override
(`openai_base_url=…`, or `model_providers.<id>.base_url=…` for custom
providers). This keeps routing scoped to the launched process and leaves
`~/.codex/config.toml` untouched, by design (#1507, #2160). Codex 0.159
runs any session that has command-line overrides in embedded mode, so
wrapped sessions always print `Running without the shared background
server` and never use Codex's shared background server.

Env-only routing can't replace the override. ChatGPT-subscription Codex
ignores `OPENAI_BASE_URL` (see 5c7a5b48 / d54c5b6a), so
`openai_base_url` has to come from config. A shared server also serves
every session at once, so a per-session base URL can't apply to it.

The issue accepts "explicit documentation of the limitation", so this PR
does that:

- `wrap codex` now prints a one-line note at launch that explains
embedded mode and points to the persistent alternative.
- The proxy docs describe the limitation and the alternative: `headroom
init codex` (project) or `headroom init -g codex` (user) writes the
routing to Codex's own config, so a plain `codex` launch keeps the
shared server.

Closes #3888

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/cli/wrap.py`: new `_CODEX_EMBEDDED_MODE_NOTE`.
`_codex_session_launch_settings` appends it to the launch display lines,
so it prints under `Launching CODEX…` for both the built-in `openai`
provider and custom providers.
- `docs/content/docs/proxy.mdx`: new paragraph under "Agent wrapping"
covering why wrapped Codex uses embedded mode, plus the `headroom init
codex` / `headroom init -g codex` alternative and its persistent scope.
- `tests/test_cli/test_wrap_codex.py`: asserts the note for both
provider paths.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`): not run successfully. My
local mypy stops on an unrelated numpy stub syntax error in this env
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ pytest tests/test_cli/test_wrap_codex.py -q
101 passed in 5.68s

$ pytest tests/test_cli -q -k codex
176 passed, 738 deselected in 6.84s

$ ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_codex.py
All checks passed!
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, branch head
- Exact command / steps: `python -c "import headroom.cli.wrap as w;
print(w._CODEX_EMBEDDED_MODE_NOTE)"`
- Observed result: the note prints as expected (below), and the codex
wrap tests assert it appears in the launch display for both the built-in
`openai` provider and custom providers:
  ```text
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.
  ```
- Not tested: a live `headroom wrap codex` launch against Codex CLI
0.159.2 (Codex isn't installed on my machine). I also didn't verify end
to end that an `init`-configured plain `codex` launch keeps the shared
server, though that path passes no command-line overrides.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: No. Routing is unchanged; only one
extra banner line is printed.
- Kill switch / disable path: N/A
- Unsafe override required: No
- Qualification impact: None
- Rollback path: revert this PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

A follow-up could skip the `--config` override when Codex's effective
config already routes the selected provider to this proxy, for example
after `headroom init codex`. That would let `wrap codex` itself keep the
shared server. The trade-off is losing the per-project `/p/<project>`
URL prefix for those sessions, so I left it out of this PR. Happy to add
it if maintainers want that behavior.
This commit is contained in:
Sudhindra Desai
2026-10-01 12:15:47 -05:00
committed by GitHub
parent c46e7cc651
commit 1982b3a773
3 changed files with 35 additions and 2 deletions
+16
View File
@@ -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.
+12
View File
@@ -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
+7 -2
View File
@@ -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