add(core): managed config (#3868)

## Summary

- Factor `load_config_as_toml` into `core::config_loader` so config
loading is reusable across callers.
- Layer `~/.codex/config.toml`, optional `~/.codex/managed_config.toml`,
and macOS managed preferences (base64) with recursive table merging and
scoped threads per source.

## Config Flow

```
Managed prefs (macOS profile: com.openai.codex/config_toml_base64)
                               ▲
                               │
~/.codex/managed_config.toml   │  (optional file-based override)
                               ▲
                               │
                ~/.codex/config.toml (user-defined settings)
```

- The loader searches under the resolved `CODEX_HOME` directory
(defaults to `~/.codex`).
- Managed configs let administrators ship fleet-wide overrides via
device profiles which is useful for enforcing certain settings like
sandbox or approval defaults.
- For nested hash tables: overlays merge recursively. Child tables are
merged key-by-key, while scalar or array values replace the prior layer
entirely. This lets admins add or tweak individual fields without
clobbering unrelated user settings.

Author: fouad-openai

codex-rs/Cargo.lock

@@ -500,7 +500,7 @@ impl CodexMessageProcessor {
     }
 
     async fn get_user_saved_config(&self, request_id: RequestId) {
-        let toml_value = match load_config_as_toml(&self.config.codex_home) {
+        let toml_value = match load_config_as_toml(&self.config.codex_home).await {
             Ok(val) => val,
             Err(err) => {
                 let error = JSONRPCErrorError {
@@ -653,18 +653,19 @@ impl CodexMessageProcessor {
     }
 
     async fn process_new_conversation(&self, request_id: RequestId, params: NewConversationParams) {
-        let config = match derive_config_from_params(params, self.codex_linux_sandbox_exe.clone()) {
-            Ok(config) => config,
-            Err(err) => {
-                let error = JSONRPCErrorError {
-                    code: INVALID_REQUEST_ERROR_CODE,
-                    message: format!("error deriving config: {err}"),
-                    data: None,
-                };
-                self.outgoing.send_error(request_id, error).await;
-                return;
-            }
-        };
+        let config =
+            match derive_config_from_params(params, self.codex_linux_sandbox_exe.clone()).await {
+                Ok(config) => config,
+                Err(err) => {
+                    let error = JSONRPCErrorError {
+                        code: INVALID_REQUEST_ERROR_CODE,
+                        message: format!("error deriving config: {err}"),
+                        data: None,
+                    };
+                    self.outgoing.send_error(request_id, error).await;
+                    return;
+                }
+            };
 
         match self.conversation_manager.new_conversation(config).await {
             Ok(conversation_id) => {
@@ -752,7 +753,7 @@ impl CodexMessageProcessor {
         // Derive a Config using the same logic as new conversation, honoring overrides if provided.
         let config = match params.overrides {
             Some(overrides) => {
-                derive_config_from_params(overrides, self.codex_linux_sandbox_exe.clone())
+                derive_config_from_params(overrides, self.codex_linux_sandbox_exe.clone()).await
             }
             None => Ok(self.config.as_ref().clone()),
         };
@@ -1320,7 +1321,7 @@ async fn apply_bespoke_event_handling(
     }
 }
 
-fn derive_config_from_params(
+async fn derive_config_from_params(
     params: NewConversationParams,
     codex_linux_sandbox_exe: Option<PathBuf>,
 ) -> std::io::Result<Config> {
@@ -1358,7 +1359,7 @@ fn derive_config_from_params(
         .map(|(k, v)| (k, json_to_toml(v)))
         .collect();
 
-    Config::load_with_cli_overrides(cli_overrides, overrides)
+    Config::load_with_cli_overrides(cli_overrides, overrides).await
 }
 
 async fn on_patch_approval_response(

codex-rs/app-server/src/codex_message_processor.rs

@@ -81,6 +81,7 @@ pub async fn run_main(
         )
     })?;
     let config = Config::load_with_cli_overrides(cli_kv_overrides, ConfigOverrides::default())
+        .await
         .map_err(|e| {
             std::io::Error::new(ErrorKind::InvalidData, format!("error loading config: {e}"))
         })?;

codex-rs/app-server/src/lib.rs

@@ -29,7 +29,8 @@ pub async fn run_apply_command(
             .parse_overrides()
             .map_err(anyhow::Error::msg)?,
         ConfigOverrides::default(),
-    )?;
+    )
+    .await?;
 
     init_chatgpt_token_from_auth(&config.codex_home).await?;
 

codex-rs/chatgpt/src/apply_command.rs

@@ -73,7 +73,8 @@ async fn run_command_under_sandbox(
             codex_linux_sandbox_exe,
             ..Default::default()
         },
-    )?;
+    )
+    .await?;
 
     // In practice, this should be `std::env::current_dir()` because this CLI
     // does not support `--cwd`, but let's use the config value for consistency.

codex-rs/cli/src/debug_sandbox.rs

@@ -26,7 +26,7 @@ pub async fn login_with_chatgpt(codex_home: PathBuf) -> std::io::Result<()> {
 }
 
 pub async fn run_login_with_chatgpt(cli_config_overrides: CliConfigOverrides) -> ! {
-    let config = load_config_or_exit(cli_config_overrides);
+    let config = load_config_or_exit(cli_config_overrides).await;
 
     match login_with_chatgpt(config.codex_home).await {
         Ok(_) => {
@@ -44,7 +44,7 @@ pub async fn run_login_with_api_key(
     cli_config_overrides: CliConfigOverrides,
     api_key: String,
 ) -> ! {
-    let config = load_config_or_exit(cli_config_overrides);
+    let config = load_config_or_exit(cli_config_overrides).await;
 
     match login_with_api_key(&config.codex_home, &api_key) {
         Ok(_) => {
@@ -91,7 +91,7 @@ pub async fn run_login_with_device_code(
     issuer_base_url: Option<String>,
     client_id: Option<String>,
 ) -> ! {
-    let config = load_config_or_exit(cli_config_overrides);
+    let config = load_config_or_exit(cli_config_overrides).await;
     let mut opts = ServerOptions::new(
         config.codex_home,
         client_id.unwrap_or(CLIENT_ID.to_string()),
@@ -112,7 +112,7 @@ pub async fn run_login_with_device_code(
 }
 
 pub async fn run_login_status(cli_config_overrides: CliConfigOverrides) -> ! {
-    let config = load_config_or_exit(cli_config_overrides);
+    let config = load_config_or_exit(cli_config_overrides).await;
 
     match CodexAuth::from_codex_home(&config.codex_home) {
         Ok(Some(auth)) => match auth.mode {
@@ -143,7 +143,7 @@ pub async fn run_login_status(cli_config_overrides: CliConfigOverrides) -> ! {
 }
 
 pub async fn run_logout(cli_config_overrides: CliConfigOverrides) -> ! {
-    let config = load_config_or_exit(cli_config_overrides);
+    let config = load_config_or_exit(cli_config_overrides).await;
 
     match logout(&config.codex_home) {
         Ok(true) => {
@@ -161,7 +161,7 @@ pub async fn run_logout(cli_config_overrides: CliConfigOverrides) -> ! {
     }
 }
 
-fn load_config_or_exit(cli_config_overrides: CliConfigOverrides) -> Config {
+async fn load_config_or_exit(cli_config_overrides: CliConfigOverrides) -> Config {
     let cli_overrides = match cli_config_overrides.parse_overrides() {
         Ok(v) => v,
         Err(e) => {
@@ -171,7 +171,7 @@ fn load_config_or_exit(cli_config_overrides: CliConfigOverrides) -> Config {
     };
 
     let config_overrides = ConfigOverrides::default();
-    match Config::load_with_cli_overrides(cli_overrides, config_overrides) {
+    match Config::load_with_cli_overrides(cli_overrides, config_overrides).await {
         Ok(config) => config,
         Err(e) => {
             eprintln!("Error loading configuration: {e}");

codex-rs/cli/src/login.rs

@@ -113,30 +113,30 @@ impl McpCli {
 
         match subcommand {
             McpSubcommand::List(args) => {
-                run_list(&config_overrides, args)?;
+                run_list(&config_overrides, args).await?;
             }
             McpSubcommand::Get(args) => {
-                run_get(&config_overrides, args)?;
+                run_get(&config_overrides, args).await?;
             }
             McpSubcommand::Add(args) => {
-                run_add(&config_overrides, args)?;
+                run_add(&config_overrides, args).await?;
             }
             McpSubcommand::Remove(args) => {
-                run_remove(&config_overrides, args)?;
+                run_remove(&config_overrides, args).await?;
             }
             McpSubcommand::Login(args) => {
                 run_login(&config_overrides, args).await?;
             }
             McpSubcommand::Logout(args) => {
-                run_logout(&config_overrides, args)?;
+                run_logout(&config_overrides, args).await?;
             }
         }
 
         Ok(())
     }
 }
 
-fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Result<()> {
+async fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Result<()> {
     // Validate any provided overrides even though they are not currently applied.
     config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
 
@@ -162,6 +162,7 @@ fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Result<(
 
     let codex_home = find_codex_home().context("failed to resolve CODEX_HOME")?;
     let mut servers = load_global_mcp_servers(&codex_home)
+        .await
         .with_context(|| format!("failed to load MCP servers from {}", codex_home.display()))?;
 
     let new_entry = McpServerConfig {
@@ -184,7 +185,7 @@ fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Result<(
     Ok(())
 }
 
-fn run_remove(config_overrides: &CliConfigOverrides, remove_args: RemoveArgs) -> Result<()> {
+async fn run_remove(config_overrides: &CliConfigOverrides, remove_args: RemoveArgs) -> Result<()> {
     config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
 
     let RemoveArgs { name } = remove_args;
@@ -193,6 +194,7 @@ fn run_remove(config_overrides: &CliConfigOverrides, remove_args: RemoveArgs) ->
 
     let codex_home = find_codex_home().context("failed to resolve CODEX_HOME")?;
     let mut servers = load_global_mcp_servers(&codex_home)
+        .await
         .with_context(|| format!("failed to load MCP servers from {}", codex_home.display()))?;
 
     let removed = servers.remove(&name).is_some();
@@ -214,6 +216,7 @@ fn run_remove(config_overrides: &CliConfigOverrides, remove_args: RemoveArgs) ->
 async fn run_login(config_overrides: &CliConfigOverrides, login_args: LoginArgs) -> Result<()> {
     let overrides = config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
     let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+        .await
         .context("failed to load configuration")?;
 
     if !config.use_experimental_use_rmcp_client {
@@ -238,9 +241,10 @@ async fn run_login(config_overrides: &CliConfigOverrides, login_args: LoginArgs)
     Ok(())
 }
 
-fn run_logout(config_overrides: &CliConfigOverrides, logout_args: LogoutArgs) -> Result<()> {
+async fn run_logout(config_overrides: &CliConfigOverrides, logout_args: LogoutArgs) -> Result<()> {
     let overrides = config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
     let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+        .await
         .context("failed to load configuration")?;
 
     let LogoutArgs { name } = logout_args;
@@ -264,9 +268,10 @@ fn run_logout(config_overrides: &CliConfigOverrides, logout_args: LogoutArgs) ->
     Ok(())
 }
 
-fn run_list(config_overrides: &CliConfigOverrides, list_args: ListArgs) -> Result<()> {
+async fn run_list(config_overrides: &CliConfigOverrides, list_args: ListArgs) -> Result<()> {
     let overrides = config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
     let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+        .await
         .context("failed to load configuration")?;
 
     let mut entries: Vec<_> = config.mcp_servers.iter().collect();
@@ -424,9 +429,10 @@ fn run_list(config_overrides: &CliConfigOverrides, list_args: ListArgs) -> Resul
     Ok(())
 }
 
-fn run_get(config_overrides: &CliConfigOverrides, get_args: GetArgs) -> Result<()> {
+async fn run_get(config_overrides: &CliConfigOverrides, get_args: GetArgs) -> Result<()> {
     let overrides = config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
     let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+        .await
         .context("failed to load configuration")?;
 
     let Some(server) = config.mcp_servers.get(&get_args.name) else {

codex-rs/cli/src/mcp_cmd.rs

@@ -13,8 +13,8 @@ fn codex_command(codex_home: &Path) -> Result<assert_cmd::Command> {
     Ok(cmd)
 }
 
-#[test]
-fn add_and_remove_server_updates_global_config() -> Result<()> {
+#[tokio::test]
+async fn add_and_remove_server_updates_global_config() -> Result<()> {
     let codex_home = TempDir::new()?;
 
     let mut add_cmd = codex_command(codex_home.path())?;
@@ -24,7 +24,7 @@ fn add_and_remove_server_updates_global_config() -> Result<()> {
         .success()
         .stdout(contains("Added global MCP server 'docs'."));
 
-    let servers = load_global_mcp_servers(codex_home.path())?;
+    let servers = load_global_mcp_servers(codex_home.path()).await?;
     assert_eq!(servers.len(), 1);
     let docs = servers.get("docs").expect("server should exist");
     match &docs.transport {
@@ -43,7 +43,7 @@ fn add_and_remove_server_updates_global_config() -> Result<()> {
         .success()
         .stdout(contains("Removed global MCP server 'docs'."));
 
-    let servers = load_global_mcp_servers(codex_home.path())?;
+    let servers = load_global_mcp_servers(codex_home.path()).await?;
     assert!(servers.is_empty());
 
     let mut remove_again_cmd = codex_command(codex_home.path())?;
@@ -53,14 +53,14 @@ fn add_and_remove_server_updates_global_config() -> Result<()> {
         .success()
         .stdout(contains("No MCP server named 'docs' found."));
 
-    let servers = load_global_mcp_servers(codex_home.path())?;
+    let servers = load_global_mcp_servers(codex_home.path()).await?;
     assert!(servers.is_empty());
 
     Ok(())
 }
 
-#[test]
-fn add_with_env_preserves_key_order_and_values() -> Result<()> {
+#[tokio::test]
+async fn add_with_env_preserves_key_order_and_values() -> Result<()> {
     let codex_home = TempDir::new()?;
 
     let mut add_cmd = codex_command(codex_home.path())?;
@@ -80,7 +80,7 @@ fn add_with_env_preserves_key_order_and_values() -> Result<()> {
         .assert()
         .success();
 
-    let servers = load_global_mcp_servers(codex_home.path())?;
+    let servers = load_global_mcp_servers(codex_home.path()).await?;
     let envy = servers.get("envy").expect("server should exist");
     let env = match &envy.transport {
         McpServerTransportConfig::Stdio { env: Some(env), .. } => env,

codex-rs/cli/tests/mcp_add_remove.rs

@@ -19,13 +19,13 @@ async-trait = { workspace = true }
 base64 = { workspace = true }
 bytes = { workspace = true }
 chrono = { workspace = true, features = ["serde"] }
+codex-app-server-protocol = { workspace = true }
 codex-apply-patch = { workspace = true }
 codex-file-search = { workspace = true }
 codex-mcp-client = { workspace = true }
-codex-rmcp-client = { workspace = true }
-codex-protocol = { workspace = true }
-codex-app-server-protocol = { workspace = true }
 codex-otel = { workspace = true, features = ["otel"] }
+codex-protocol = { workspace = true }
+codex-rmcp-client = { workspace = true }
 codex-utils-string = { workspace = true }
 dirs = { workspace = true }
 dunce = { workspace = true }
@@ -76,6 +76,9 @@ wildmatch = { workspace = true }
 landlock = { workspace = true }
 seccompiler = { workspace = true }
 
+[target.'cfg(target_os = "macos")'.dependencies]
+core-foundation = "0.9"
+
 # Build OpenSSL from source for musl builds.
 [target.x86_64-unknown-linux-musl.dependencies]
 openssl-sys = { workspace = true, features = ["vendored"] }