refactor(linux): audit cef.Initialize defaults; drop dead switches and stale workarounds

- Drop dead/no-op code: duplicate ozone-platform setdefault, sw alias,
  wayland-branch's setdefault, redundant GDK_BACKEND set (already in
  _linux_gtk_init), and the WAYLAND_DISPLAY pop (--ozone-platform=x11
  in argv already wins).
- Drop empirically-unnecessary switches: disable-zygote, disable-gpu,
  profile-directory, disable-features=ProfilePicker..., and six noise
  switches (no-first-run, disable-sync, no-startup-window,
  disable-background-networking, password-store, disable-dev-shm-usage).
  Verified across hello_world.py / pysdl2.py / qt.py / native Wayland.
- Remove _linux_setup_profile() and its call site; the profile-picker
  keepalive workaround does not reproduce on current CEF/Chromium even
  with a fresh user-data-dir.
- Make VK_ICD_FILENAMES SwiftShader fallback conditional on no system
  Vulkan ICD being installed (glob /usr/share/vulkan/icd.d/), so
  bare-metal users keep hardware Vulkan instead of being silently
  swapped to software rendering.
- Replace version-tagged comments with current-tense rationale; add
  upstream history blocks for the no-sandbox default (CEF commit
  f5bc72b23 / branch 2357, Ubuntu 23.10 AppArmor regression) and for
  the absent CefCurrentlyOn(TID_UI) assert in CreateBrowserSync.
- Knowledge-Base.md: add troubleshooting entry for the
  "kTransientFailure: CreateCommandBuffer" log line, and an opt-in
  walkthrough for enabling the Chromium sandbox by installing
  chrome-sandbox SUID-root manually.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: linesight

docs/Knowledge-Base.md

