Add Linux Bubblewrap sandbox

- Use `bwrap` to translate shared sandbox rules into rootless
  namespace execution.
- Gate the backend behind `HOMEBREW_SANDBOX_LINUX` while the Linux
  policy is still experimental.
- Keep macOS on its existing `sandbox-exec` path while Linux uses shared
  executable lookup for `bwrap`.
- Auto-install `bubblewrap` from `homebrew/core` when the sandbox is
  enabled and no system or usable brewed binary is found.
- Prefer a usable system `bwrap` from `ORIGINAL_PATHS` over a brewed
  one so distribution-provided binaries are used when available.
- Find brewed `bwrap` from `HOMEBREW_ORIGINAL_BREW_FILE` so integration
  subprocesses still use the Linux sandbox.
- Preserve `Sandbox#run`'s tmpdir cwd inside the `bwrap` namespace and
  suppress Linux PTY thread warnings after sandboxed children exit.
- Expose formula, Homebrew library and Linux runtime paths as read-only
  binds so sandboxed source builds can run with vendored Ruby.
- Keep synthetic test formula installs off the API so sandbox CI does
  not require network during local formula setup.
- Avoid creating optional prefix `var` directories just to configure a
  test sandbox and remove empty Linux bind placeholders after runs.
- Require a working rootless `bwrap` on GitHub Actions and install the
  system `bubblewrap` package before Linux tests run.

Author: MikeMcQuaid

.github/workflows/tests.yml

@@ -274,6 +274,21 @@ jobs:
           workflow-key: tests-tests-macos
           uninstall: true
 
+      - name: Install brew tests Linux dependencies
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends bubblewrap
+          # Allow unprivileged user namespace cloning; rootless `bwrap` needs this
+          # to create its user namespace.
+          sudo sysctl -w kernel.unprivileged_userns_clone=1
+          # Ensure the runner can allocate user namespaces instead of hitting a
+          # per-user namespace limit.
+          sudo sysctl -w user.max_user_namespaces=28633
+          # Ubuntu runners may additionally restrict unprivileged user namespaces
+          # through AppArmor; older kernels may not expose this sysctl.
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 || true
+
         # brew tests doesn't like world writable directories
       - name: Cleanup permissions
         if: runner.os == 'Linux'
@@ -286,6 +301,7 @@ jobs:
           HOMEBREW_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # These cannot be queried at the macOS level on GitHub Actions.
           HOMEBREW_LANGUAGES: en-GB
+          HOMEBREW_SANDBOX_LINUX: 1
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Get RSpec JUnit XML filenames
@@ -335,6 +351,7 @@ jobs:
           - name: test-bot (macOS arm64)
             runs-on: macos-26
     env:
+      HOMEBREW_SANDBOX_LINUX: 1
       HOMEBREW_TEST_BOT_ANALYTICS: 1
     steps:
       - name: Install Homebrew and Homebrew's dependencies
@@ -345,6 +362,7 @@ jobs:
           # Slimmed down version from the Homebrew Dockerfile
           apt-get update
           apt-get install -y --no-install-recommends \
+            bubblewrap \
             bzip2 \
             ca-certificates \
             curl \

Dockerfile

@@ -29,6 +29,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
   && retry apt-get update --error-on=any \
   && apt-get install -y --no-install-recommends \
   acl \
+  bubblewrap \
   bzip2 \
   ca-certificates \
   curl \

Library/Homebrew/build.rb

@@ -260,6 +260,11 @@ def normalize_pod2man_outputs!(formula)
   # We need to allow formulae from paths here due to how we pass them through.
   ENV["HOMEBREW_INTERNAL_ALLOW_PACKAGES_FROM_PATHS"] = "1"
 
+  formula_path = ARGV.first
+  # `build.rb` is handed a concrete formula file; keep reparsing from falling
+  # back to the API inside the Linux sandbox.
+  ENV["HOMEBREW_NO_INSTALL_FROM_API"] = "1" if formula_path&.end_with?(".rb")
+
   args = Homebrew::Cmd::InstallCmd.new.args
   Context.current = args.context
 
