feat(linux-sandbox): add bwrap support (#9938)

## Summary
This PR introduces a gated Bubblewrap (bwrap) Linux sandbox path. The
curent Linux sandbox path relies on in-process restrictions (including
Landlock). Bubblewrap gives us a more uniform filesystem isolation
model, especially explicit writable roots with the option to make some
directories read-only and granular network controls.

This is behind a feature flag so we can validate behavior safely before
making it the default.

- Added temporary rollout flag:
  - `features.use_linux_sandbox_bwrap`
- Preserved existing default path when the flag is off.
- In Bubblewrap mode:
- Added internal retry without /proc when /proc mount is not permitted
by the host/container.

codex-rs/core/config.schema.json

@@ -235,6 +235,9 @@
             "unified_exec": {
               "type": "boolean"
             },
+            "use_linux_sandbox_bwrap": {
+              "type": "boolean"
+            },
             "web_search": {
               "type": "boolean"
             },
@@ -1253,6 +1256,9 @@
         "unified_exec": {
           "type": "boolean"
         },
+        "use_linux_sandbox_bwrap": {
+          "type": "boolean"
+        },
         "web_search": {
           "type": "boolean"
         },

codex-rs/core/src/codex.rs

@@ -508,6 +508,7 @@ pub(crate) struct TurnContext {
     pub(crate) windows_sandbox_level: WindowsSandboxLevel,
     pub(crate) shell_environment_policy: ShellEnvironmentPolicy,
     pub(crate) tools_config: ToolsConfig,
+    pub(crate) features: Features,
     pub(crate) ghost_snapshot: GhostSnapshotConfig,
     pub(crate) final_output_json_schema: Option<Value>,
     pub(crate) codex_linux_sandbox_exe: Option<PathBuf>,
@@ -766,6 +767,7 @@ impl Session {
             windows_sandbox_level: session_configuration.windows_sandbox_level,
             shell_environment_policy: per_turn_config.shell_environment_policy.clone(),
             tools_config,
+            features: per_turn_config.features.clone(),
             ghost_snapshot: per_turn_config.ghost_snapshot.clone(),
             final_output_json_schema: None,
             codex_linux_sandbox_exe: per_turn_config.codex_linux_sandbox_exe.clone(),
@@ -1036,6 +1038,7 @@ impl Session {
             sandbox_policy: session_configuration.sandbox_policy.get().clone(),
             codex_linux_sandbox_exe: config.codex_linux_sandbox_exe.clone(),
             sandbox_cwd: session_configuration.cwd.clone(),
+            use_linux_sandbox_bwrap: config.features.enabled(Feature::UseLinuxSandboxBwrap),
         };
         let cancel_token = sess.mcp_startup_cancellation_token().await;
 
@@ -1285,6 +1288,9 @@ impl Session {
                 sandbox_policy: per_turn_config.sandbox_policy.get().clone(),
                 codex_linux_sandbox_exe: per_turn_config.codex_linux_sandbox_exe.clone(),
                 sandbox_cwd: per_turn_config.cwd.clone(),
+                use_linux_sandbox_bwrap: per_turn_config
+                    .features
+                    .enabled(Feature::UseLinuxSandboxBwrap),
             };
             if let Err(e) = self
                 .services
@@ -2367,6 +2373,7 @@ impl Session {
             sandbox_policy: turn_context.sandbox_policy.clone(),
             codex_linux_sandbox_exe: turn_context.codex_linux_sandbox_exe.clone(),
             sandbox_cwd: turn_context.cwd.clone(),
+            use_linux_sandbox_bwrap: turn_context.features.enabled(Feature::UseLinuxSandboxBwrap),
         };
         let cancel_token = self.reset_mcp_startup_cancellation_token().await;
 
@@ -3343,6 +3350,7 @@ async fn spawn_review_thread(
         session_source,
         transport_manager,
         tools_config,
+        features: parent_turn_context.features.clone(),
         ghost_snapshot: parent_turn_context.ghost_snapshot.clone(),
         developer_instructions: None,
         user_instructions: None,

codex-rs/core/src/connectors.rs

@@ -43,6 +43,7 @@ pub async fn list_accessible_connectors_from_mcp_tools(
         sandbox_policy: SandboxPolicy::ReadOnly,
         codex_linux_sandbox_exe: config.codex_linux_sandbox_exe.clone(),
         sandbox_cwd: env::current_dir().unwrap_or_else(|_| PathBuf::from("/")),
+        use_linux_sandbox_bwrap: config.features.enabled(Feature::UseLinuxSandboxBwrap),
     };
 
     mcp_connection_manager

codex-rs/core/src/exec.rs

@@ -140,6 +140,7 @@ pub async fn process_exec_tool_call(
     sandbox_policy: &SandboxPolicy,
     sandbox_cwd: &Path,
     codex_linux_sandbox_exe: &Option<PathBuf>,
+    use_linux_sandbox_bwrap: bool,
     stdout_stream: Option<StdoutStream>,
 ) -> Result<ExecToolCallOutput> {
     let windows_sandbox_level = params.windows_sandbox_level;
@@ -184,14 +185,15 @@ pub async fn process_exec_tool_call(
 
     let manager = SandboxManager::new();
     let exec_env = manager
-        .transform(
+        .transform(crate::sandboxing::SandboxTransformRequest {
             spec,
-            sandbox_policy,
-            sandbox_type,
-            sandbox_cwd,
-            codex_linux_sandbox_exe.as_ref(),
+            policy: sandbox_policy,
+            sandbox: sandbox_type,
+            sandbox_policy_cwd: sandbox_cwd,
+            codex_linux_sandbox_exe: codex_linux_sandbox_exe.as_ref(),
+            use_linux_sandbox_bwrap,
             windows_sandbox_level,
-        )
+        })
         .map_err(CodexErr::from)?;
 
     // Route through the sandboxing module for a single, unified execution path.
@@ -1108,6 +1110,7 @@ mod tests {
             &SandboxPolicy::DangerFullAccess,
             cwd.as_path(),
             &None,
+            false,
             None,
         )
         .await;

codex-rs/core/src/features.rs

@@ -89,6 +89,8 @@ pub enum Feature {
     WebSearchCached,
     /// Gate the execpolicy enforcement for shell/unified exec.
     ExecPolicy,
+    /// Use the bubblewrap-based Linux sandbox pipeline.
+    UseLinuxSandboxBwrap,
     /// Allow the model to request approval and propose exec rules.
     RequestRule,
     /// Enable Windows sandbox (restricted token) on Windows.
@@ -465,6 +467,12 @@ pub const FEATURES: &[FeatureSpec] = &[
         stage: Stage::UnderDevelopment,
         default_enabled: true,
     },
+    FeatureSpec {
+        id: Feature::UseLinuxSandboxBwrap,
+        key: "use_linux_sandbox_bwrap",
+        stage: Stage::UnderDevelopment,
+        default_enabled: false,
+    },
     FeatureSpec {
         id: Feature::RequestRule,
         key: "request_rule",

codex-rs/core/src/landlock.rs

@@ -6,26 +6,34 @@ use std::path::Path;
 use std::path::PathBuf;
 use tokio::process::Child;
 
-/// Spawn a shell tool command under the Linux Landlock+seccomp sandbox helper
-/// (codex-linux-sandbox).
+/// Spawn a shell tool command under the Linux sandbox helper
+/// (codex-linux-sandbox), which currently uses bubblewrap for filesystem
+/// isolation plus seccomp for network restrictions.
 ///
 /// Unlike macOS Seatbelt where we directly embed the policy text, the Linux
 /// helper accepts a list of `--sandbox-permission`/`-s` flags mirroring the
 /// public CLI. We convert the internal [`SandboxPolicy`] representation into
 /// the equivalent CLI options.
+#[allow(clippy::too_many_arguments)]
 pub async fn spawn_command_under_linux_sandbox<P>(
     codex_linux_sandbox_exe: P,
     command: Vec<String>,
     command_cwd: PathBuf,
     sandbox_policy: &SandboxPolicy,
     sandbox_policy_cwd: &Path,
+    use_bwrap_sandbox: bool,
     stdio_policy: StdioPolicy,
     env: HashMap<String, String>,
 ) -> std::io::Result<Child>
 where
     P: AsRef<Path>,
 {
-    let args = create_linux_sandbox_command_args(command, sandbox_policy, sandbox_policy_cwd);
+    let args = create_linux_sandbox_command_args(
+        command,
+        sandbox_policy,
+        sandbox_policy_cwd,
+        use_bwrap_sandbox,
+    );
     let arg0 = Some("codex-linux-sandbox");
     spawn_child_async(
         codex_linux_sandbox_exe.as_ref().to_path_buf(),
@@ -40,10 +48,14 @@ where
 }
 
 /// Converts the sandbox policy into the CLI invocation for `codex-linux-sandbox`.
+///
+/// The helper performs the actual sandboxing (bubblewrap + seccomp) after
+/// parsing these arguments. See `docs/linux_sandbox.md` for the Linux semantics.
 pub(crate) fn create_linux_sandbox_command_args(
     command: Vec<String>,
     sandbox_policy: &SandboxPolicy,
     sandbox_policy_cwd: &Path,
+    use_bwrap_sandbox: bool,
 ) -> Vec<String> {
     #[expect(clippy::expect_used)]
     let sandbox_policy_cwd = sandbox_policy_cwd
@@ -60,13 +72,42 @@ pub(crate) fn create_linux_sandbox_command_args(
         sandbox_policy_cwd,
         "--sandbox-policy".to_string(),
         sandbox_policy_json,
-        // Separator so that command arguments starting with `-` are not parsed as
-        // options of the helper itself.
-        "--".to_string(),
     ];
+    if use_bwrap_sandbox {
+        linux_cmd.push("--use-bwrap-sandbox".to_string());
+    }
+
+    // Separator so that command arguments starting with `-` are not parsed as
+    // options of the helper itself.
+    linux_cmd.push("--".to_string());
 
     // Append the original tool command.
     linux_cmd.extend(command);
 
     linux_cmd
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn bwrap_flags_are_feature_gated() {
+        let command = vec!["/bin/true".to_string()];
+        let cwd = Path::new("/tmp");
+        let policy = SandboxPolicy::ReadOnly;
+
+        let with_bwrap = create_linux_sandbox_command_args(command.clone(), &policy, cwd, true);
+        assert_eq!(
+            with_bwrap.contains(&"--use-bwrap-sandbox".to_string()),
+            true
+        );
+
+        let without_bwrap = create_linux_sandbox_command_args(command, &policy, cwd, false);
+        assert_eq!(
+            without_bwrap.contains(&"--use-bwrap-sandbox".to_string()),
+            false
+        );
+    }
+}

codex-rs/core/src/mcp/mod.rs

@@ -167,6 +167,7 @@ pub async fn collect_mcp_snapshot(config: &Config) -> McpListToolsResponseEvent
         sandbox_policy: SandboxPolicy::ReadOnly,
         codex_linux_sandbox_exe: config.codex_linux_sandbox_exe.clone(),
         sandbox_cwd: env::current_dir().unwrap_or_else(|_| PathBuf::from("/")),
+        use_linux_sandbox_bwrap: config.features.enabled(Feature::UseLinuxSandboxBwrap),
     };
 
     mcp_connection_manager

codex-rs/core/src/mcp_connection_manager.rs

@@ -313,6 +313,8 @@ pub struct SandboxState {
     pub sandbox_policy: SandboxPolicy,
     pub codex_linux_sandbox_exe: Option<PathBuf>,
     pub sandbox_cwd: PathBuf,
+    #[serde(default)]
+    pub use_linux_sandbox_bwrap: bool,
 }
 
 /// A thin wrapper around a set of running [`RmcpClient`] instances.

codex-rs/core/src/sandboxing/mod.rs

@@ -51,6 +51,19 @@ pub struct ExecEnv {
     pub arg0: Option<String>,
 }
 
+/// Bundled arguments for sandbox transformation.
+///
+/// This keeps call sites self-documenting when several fields are optional.
+pub(crate) struct SandboxTransformRequest<'a> {
+    pub spec: CommandSpec,
+    pub policy: &'a SandboxPolicy,
+    pub sandbox: SandboxType,
+    pub sandbox_policy_cwd: &'a Path,
+    pub codex_linux_sandbox_exe: Option<&'a PathBuf>,
+    pub use_linux_sandbox_bwrap: bool,
+    pub windows_sandbox_level: WindowsSandboxLevel,
+}
+
 pub enum SandboxPreference {
     Auto,
     Require,
@@ -104,13 +117,17 @@ impl SandboxManager {
 
     pub(crate) fn transform(
         &self,
-        mut spec: CommandSpec,
-        policy: &SandboxPolicy,
-        sandbox: SandboxType,
-        sandbox_policy_cwd: &Path,
-        codex_linux_sandbox_exe: Option<&PathBuf>,
-        windows_sandbox_level: WindowsSandboxLevel,
+        request: SandboxTransformRequest<'_>,
     ) -> Result<ExecEnv, SandboxTransformError> {
+        let SandboxTransformRequest {
+            mut spec,
+            policy,
+            sandbox,
+            sandbox_policy_cwd,
+            codex_linux_sandbox_exe,
+            use_linux_sandbox_bwrap,
+            windows_sandbox_level,
+        } = request;
         let mut env = spec.env;
         if !policy.has_full_network_access() {
             env.insert(
@@ -141,8 +158,12 @@ impl SandboxManager {
             SandboxType::LinuxSeccomp => {
                 let exe = codex_linux_sandbox_exe
                     .ok_or(SandboxTransformError::MissingLinuxSandboxExecutable)?;
-                let mut args =
-                    create_linux_sandbox_command_args(command.clone(), policy, sandbox_policy_cwd);
+                let mut args = create_linux_sandbox_command_args(
+                    command.clone(),
+                    policy,
+                    sandbox_policy_cwd,
+                    use_linux_sandbox_bwrap,
+                );
                 let mut full_command = Vec::with_capacity(1 + args.len());
                 full_command.push(exe.to_string_lossy().to_string());
                 full_command.append(&mut args);

codex-rs/core/src/tools/orchestrator.rs

@@ -8,6 +8,7 @@ retry without sandbox on denial (no re‑approval thanks to caching).
 use crate::error::CodexErr;
 use crate::error::SandboxErr;
 use crate::exec::ExecToolCallOutput;
+use crate::features::Feature;
 use crate::sandboxing::SandboxManager;
 use crate::tools::sandboxing::ApprovalCtx;
 use crate::tools::sandboxing::ExecApprovalRequirement;
@@ -97,12 +98,14 @@ impl ToolOrchestrator {
 
         // Platform-specific flag gating is handled by SandboxManager::select_initial
         // via crate::safety::get_platform_sandbox(..).
+        let use_linux_sandbox_bwrap = turn_ctx.features.enabled(Feature::UseLinuxSandboxBwrap);
         let initial_attempt = SandboxAttempt {
             sandbox: initial_sandbox,
             policy: &turn_ctx.sandbox_policy,
             manager: &self.sandbox,
             sandbox_cwd: &turn_ctx.cwd,
             codex_linux_sandbox_exe: turn_ctx.codex_linux_sandbox_exe.as_ref(),
+            use_linux_sandbox_bwrap,
             windows_sandbox_level: turn_ctx.windows_sandbox_level,
         };
 
@@ -154,6 +157,7 @@ impl ToolOrchestrator {
                     manager: &self.sandbox,
                     sandbox_cwd: &turn_ctx.cwd,
                     codex_linux_sandbox_exe: None,
+                    use_linux_sandbox_bwrap,
                     windows_sandbox_level: turn_ctx.windows_sandbox_level,
                 };
 

codex-rs/core/src/tools/sandboxing.rs

@@ -274,6 +274,7 @@ pub(crate) struct SandboxAttempt<'a> {
     pub(crate) manager: &'a SandboxManager,
     pub(crate) sandbox_cwd: &'a Path,
     pub codex_linux_sandbox_exe: Option<&'a std::path::PathBuf>,
+    pub use_linux_sandbox_bwrap: bool,
     pub windows_sandbox_level: codex_protocol::config_types::WindowsSandboxLevel,
 }
 
@@ -282,14 +283,16 @@ impl<'a> SandboxAttempt<'a> {
         &self,
         spec: CommandSpec,
     ) -> Result<crate::sandboxing::ExecEnv, SandboxTransformError> {
-        self.manager.transform(
-            spec,
-            self.policy,
-            self.sandbox,
-            self.sandbox_cwd,
-            self.codex_linux_sandbox_exe,
-            self.windows_sandbox_level,
-        )
+        self.manager
+            .transform(crate::sandboxing::SandboxTransformRequest {
+                spec,
+                policy: self.policy,
+                sandbox: self.sandbox,
+                sandbox_policy_cwd: self.sandbox_cwd,
+                codex_linux_sandbox_exe: self.codex_linux_sandbox_exe,
+                use_linux_sandbox_bwrap: self.use_linux_sandbox_bwrap,
+                windows_sandbox_level: self.windows_sandbox_level,
+            })
     }
 }
 

codex-rs/core/tests/suite/exec.rs

@@ -44,7 +44,7 @@ async fn run_test_cmd(tmp: TempDir, cmd: Vec<&str>) -> Result<ExecToolCallOutput
 
     let policy = SandboxPolicy::new_read_only_policy();
 
-    process_exec_tool_call(params, &policy, tmp.path(), &None, None).await
+    process_exec_tool_call(params, &policy, tmp.path(), &None, false, None).await
 }
 
 /// Command succeeds with exit code 0 normally