@@ -13,10 +13,12 @@ Table of contents:
 * [How to capture Audio and Video in HTML5?](#how-to-capture-audio-and-video-in-html5)
 * [Touch and multi-touch support](#touch-and-multi-touch-support)
 * [Black or white browser screen](#black-or-white-browser-screen)
+* ["kTransientFailure: Failed to send GpuControl.CreateCommandBuffer" on Linux](#ktransientfailure-failed-to-send-gpucontrolcreatecommandbuffer-on-linux)
 * [Python crashes with "Segmentation fault" - how to debug?](#python-crashes-with-segmentation-fault---how-to-debug)
 * [Windows XP support](#windows-xp-support)
 * [Mac 32-bit support](#mac-32-bit-support)
 * [Security](#security)
+  * [Linux: enabling the Chromium sandbox (advanced)](#linux-enabling-the-chromium-sandbox-advanced)
 
 
 ## Notifications about new releases / commits
@@ -264,6 +266,33 @@ appear even after disabling GPU hardware acceleration. This is normal
 because GPU was disabled so WebGL cannot work.
 
 
+## "kTransientFailure: Failed to send GpuControl.CreateCommandBuffer" on Linux
+
+You may see a log line like this during startup, especially on Linux
+VMs and other systems without a working GPU. On VMs the line appears in
+nearly every run; on bare metal with a real GPU it is rarer:
+
+```
+ERROR:gpu/ipc/client/command_buffer_proxy_impl.cc:285] ContextResult::kTransientFailure: Failed to send GpuControl.CreateCommandBuffer.
+```
+
+**This is a Chromium-recoverable transient and can be ignored.** It is
+emitted by the renderer process when it tries to create a GPU command
+buffer before the GPU process has finished binding its IPC endpoint —
+typically a millisecond-scale race during startup, more likely on slow
+disks or when Chromium falls back from real-GL to SwiftShader. The
+compositor retries automatically; pages still render and
+`OnContextInitialized` still fires. The `kTransientFailure` label is
+Chromium's own classification — Chromium expects callers to retry, and
+they do.
+
+If a clean log is more important than hardware acceleration in your
+deployment, you can opt in to disabling the GPU process by passing
+`switches={"disable-gpu": ""}` to `cef.Initialize()`. Do not enable
+`in-process-gpu` to silence this line — it is not stable across
+multiple browser windows.
+
+
 ## Python crashes with "Segmentation fault" - how to debug?
 
 Install gdb:
@@ -347,3 +376,59 @@ A quote by Marshall Greenblatt:
 Reference: [Question on browser security](http://magpcss.org/ceforum/viewtopic.php?f=10&t=10222)
 on the CEF Forum.
 
+
+### Linux: enabling the Chromium sandbox (advanced)
+
+cefpython on Linux passes `--no-sandbox` by default
+(`_linux_apply_initialize_defaults` in `src/window_utils_linux.pyx`).
+
+Reasons for the default:
+1. cefpython does not bundle the SUID-root `chrome-sandbox` helper that
+   Chromium's namespace sandbox needs to bypass AppArmor's
+   `apparmor_restrict_unprivileged_userns=1` (the default on Ubuntu
+   23.10+, Debian 12+, and other modern distros).
+2. Without the helper, Chromium aborts at startup with
+   `FATAL: No usable sandbox!` — every cefpython app would fail to
+   launch out of the box.
+3. The most common cefpython use case is rendering the application's
+   own trusted HTML/JS as a UI surface, where the sandbox provides
+   defense-in-depth rather than primary security.
+
+If your app loads untrusted web content and you want the Chromium
+sandbox enabled, three steps are required:
+
+**1. Install the SUID-root `chrome-sandbox` helper.**
+The binary ships in the CEF binary distribution under
+`Release/chrome-sandbox`. Copy it to a stable path and set it up:
+
+```bash
+sudo cp /path/to/cef_binary_<ver>_linux64/Release/chrome-sandbox \
+        /opt/cef/chrome-sandbox
+sudo chown root:root /opt/cef/chrome-sandbox
+sudo chmod 4755 /opt/cef/chrome-sandbox
+```
+
+**2. Tell Chromium where the helper lives.** Set the
+`CHROME_DEVEL_SANDBOX` environment variable before `cef.Initialize()`:
+
+```python
+import os
+os.environ["CHROME_DEVEL_SANDBOX"] = "/opt/cef/chrome-sandbox"
+```
+
+**3. Remove cefpython's `--no-sandbox` default.** Because
+`_linux_apply_initialize_defaults` sets it via `setdefault`, passing
+`switches={"no-sandbox": ""}` to `cef.Initialize()` does not override
+it. The default has to be deleted at the source (or pop the key from
+your switches dict after init detection). The simplest path is a small
+local patch in `src/window_utils_linux.pyx` that drops the
+`cmd_switches.setdefault("no-sandbox", "")` line.
+
+After all three steps, Chromium subprocesses should launch under the
+namespace sandbox (no `--no-sandbox` in their argv, no FATAL at
+startup). Verify via the GPU process command line:
+
+```bash
+ps -Af | grep "type=gpu" | grep -v "no-sandbox"
+```
+

src/cefpython.pyx

@@ -587,10 +587,6 @@ def Initialize(applicationSettings=None, commandLineSwitches=None, **kwargs):
         # In native Wayland mode, no GTK/X11 connection is needed or wanted.
         if not _g_linux_wayland_mode:
             _linux_gtk_init()
-        # Pre-seed Chrome profile files to prevent the profile-picker keepalive
-        # from blocking OnContextInitialized (Chrome 146).
-        if application_settings.get("cache_path"):
-            _linux_setup_profile(application_settings["cache_path"])
 
     cdef CefRefPtr[CefApp] cefApp = <CefRefPtr[CefApp]?>new CefPythonApp()
 
@@ -726,8 +722,14 @@ def CreateBrowserSync(windowInfo=None,
         raise Exception("Invalid argument: "+kwarg)
 
     Debug("CreateBrowserSync() called")
-    # CEF 146+: CefCurrentlyOn(TID_UI) returns false before MessageLoop starts,
-    # so skip the assert here and let CEF's own internal checks handle it.
+    # No CefCurrentlyOn(TID_UI) assert here.  cefpython defers the real
+    # browser creation until OnContextInitialized fires (see below), so
+    # this function is reached before BrowserThread::UI is fully
+    # established — at which point CefCurrentlyOn() returns false and
+    # logs a WARNING (libcef/common/task_impl.cc).  CEF's own
+    # CefBrowserHost::CreateBrowserSync() runs CONTEXT_STATE_VALID()
+    # plus its own thread checks internally, so a Python-side assert
+    # would only catch the same condition with a worse error message.
 
     # Defer browser creation until OnContextInitialized fires inside MessageLoop.
     # In CEF 123+, browser creation before OnContextInitialized causes

src/window_utils_linux.pyx

@@ -99,7 +99,7 @@ def _linux_get_root_xid():
 
 
 def _linux_apply_initialize_defaults(app_settings, cmd_switches):
-    """Auto-apply Linux CEF 146 defaults that every app needs.
+    """Auto-apply Linux defaults that every cefpython app needs.
 
     X11/XWayland is the default on all Linux systems (even Wayland sessions).
     Native Wayland mode must be requested explicitly by passing
@@ -112,147 +112,99 @@ def _linux_apply_initialize_defaults(app_settings, cmd_switches):
     manager decorates the GTK frame window normally.
 
     Uses setdefault so users can still override any individual entry by passing
-    it explicitly to cef.Initialize(switches={...}).
+    it explicitly to cef.Initialize(switches={...}).  Each setting kept here
+    has been individually retested against current CEF/Chromium — anything
+    that did not regress when removed has been dropped.
     """
     global _g_linux_wayland_mode
     import os as _os
 
-    # Native Wayland mode only when the caller explicitly opts in.
-    _ozone_explicit = cmd_switches.get("ozone-platform", "")
-    _wayland_mode = (_ozone_explicit == "wayland")
-    _g_linux_wayland_mode = _wayland_mode
-
-    if not _wayland_mode:
-        # X11/Xwayland mode: force GDK and Chrome onto X11.
-        # Must be set before gtk_init() so GDK opens an X11/Xwayland display.
-        _os.environ.setdefault("GDK_BACKEND", "x11")
-        # Remove WAYLAND_DISPLAY so Chrome's Ozone platform selection picks X11.
-        _os.environ.pop("WAYLAND_DISPLAY", None)
+    # Native Wayland mode only when the caller explicitly opts in via
+    # switches={"ozone-platform": "wayland"}.  Otherwise default to X11/Xwayland.
+    _g_linux_wayland_mode = (cmd_switches.get("ozone-platform") == "wayland")
+
+    if not _g_linux_wayland_mode:
+        # X11/Xwayland mode: force Chrome's Ozone backend to X11.  This is
+        # the *only* thing keeping Chromium off the Wayland display on a
+        # Wayland session — we cannot embed a Wayland xdg_surface inside
+        # the GTK X11 window we create in _linux_create_toplevel().
+        # GDK_BACKEND=x11 is set separately in _linux_gtk_init() before
+        # gtk_init().
         cmd_switches.setdefault("ozone-platform", "x11")
-    else:
-        # Native Wayland mode: use the Ozone Wayland backend.
-        # Keep WAYLAND_DISPLAY so Chrome connects to the Wayland compositor.
-        cmd_switches.setdefault("ozone-platform", "wayland")
-
-    # Point the Vulkan loader at the SwiftShader ICD shipped with CEF.
-    import cefpython3 as _cef3_pkg
-    _cef3_dir = _os.path.dirname(_cef3_pkg.__file__)
-    _vk_icd = _os.path.join(_cef3_dir, "vk_swiftshader_icd.json")
-    if _os.path.exists(_vk_icd):
-        _os.environ.setdefault("VK_ICD_FILENAMES", _vk_icd)
-
-    # CEF 146 on Ozone X11 requires a running GLib main loop for
-    # OnContextInitialized to fire.  external_message_pump integrates
-    # CefDoMessageLoopWork() as a GLib source.
+    # Native Wayland branch: "ozone-platform" is already in cmd_switches
+    # (the only way to reach this branch), so nothing to do here.
+
+    # Vulkan ICD fallback for systems with no system-installed driver.
+    #
+    # On systems with no Vulkan ICD (typical for VMs and minimal containers),
+    # Chromium's GPU process fails its Vulkan probe and the renderer logs a
+    # transient
+    #   ContextResult::kTransientFailure: Failed to send
+    #     GpuControl.CreateCommandBuffer
+    # before falling back to software rendering.  Pointing VK_ICD_FILENAMES
+    # at the SwiftShader manifest bundled with CEF makes the probe succeed
+    # immediately and silences the line.
+    #
+    # Only apply the fallback when no system ICD is present in the standard
+    # loader search paths — overriding a working Mesa/NVIDIA/AMD ICD with
+    # SwiftShader would force software rendering for no reason on real GPUs.
+    # Honors a pre-set VK_ICD_FILENAMES (setdefault) so users can override.
+    import glob as _glob
+    _system_icds = (_glob.glob("/usr/share/vulkan/icd.d/*.json") +
+                    _glob.glob("/etc/vulkan/icd.d/*.json") +
+                    _glob.glob("/usr/local/share/vulkan/icd.d/*.json"))
+    if not _system_icds:
+        import cefpython3 as _cef3_pkg
+        _cef3_dir = _os.path.dirname(_cef3_pkg.__file__)
+        _vk_icd = _os.path.join(_cef3_dir, "vk_swiftshader_icd.json")
+        if _os.path.exists(_vk_icd):
+            _os.environ.setdefault("VK_ICD_FILENAMES", _vk_icd)
+
+    # _linux_message_loop / _linux_wayland_message_loop drive CEF by calling
+    # CefDoMessageLoopWork() from a GLib timer.  external_message_pump tells
+    # CEF not to run its own internal loop, so the two don't conflict.
     app_settings.setdefault("external_message_pump", True)
 
-    # Allow per-browser opt-in to off-screen rendering.  This is needed so
-    # that JS-created popup browsers (window.open) can be closed without
-    # dispatching GLib/X11 events: off-screen browsers are destroyed
-    # immediately when DoClose returns False (no delete_event to parent).
+    # Allow per-browser opt-in to off-screen rendering.  Required by examples
+    # that pass WindowInfo.SetAsOffscreen() (e.g. pysdl2.py) and by JS-created
+    # popup browsers, which are destroyed immediately when DoClose returns
+    # False — no delete_event would be dispatched on a windowed popup.
     app_settings.setdefault("windowless_rendering_enabled", True)
 
-    # Chromium switches required for stable embedded operation on CEF 146.
-    sw = cmd_switches
-    # Ozone platform: already set above (wayland or x11); setdefault is a no-op
-    # if the user already passed ozone-platform explicitly.
-    sw.setdefault("ozone-platform", "x11")
-    # Bypass Zygote to avoid stack-smash crash from --change-stack-guard-on-fork.
-    sw.setdefault("disable-zygote", "")
-    # Belt-and-suspenders sandbox suppression.
-    sw.setdefault("no-sandbox", "")
-    # /dev/shm may be too small in VMs and containers.
-    sw.setdefault("disable-dev-shm-usage", "")
-    # Suppress GNOME Keyring unlock prompt.
-    sw.setdefault("password-store", "basic")
-    # Skip 3× GPU subprocess crash cycle; go straight to software rendering.
-    sw.setdefault("disable-gpu", "")
-    # Startup / sync / background noise suppression.
-    sw.setdefault("no-first-run", "")
-    sw.setdefault("disable-sync", "")
-    sw.setdefault("no-startup-window", "")
-    sw.setdefault("disable-background-networking", "")
-    # Profile subdirectory — prevents ShouldShowProfilePickerAtLaunch() from
-    # returning True and adding a kProfileCreationFlow keepalive that would
-    # permanently block OnContextInitialized in embedded apps.
-    sw.setdefault("profile-directory", "Default")
-    # Disable UI features that add their own keepalives or block init.
-    if "disable-features" not in sw:
-        sw["disable-features"] = (
-            "WebGPU,"
-            "ProfilePicker,"
-            "ProfilePickerIPH,"
-            "ForYouFre,"
-            "SyncPromoFRE,"
-            "ChromeSigninIphExperiment,"
-            "ChromeWhatsNewUI,"
-            "DefaultBrowserPrompt,"
-            "ProfileManagementFlowController"
-        )
-
-
-def _linux_setup_profile(cache_path):
-    """Pre-create Chrome profile files to skip profile-picker keepalive.
-
-    Chrome 146 adds a kProfileCreationFlow keepalive when it creates a new
-    profile from scratch and only removes it after the wizard UI completes.
-    Writing seed files before cef.Initialize() makes Chrome treat the
-    profile as already configured, skipping the keepalive entirely.
-    """
-    import os as _os, json as _json, glob as _glob
-
-    default_dir = _os.path.join(cache_path, "Default")
-    _os.makedirs(default_dir, exist_ok=True)
-
-    for _pat in ("Singleton*", "*.lock", "LOCK"):
-        for _f in _glob.glob(_os.path.join(cache_path, _pat)):
-            try: _os.unlink(_f)
-            except OSError: pass
-        for _f in _glob.glob(_os.path.join(default_dir, _pat)):
-            try: _os.unlink(_f)
-            except OSError: pass
-
-    first_run = _os.path.join(cache_path, "First Run")
-    if not _os.path.exists(first_run):
-        open(first_run, "w").close()
-
-    local_state = _os.path.join(cache_path, "Local State")
-    if not _os.path.exists(local_state):
-        with open(local_state, "w") as _f:
-            _json.dump({"profile": {
-                "info_cache": {"Default": {
-                    "active_time": 1704067200.0,
-                    "avatar_icon": "chrome://theme/IDR_PROFILE_AVATAR_0",
-                    "is_using_default_avatar": True,
-                    "is_using_default_name": True,
-                    "is_new_profile": False,
-                    "managed_user_id": "",
-                    "name": "Default",
-                }},
-                "last_used": "Default",
-                "profiles_created": 1,
-            }}, _f)
-
-    prefs = _os.path.join(default_dir, "Preferences")
-    if not _os.path.exists(prefs):
-        with open(prefs, "w") as _f:
-            _json.dump({
-                "profile": {
-                    "creation_time": "13328563200000000",
-                    "is_using_default_name": True,
-                    "name": "Default",
-                },
-                "browser": {"has_seen_welcome_page": True},
-                "privacy_sandbox": {
-                    "m1.consent_decision_made": True,
-                    "m1.notice_acknowledged": True,
-                    "m1.restricted_notice_acknowledged": True,
-                    "consent_decision_made": True,
-                    "notice_acknowledged": True,
-                    "first_run_consent_required": False,
-                    "first_run_setup_complete": True,
-                },
-            }, _f)
+    # Disable Chromium's Linux sandbox.
+    #
+    # History (so readers don't think this is CEF-146-specific):
+    #   * CEF defaulted sandbox-OFF until 2013-11-15 (commit f5bc72b23,
+    #     SVN trunk@1518, "Add sandbox support, issue #524").  The
+    #     commit message stated explicitly: "Linux: For binary
+    #     distributions a new chrome-sandbox executable with SUID
+    #     permissions must be placed next to the CEF executable."
+    #   * The earliest release branch carrying that change is branch
+    #     2357 (created 2015-08-21, ~Chromium 44).  From 2357 onward,
+    #     every CEF Linux build defaults sandbox-ON and refuses to start
+    #     unless either a SUID-root chrome-sandbox helper is installed
+    #     or this --no-sandbox switch is passed.
+    #   * For ~2017-2023, most distros enabled
+    #     kernel.unprivileged_userns_clone=1, so Chromium's namespace
+    #     sandbox could substitute for the SUID helper and many
+    #     embedders quietly avoided either step.
+    #   * Ubuntu 23.10 (Oct 2023) set
+    #     kernel.apparmor_restrict_unprivileged_userns=1 by default;
+    #     Debian 12 followed.  This re-broke the namespace-only path:
+    #     without the SUID helper Chromium aborts with
+    #     FATAL: No usable sandbox!  (zygote_host_impl_linux.cc:128)
+    #   * cefpython is distributed as a pip wheel, and pip cannot
+    #     chown root + chmod 4755 a binary (it runs as the user, not
+    #     root, and has no postinst hook).  Distro packages such as
+    #     google-chrome and chromium handle this in their .deb/.rpm
+    #     postinst scripts; cefpython has no equivalent install path.
+    #
+    # Effect of this line: cefpython works out of the box on every
+    # Linux distro at the cost of running Chromium subprocesses
+    # without the chromium namespace sandbox (seccomp-bpf still
+    # applies).  See docs/Knowledge-Base.md "Linux: enabling the
+    # Chromium sandbox" for the manual opt-in path.
+    cmd_switches.setdefault("no-sandbox", "")
 
 
 def _linux_create_toplevel(title, width=_LINUX_DEFAULT_WIDTH, height=_LINUX_DEFAULT_HEIGHT):