@@ -268,7 +273,6 @@ def normalize_pod2man_outputs!(formula)
 
   trap("INT", old_trap)
 
-  formula_path = ARGV.first
   if formula_path&.end_with?(".json")
     raise "build.rb received an API JSON file as the formula path: #{formula_path}. " \
           "This usually means the formula source was not downloaded from the API. " \

Library/Homebrew/dev-cmd/test.rb

@@ -37,6 +37,7 @@ def run
         require "formula_free_port"
         require "utils/fork"
 
+        optional_prefix_var_dirs = %w[var/cache var/log var/run]
         args.named.to_resolved_formulae.each do |f|
           # Cannot test uninstalled formulae
           unless f.latest_version_installed?
@@ -81,17 +82,18 @@ def run
 
             exec_args << "--HEAD" if f.head?
 
+            Sandbox.ensure_sandbox_installed!
             if Sandbox.available?
               sandbox = Sandbox.new
               f.logs.mkpath
               sandbox.record_log(f.logs/"test.sandbox.log")
               sandbox.allow_write_temp_and_cache
               sandbox.allow_write_log(f)
               sandbox.allow_write_xcode
-              sandbox.allow_write_path(HOMEBREW_PREFIX/"var/cache")
               sandbox.allow_write_path(HOMEBREW_PREFIX/"var/homebrew/locks")
-              sandbox.allow_write_path(HOMEBREW_PREFIX/"var/log")
-              sandbox.allow_write_path(HOMEBREW_PREFIX/"var/run")
+              optional_prefix_var_dirs.each do |dir|
+                sandbox.allow_write_path_if_exists HOMEBREW_PREFIX/dir
+              end
               sandbox.deny_all_network unless f.class.network_access_allowed?(:test)
               sandbox.run(*exec_args)
             else

Library/Homebrew/dev-cmd/tests.rb

@@ -66,6 +66,8 @@ def run
           # `return false`.
           require "extend/os/dev-cmd/tests"
 
+          check_test_environment!
+
           parallel = !args.no_parallel?
 
           only = args.only
@@ -210,6 +212,9 @@ def non_linux_bundle_args(bundle_args)
         bundle_args << "--tag" << "~needs_linux" << "--tag" << "~needs_systemd"
       end
 
+      sig { void }
+      def check_test_environment!; end
+
       sig { params(files: T::Array[String]).returns(T::Array[String]) }
       def os_files(files)
         # for generic tests, remove macOS or Linux specific files
@@ -256,6 +261,7 @@ def setup_environment!
           HOMEBREW_GITHUB_API_TOKEN
           HOMEBREW_CACHE
           HOMEBREW_LOGS
+          HOMEBREW_SANDBOX_LINUX
           HOMEBREW_TEMP
         ]
         allowed_test_env << "HOMEBREW_USE_RUBY_FROM_PATH" if Homebrew::EnvConfig.developer?

Library/Homebrew/env_config.rb

@@ -486,6 +486,10 @@ module EnvConfig
         description: "If set, use Pry for the `brew irb` command.",
         boolean:     true,
       },
+      HOMEBREW_SANDBOX_LINUX:                    {
+        description: "If set, use the `bwrap`(1) sandbox for formula installation and testing on Linux.",
+        boolean:     true,
+      },
       HOMEBREW_SBOM:                             {
         # odeprecated: edit in 5.2.0
         description: "If set, Homebrew will write SBOM files and run SBOM-related installation logic. " \

Library/Homebrew/extend/os/linux/dev-cmd/tests.rb

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require "utils/github/actions"
+
 module OS
   module Linux
     module DevCmd
@@ -20,6 +22,19 @@ def os_bundle_args(bundle_args)
         def os_files(files)
           non_macos_files(files)
         end
+
+        sig { void }
+        def check_test_environment!
+          super
+          return unless GitHub::Actions.env_set?
+
+          require "sandbox"
+          with_env(HOMEBREW_SANDBOX_LINUX: "1") do
+            return if ::Sandbox.available?
+
+            raise UsageError, "GitHub Actions Linux tests require a working rootless Bubblewrap sandbox."
+          end
+        end
       end
     end
   end