Add a config-file-only path override separate from CODEX_HOME

What variant of Codex are you using?

Codex CLI, app-server, and IDE integrations inside Linux Dev Containers.

What feature would you like to see?

Please add a stable public environment variable that selects the base user configuration file without relocating the rest of Codex state. For example:

CODEX_CONFIG_PATH=/mnt/codex/config_devcontainer.toml codex

The exact variable name is not important. The important behavior is that only the user config.toml location changes while CODEX_HOME continues to own container-local state.

Why CODEX_HOME is not a solution

The official documentation describes CODEX_HOME as the root for config, auth, logs, sessions, skills, and standalone package metadata:

https://learn.chatgpt.com/docs/config-file/environment-variables

It also contains runtime and IPC state used by the background server. For example, codex doctor reports paths such as:

Background Server
  app-server                running (ephemeral mode)
  daemon state dir          ~/.codex/app-server-daemon
  settings                  ~/.codex/app-server-daemon/settings.json
  pid file                  ~/.codex/app-server-daemon/app-server.pid
  update-loop pid file      ~/.codex/app-server-daemon/app-server-updater.pid
  control socket            ~/.codex/app-server-control/...sock

In a Dev Container, mounting a host CODEX_HOME merely to reuse config.toml also exposes process-local daemon state, PID files, control sockets, authentication, sessions, logs, and other mutable state to the container.

That creates several failure modes:

• A read-only mount prevents the container daemon from writing required state.
• A writable mount couples independent host and container Codex processes through the same PID files, sockets, databases, and mutable files.
• Ownership, permissions, lifecycle, and namespace differences can make host runtime state invalid inside the container.
• Multiple containers cannot safely share the same host CODEX_HOME.

CODEX_SQLITE_HOME does not solve this because it moves only SQLite-backed state; daemon directories, PID files, sockets, auth, sessions, logs, and other files still follow CODEX_HOME.

Desired flow

Host-managed config
  ~/.codex/config_devcontainer.toml
                |
                | bind mount
                v
Container
  /mnt/codex/config_devcontainer.toml

CODEX_CONFIG_PATH=/mnt/codex/config_devcontainer.toml
CODEX_HOME=/home/vscode/.codex

The mounted configuration is portable and host-managed. The container keeps its daemon files, sockets, sessions, databases, logs, and other runtime state in its private CODEX_HOME.

Proposed behavior

• Accept an absolute config filepath through a stable public environment variable such as CODEX_CONFIG_PATH.
• Use that file as the base user configuration instead of $CODEX_HOME/config.toml.
• Leave all other Codex paths under CODEX_HOME.
• Keep project .codex/config.toml, profiles, managed configuration, and -c/--config overrides working with their documented precedence.
• Ensure all readers and writers of the base user configuration consistently target the selected file.
• Return a clear error for an explicitly configured missing, non-regular, unreadable, unwritable, or invalid TOML path rather than silently falling back.
• Preserve the current behavior when the variable is unset.
• Apply the behavior consistently to the CLI, codex exec, app-server, and IDE integrations.

A CLI option such as --config-file could additionally override the environment variable for one invocation, but the environment-variable support is the essential request.

Current workaround

The current workaround is to mount a separate file and continuously copy or synchronize it with $CODEX_HOME/config.toml. A correct bidirectional synchronizer must handle missing and empty files, initialization ordering, simultaneous edits, partial writes, conflicts, watcher restarts, and container shutdown. This is substantially more fragile than letting Codex read the intended file directly and has caused real empty-file and race-condition failures.

Related issues

• #7971 requested a configurable config path but was closed with CODEX_HOME as the answer. This request explains why changing the whole home directory does not provide config/runtime isolation.
• #8659 requested config/state separation for Docker and was closed for lack of upvotes. This request narrows the API to one explicit config-file override and includes the daemon socket/PID use case.
• #18334 concerns relocating project-scoped configuration rather than the base user config.

Additional information

This request does not require redesigning all Codex storage categories or changing defaults. One config-file-only override would remove the need for fragile synchronization while preserving backward compatibility.