Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

fix(desktop): trust the OS certificate store on the Linux desktop (#9218) (#9240)

yzxcj797abf4d33d54f8
diff --git a/studio/backend/tests/test_native_tls.py b/studio/backend/tests/test_native_tls.py
index 1cd848627ff..c053dc39929 100644
--- a/studio/backend/tests/test_native_tls.py
+++ b/studio/backend/tests/test_native_tls.py
@@ -28,11 +28,16 @@ def _reset_activation(monkeypatch):
import os
monkeypatch.setattr(native_tls, "_activated", False)
- for key in ("UNSLOTH_STUDIO_NATIVE_TLS", "UV_SYSTEM_CERTS", "UV_NATIVE_TLS"):
+ for key in (
+ "UNSLOTH_STUDIO_NATIVE_TLS",
+ "UNSLOTH_STUDIO_DESKTOP_OWNER_KIND",
+ "UV_SYSTEM_CERTS",
+ "UV_NATIVE_TLS",
+ ):
monkeypatch.delenv(key, raising = False)
yield
# monkeypatch cannot undo vars that were absent, so drop what setdefault added.
- for key in ("UV_SYSTEM_CERTS", "UV_NATIVE_TLS"):
+ for key in ("UNSLOTH_STUDIO_NATIVE_TLS", "UV_SYSTEM_CERTS", "UV_NATIVE_TLS"):
os.environ.pop(key, None)
@@ -154,3 +159,156 @@ def test_activate_fails_open_when_injection_raises(monkeypatch):
monkeypatch.setitem(sys.modules, "truststore", fake)
assert native_tls.activate_native_tls() is False
+
+
+ ("platform", "desktop_kind", "expected"),
+ [
+ ("linux", "tauri", True), # .deb/AppImage desktop: icon launch, no shell profile
+ ("linux", "", False), # headless `unsloth studio`: opt-in stays
+ ("linux", "other", False), # unknown owner kind: not the Tauri handshake
+ ],
+)
+def test_linux_desktop_owner_flips_native_tls_default(
+ monkeypatch, platform, desktop_kind, expected
+):
+ monkeypatch.delenv("UNSLOTH_STUDIO_NATIVE_TLS", raising = False)
+ monkeypatch.setattr(sys, "platform", platform)
+ monkeypatch.setenv("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", desktop_kind)
+ assert native_tls.native_tls_enabled() is expected
+
+
+def test_linux_explicit_opt_out_wins_over_desktop_owner(monkeypatch):
+ monkeypatch.setattr(sys, "platform", "linux")
+ monkeypatch.setenv("UNSLOTH_STUDIO_NATIVE_TLS", "0")
+ monkeypatch.setenv("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", "tauri")
+ assert native_tls.native_tls_enabled() is False
+
+
+def test_activate_spells_the_resolved_decision_into_the_env(monkeypatch):
+ import os
+
+ monkeypatch.setattr(sys, "platform", "linux")
+ monkeypatch.setenv("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", "tauri")
+ _fake_truststore(monkeypatch)
+
+ assert native_tls.activate_native_tls() is True
+ # The probe children only see the flag: main.py pops the marker before they spawn.
+ assert os.environ["UNSLOTH_STUDIO_NATIVE_TLS"] == "1"
+
+
[email protected]("inherited", ["", "on"])
+def test_activate_overwrites_an_unrecognized_inherited_flag(monkeypatch, inherited):
+ import os
+
+ # An unrecognized value resolves to the default here but reads as off in a
+ # child, so setdefault would leave the probes verifying against certifi.
+ monkeypatch.setattr(sys, "platform", "linux")
+ monkeypatch.setenv("UNSLOTH_STUDIO_NATIVE_TLS", inherited)
+ monkeypatch.setenv("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", "tauri")
+ _fake_truststore(monkeypatch)
+
+ assert native_tls.activate_native_tls() is True
+ assert os.environ["UNSLOTH_STUDIO_NATIVE_TLS"] == "1"
+
+
+def test_desktop_default_leaves_uv_on_its_bundled_roots(monkeypatch):
+ import os
+
+ # uv's system certs replace its webpki roots rather than adding to them, so an
+ # unusable SSL_CERT_FILE it ignores today would become a hard failure, and
+ # core/training/worker.py runs uv with no pip fallback.
+ monkeypatch.setattr(sys, "platform", "linux")
+ monkeypatch.setenv("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", "tauri")
+ _fake_truststore(monkeypatch)
+
+ assert native_tls.activate_native_tls() is True
+ assert os.environ["UV_SYSTEM_CERTS"] == "0"
+ assert os.environ["UV_NATIVE_TLS"] == "0"
+
+
+def test_linux_explicit_opt_in_still_moves_uv(monkeypatch):
+ import os
+
+ monkeypatch.setattr(sys, "platform", "linux")
+ monkeypatch.setenv("UNSLOTH_STUDIO_NATIVE_TLS", "1")
+ _fake_truststore(monkeypatch)
+
+ assert native_tls.activate_native_tls() is True
+ assert os.environ["UV_SYSTEM_CERTS"] == "1"
+
+
+def test_a_worker_inherits_the_uv_answer_it_cannot_re_derive(monkeypatch):
+ import os
+
+ # The worker's env is the parent's: the flag normalized to "1" and the marker
+ # popped, so re-deriving would read as an explicit opt-in and flip uv anyway.
+ monkeypatch.setattr(sys, "platform", "linux")
+ monkeypatch.setenv("UNSLOTH_STUDIO_NATIVE_TLS", "1")
+ monkeypatch.setenv("UV_SYSTEM_CERTS", "0")
+ _fake_truststore(monkeypatch)
+
+ assert native_tls.activate_native_tls() is True
+ assert os.environ["UV_SYSTEM_CERTS"] == "0"
+ assert os.environ["UV_NATIVE_TLS"] == "0"
+
+
+def test_desktop_default_keeps_an_explicit_uv_opt_in(monkeypatch):
+ import os
+
+ monkeypatch.setattr(sys, "platform", "linux")
+ monkeypatch.setenv("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", "tauri")
+ monkeypatch.setenv("UV_NATIVE_TLS", "1")
+ _fake_truststore(monkeypatch)
+
+ assert native_tls.activate_native_tls() is True
+ assert os.environ["UV_SYSTEM_CERTS"] == "1"
+
+
+def test_disabled_activation_leaves_the_flag_env_absent(monkeypatch):
+ import os
+
+ monkeypatch.setattr(sys, "platform", "linux")
+ monkeypatch.setenv("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", "")
+ _fake_truststore(monkeypatch)
+
+ assert native_tls.activate_native_tls() is False
+ assert "UNSLOTH_STUDIO_NATIVE_TLS" not in os.environ
+
+
+def _run_inline_gate(
+ monkeypatch,
+ platform,
+ owner_kind = None,
+ flag = None,
+):
+ import os
+
+ calls = _fake_truststore(monkeypatch)
+ if owner_kind is not None:
+ monkeypatch.setenv("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", owner_kind)
+ if flag is not None:
+ monkeypatch.setenv("UNSLOTH_STUDIO_NATIVE_TLS", flag)
+ # The gate reads only sys.platform and sys.path off the handed-in `sys`;
+ # `import truststore` still finds _fake_truststore's stub in the real sys.modules.
+ child_sys = _types.SimpleNamespace(platform = platform, path = [])
+ namespace = {"os": os, "sys": child_sys, "_TRUSTSTORE_VENDOR": "/vendor"}
+ exec(native_tls.inline_gate_source(), namespace)
+ return calls
+
+
+def test_inline_gate_injects_for_linux_desktop_child(monkeypatch):
+ assert _run_inline_gate(monkeypatch, "linux", owner_kind = "tauri") == ["inject"]
+
+
+def test_inline_gate_skips_headless_linux_child(monkeypatch):
+ assert _run_inline_gate(monkeypatch, "linux", owner_kind = "") == []
+
+
+def test_inline_gate_opt_out_wins_over_desktop_owner(monkeypatch):
+ assert _run_inline_gate(monkeypatch, "linux", owner_kind = "tauri", flag = "0") == []
+
+
+def test_inline_gate_keeps_platform_and_opt_in_defaults(monkeypatch):
+ assert _run_inline_gate(monkeypatch, "darwin", owner_kind = "") == ["inject"]
+ assert _run_inline_gate(monkeypatch, "linux", owner_kind = "", flag = "1") == ["inject"]
diff --git a/studio/backend/utils/native_tls.py b/studio/backend/utils/native_tls.py
index d92693ea211..be61dfe4c68 100644
--- a/studio/backend/utils/native_tls.py
+++ b/studio/backend/utils/native_tls.py
@@ -21,12 +21,15 @@ Unsloth user gains a package for a proxy they do not have; see the README there.
Every consumer appends that directory to ``sys.path`` and imports the top-level
name, which keeps a truststore the user installed themselves in front of ours.
-Defaults mirror install.sh: on for macOS and Windows, opt-in on Linux via
-``UNSLOTH_STUDIO_NATIVE_TLS=1`` (distro OpenSSL configurations vary), opt-out
-anywhere with ``0``. Explicit ``SSL_CERT_FILE``/``REQUESTS_CA_BUNDLE`` keep
-working, but become additive rather than exclusive, since truststore keeps the
-OS anchors alongside them; ``0`` is the way back to a bundle being the only
-trust root.
+On by default for macOS and Windows, and on Linux only for the desktop app's own
+backend (#9218); a headless ``unsloth studio`` keeps the
+``UNSLOTH_STUDIO_NATIVE_TLS=1`` opt-in, since distro OpenSSL configurations vary
+and an operator in a shell can export it. ``0`` opts out anywhere.
+
+``SSL_CERT_FILE``/``REQUESTS_CA_BUNDLE`` stay exclusive, not additive: httpx
+builds its context from ``SSL_CERT_FILE`` alone, so pointing it at a private CA
+still costs you the public roots and the Hub with them. Install the CA in the OS
+store instead, which is what this module then reaches.
Client side only: the injected class verifies a peer chain on every handshake,
so an ``SSLContext`` built after activation cannot serve TLS. Unsloth serves
@@ -43,6 +46,7 @@ import sys
from pathlib import Path
_NATIVE_TLS_ENV = "UNSLOTH_STUDIO_NATIVE_TLS"
+_DESKTOP_OWNER_KIND_ENV = "UNSLOTH_STUDIO_DESKTOP_OWNER_KIND"
_DEFAULT_ON_PLATFORMS = ("darwin", "win32")
_TRUTHY = ("1", "true", "yes")
_FALSEY = ("0", "false", "no")
@@ -56,22 +60,60 @@ _activated = False
def native_tls_enabled() -> bool:
- """Resolve ``UNSLOTH_STUDIO_NATIVE_TLS`` against the platform default."""
+ """Resolve ``UNSLOTH_STUDIO_NATIVE_TLS`` against the platform default.
+
+ Linux is on only for the desktop's own backend: a .deb/AppImage launched
+ from an icon reads no shell profile, so the opt-in is unreachable there
+ (#9218), while a headless server has an operator who can export it.
+ """
flag = os.environ.get(_NATIVE_TLS_ENV, "").strip().lower()
if flag in _TRUTHY:
return True
if flag in _FALSEY:
return False
+ if sys.platform in _DEFAULT_ON_PLATFORMS:
+ return True
+ if sys.platform.startswith("linux"):
+ return _desktop_owned_process()
+ return False
+
+
+def _desktop_owned_process() -> bool:
+ """True when this backend belongs to the Tauri desktop app.
+
+ Read, never popped: main._load_desktop_owner owns this marker and pops it,
+ but activation runs first (main.py:185, ahead of the loader), so reading it
+ here cannot steal it.
+ """
+ return os.environ.get(_DESKTOP_OWNER_KIND_ENV, "") == "tauri"
+
+
+def _uv_system_certs_wanted() -> bool:
+ """Whether uv should move onto the OS store along with this process.
+
+ True for an explicit opt-in and for the platforms install.sh already covers,
+ False when only the desktop-owner default turned native TLS on. truststore
+ ADDS the OS anchors to the ones a caller loaded, but uv's system certs
+ REPLACE its bundled webpki roots, so an unusable SSL_CERT_FILE that uv
+ happily ignores today becomes "No CA certificates were loaded from the
+ system" instead, and core/training/worker.py runs uv with no pip fallback.
+ """
+ if os.environ.get(_NATIVE_TLS_ENV, "").strip().lower() in _TRUTHY:
+ return True
return sys.platform in _DEFAULT_ON_PLATFORMS
# Children that cannot import this module carry the gate as source, generated from the same constants so it cannot drift
-# from native_tls_enabled().
+# from native_tls_enabled(). The Linux desktop-owner clause also applies to children launched directly by the desktop.
# The children that cannot import it are the `python -c` probes and prebuilt_core.py, and each supplies os, sys and
# _TRUSTSTORE_VENDOR itself.
_INLINE_GATE = """\
_flag = os.environ.get({env!r}, '').strip().lower()
-if _flag in {truthy!r} or (_flag not in {falsey!r} and sys.platform in {platforms!r}):
+_owned = os.environ.get({owner_env!r}, '') == 'tauri'
+if _flag in {truthy!r} or (
+ _flag not in {falsey!r}
+ and (sys.platform in {platforms!r} or (sys.platform.startswith('linux') and _owned))
+):
try:
if _TRUSTSTORE_VENDOR not in sys.path:
sys.path.append(_TRUSTSTORE_VENDOR)
@@ -79,7 +121,7 @@ if _flag in {truthy!r} or (_flag not in {falsey!r} and sys.platform in {platform
truststore.inject_into_ssl()
except Exception:
pass
-del _flag
+del _flag, _owned
"""
@@ -95,6 +137,7 @@ def inline_gate_source() -> str:
"""
return _INLINE_GATE.format(
env = _NATIVE_TLS_ENV,
+ owner_env = _DESKTOP_OWNER_KIND_ENV,
truthy = _TRUTHY,
falsey = _FALSEY,
platforms = _DEFAULT_ON_PLATFORMS,
@@ -112,9 +155,17 @@ def activate_native_tls() -> bool:
return True
if not native_tls_enabled():
return False
+ # main.py pops the desktop-owner marker, so children re-resolve from the flag
+ # alone: spell the decision back into the env, the way the UV_* pair below is.
+ # Assign, not setdefault: an opt-out already returned above, so the only value
+ # left to preserve would be an unrecognized one, which reads as off in a child.
+ uv_default = "1" if _uv_system_certs_wanted() else "0"
+ os.environ[_NATIVE_TLS_ENV] = "1"
# uv's rustls ignores in-process injection (uv >= 0.11 reads UV_SYSTEM_CERTS, older reads UV_NATIVE_TLS). Mirror one
# value across both: uv takes either as an opt-in, so an opt-out in one spelling must carry to the other.
- os.environ.setdefault("UV_SYSTEM_CERTS", os.environ.get("UV_NATIVE_TLS", "1"))
+ # Written even when the answer is "0", because a worker sees the normalized flag above and not the desktop marker,
+ # so an absent value would have it derive an opt-in this process declined.
+ os.environ.setdefault("UV_SYSTEM_CERTS", os.environ.get("UV_NATIVE_TLS", uv_default))
os.environ.setdefault("UV_NATIVE_TLS", os.environ["UV_SYSTEM_CERTS"])
# append, not insert(0): a user-installed truststore must win over the vendored copy.
if _VENDOR_DIR not in sys.path:
diff --git a/studio/prebuilt_core.py b/studio/prebuilt_core.py
index 14a2f412deb..4db8a6d022f 100644
--- a/studio/prebuilt_core.py
+++ b/studio/prebuilt_core.py
@@ -61,8 +61,10 @@ except ImportError:
# test_native_tls_entrypoints.py asserts the paste still matches, by AST.
_TRUSTSTORE_VENDOR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "backend", "vendor")
_flag = os.environ.get("UNSLOTH_STUDIO_NATIVE_TLS", "").strip().lower()
+_owned = os.environ.get("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", "") == "tauri"
if _flag in ("1", "true", "yes") or (
- _flag not in ("0", "false", "no") and sys.platform in ("darwin", "win32")
+ _flag not in ("0", "false", "no")
+ and (sys.platform in ("darwin", "win32") or (sys.platform.startswith("linux") and _owned))
):
try:
if _TRUSTSTORE_VENDOR not in sys.path:
@@ -71,7 +73,7 @@ if _flag in ("1", "true", "yes") or (
truststore.inject_into_ssl()
except Exception:
pass
-del _flag
+del _flag, _owned
class PrebuiltFallback(RuntimeError):