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.

19.9 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Detects OS isolation support and setup needs from Settings; never runs a privileged command."""

from __future__ import annotations

from dataclasses import asdict, dataclass
import os
import re
import shlex
import shutil
import subprocess
import sys
import threading
import time
from pathlib import Path

LINUX_INSTALL = "linux-install"
WINDOWS_SETUP = "windows-setup"
WINDOWS_RUNTIME = "windows-runtime"
OPERATIONS = (LINUX_INSTALL, WINDOWS_SETUP, WINDOWS_RUNTIME)

_APPARMOR_SYSCTL = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns"
_APPARMOR_PROFILE = "/etc/apparmor.d/bwrap-userns-restrict"
_APPARMOR_EXTRA_PROFILE = "/usr/share/apparmor/extra-profiles/bwrap-userns-restrict"
_CACHE_SECONDS = 5.0
# The elevation check is logged (auth.log) and may mail root: ask rarely.
_ELEVATION_CACHE_SECONDS = 600.0
SYSTEM_BIN_DIRS = ("/usr/sbin", "/usr/bin", "/sbin", "/bin")
ELEVATED_ENV = {
    "PATH": ":".join(SYSTEM_BIN_DIRS),
    "LANG": "C",
    "LC_ALL": "C",
    "DEBIAN_FRONTEND": "noninteractive",
}

# Must match os_sandbox's _BWRAP_INSTALL_COMMANDS / _BWRAP_APPARMOR_FIX (and install.sh).
_APT_INSTALL = ("apt-get", "-o", "DPkg::Lock::Timeout=120", "install", "-y")
_INSTALL_STEPS = {
    "apt-get": (("apt-get", "update"), (*_APT_INSTALL, "bubblewrap")),
    "dnf": (("dnf", "install", "-y", "bubblewrap"),),
    "pacman": (("pacman", "-S", "--needed", "--noconfirm", "bubblewrap"),),
    "zypper": (("zypper", "--non-interactive", "install", "bubblewrap"),),
    "apk": (("apk", "add", "bubblewrap"),),
}


def _apparmor_load() -> tuple[str, ...]:
    return ("apparmor_parser", "-r", _APPARMOR_PROFILE)


def _apparmor_steps() -> tuple[tuple[str, ...], ...]:
    return (
        (*_APT_INSTALL, "apparmor-profiles"),
        ("install", "-m", "644", _APPARMOR_EXTRA_PROFILE, "/etc/apparmor.d/"),
        _apparmor_load(),
    )


_lock = threading.Lock()
_cache: dict[tuple, tuple[float, "SetupPlan"]] = {}
_elevation_cache: "tuple[float, tuple[str | None, str | None]] | None" = None


@dataclass(frozen = True)
class SetupPlan:
    platform: str
    # One of OPERATIONS; on Linux running it also needs linux_elevation().
    action: str | None = None
    elevation: str | None = None
    steps: tuple[tuple[str, ...], ...] = ()
    manual_command: str = ""
    reason: str = ""
    needs_consent: bool = False

    def as_dict(self) -> dict:
        data = asdict(self)
        data["steps"] = [list(step) for step in self.steps]
        return data


def invalidate() -> None:
    with _lock:
        _cache.clear()


def detect(available: bool | None = None, *, force: bool = False) -> SetupPlan:
    if available is None:
        available = _os_isolation_available()
    key = (sys.platform, bool(available))
    now = time.monotonic()
    with _lock:
        cached = _cache.get(key)
        if not force and cached is not None and now < cached[0]:
            return cached[1]
    if available:
        plan = SetupPlan(
            platform = sys.platform, reason = "OS isolation already works on this computer."
        )
    elif sys.platform == "win32":
        plan = _windows_plan()
    elif sys.platform == "darwin":
        plan = SetupPlan(
            platform = sys.platform,
            reason = "The macOS sandbox (Seatbelt) did not pass its live check.",
        )
    elif sys.platform.startswith("linux"):
        plan = _linux_plan()
    else:
        plan = SetupPlan(
            platform = sys.platform, reason = "No OS sandbox is supported on this platform."
        )
    with _lock:
        _cache[key] = (time.monotonic() + _CACHE_SECONDS, plan)
    return plan


def _os_isolation_available() -> bool:
    """Both tools, as the status and capability reads count it: Python alone is not "works"."""
    from . import os_sandbox
    try:
        return all(
            os_sandbox.capability_snapshot(
                execution_kind = tool,
                selected_executable = os_sandbox.tool_isolation_target(tool),
            ).available
            for tool in os_sandbox.ISOLATED_TOOLS
        )
    except Exception:  # noqa: BLE001 - an unreadable verdict is not a working sandbox
        return False


def _running_as_root() -> bool:
    return hasattr(os, "geteuid") and os.geteuid() == 0


def manual_command(steps) -> str:
    prefix = "" if _running_as_root() else "sudo "
    return " && ".join(f"{prefix}{shlex.join(step)}" for step in steps)


def trusted_system_binary(name: str) -> str | None:
    """`name` from SYSTEM_BIN_DIRS only (never PATH), root-owned and not writable by others."""
    from .sandbox_linux import _trusted_system_file

    for directory in SYSTEM_BIN_DIRS:
        candidate = os.path.join(directory, name)
        if not os.path.exists(candidate):
            continue
        resolved = os.path.realpath(candidate)
        if not _trusted_system_file(resolved):
            continue
        try:
            parent = os.stat(os.path.dirname(resolved))
        except OSError:
            continue
        if parent.st_uid == 0 and not parent.st_mode & 0o022:
            return resolved
    return None


def elevated_steps(steps) -> list[list[str]]:
    """Each step with its program pinned to a trusted absolute path; LookupError if one has none."""
    pinned = []
    for step in steps:
        program = trusted_system_binary(step[0])
        if program is None:
            raise LookupError(f"{step[0]} was not found in {', '.join(SYSTEM_BIN_DIRS)}")
        pinned.append([program, *step[1:]])
    return pinned


def _apparmor_restricts_userns() -> bool:
    try:
        with open(_APPARMOR_SYSCTL, encoding = "utf-8") as f:
            return f.read().strip() == "1"
    except OSError:
        return False


def _package_manager() -> str | None:
    from . import os_sandbox
    for manager, _command in os_sandbox._BWRAP_INSTALL_COMMANDS:
        if shutil.which(manager):
            return manager
    return None


def _is_wsl() -> bool:
    if os.environ.get("WSL_DISTRO_NAME") or os.environ.get("WSL_INTEROP"):
        return True
    try:
        with open("/proc/version", encoding = "utf-8") as f:
            return "microsoft" in f.read().lower()
    except OSError:
        return False


def _trusted_tool(name: str) -> str | None:
    from .sandbox_linux import _trusted_system_file

    candidate = shutil.which(name)
    if candidate is None:
        return None
    resolved = os.path.realpath(candidate)
    if not _trusted_system_file(resolved):
        return None
    try:
        parent = os.stat(os.path.dirname(resolved))
    except OSError:
        return None
    if parent.st_uid != 0 or parent.st_mode & 0o022:
        return None
    return resolved


def _sudo_without_password(sudo: str) -> bool:
    try:
        probe = subprocess.run(
            [sudo, "-n", "true"],
            stdin = subprocess.DEVNULL,
            stdout = subprocess.DEVNULL,
            stderr = subprocess.DEVNULL,
            timeout = 5,
        )
    except (OSError, subprocess.SubprocessError):
        return False
    return probe.returncode == 0


def _graphical_session() -> bool:
    return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))


def linux_elevation(*, force: bool = False) -> tuple[str | None, str | None]:
    """(kind, trusted path): already root, passwordless sudo, then pkexec on a desktop, else neither."""
    global _elevation_cache
    now = time.monotonic()
    with _lock:
        cached = _elevation_cache
    if not force and cached is not None and now < cached[0]:
        return cached[1]
    found = _linux_elevation()
    with _lock:
        _elevation_cache = (time.monotonic() + _ELEVATION_CACHE_SECONDS, found)
    return found


def forget_elevation() -> None:
    global _elevation_cache
    with _lock:
        _elevation_cache = None


def _linux_elevation() -> tuple[str | None, str | None]:
    if _running_as_root():
        return "root", None  # e.g. a container: the pinned steps run as they are
    sudo = _trusted_tool("sudo")
    if sudo is not None and _sudo_without_password(sudo):
        return "sudo", sudo
    if _is_wsl() or not _graphical_session():
        return None, None
    pkexec = _trusted_tool("pkexec")
    if pkexec is not None:
        return "pkexec", pkexec
    return None, None


def _bwrap_state() -> str:
    """As the launcher sees it: "trusted", "missing", "shadowed" (PATH finds an untrusted copy first),
    or "refused" (a pinned or namespace-hidden copy, which installing would not change)."""
    from . import sandbox_linux

    try:
        sandbox_linux._trusted_bwrap_path()
        return "trusted"
    except sandbox_linux.BwrapUntrustedError as exc:
        if exc.pinned or exc.hidden_root:
            return "refused"
    except Exception:  # noqa: BLE001 - any refusal means the launcher will not run it
        pass
    if shutil.which("bwrap") is None or trusted_system_binary("bwrap") is None:
        return "missing"
    return "shadowed"


def _linux_plan() -> SetupPlan:
    from . import os_sandbox

    reason = os_sandbox.linux_unavailable_remediation()
    manager = _package_manager()
    state = _bwrap_state()
    if state == "refused":
        return SetupPlan(platform = sys.platform, reason = reason)
    if state == "shadowed":
        # Installing changes nothing: the system copy is there, PATH just finds another one first.
        return SetupPlan(
            platform = sys.platform,
            reason = (
                f"{shutil.which('bwrap')} comes first on PATH but is not a root-owned system copy, "
                f"so Unsloth will not run it. Remove it, or put {os.path.dirname(trusted_system_binary('bwrap'))} "
                "ahead of it on PATH; nothing needs installing."
            ),
        )
    bwrap_missing = state == "missing"
    if bwrap_missing and manager is None:
        return SetupPlan(platform = sys.platform, reason = reason)
    steps: list[tuple[str, ...]] = []
    if bwrap_missing:
        steps.extend(_INSTALL_STEPS[manager])
    blocked = _apparmor_restricts_userns() and (
        bwrap_missing or os_sandbox._linux_userns_blocked_by_apparmor()
    )
    if blocked and os.path.exists(_APPARMOR_PROFILE):
        steps.append(_apparmor_load())
    elif blocked and manager == "apt-get":
        if not bwrap_missing:
            steps.append(("apt-get", "update"))
        steps.extend(_apparmor_steps())
    if not steps:
        return SetupPlan(platform = sys.platform, reason = reason)
    # The steps carry the command, so the row only needs to say what is wrong.
    return SetupPlan(
        platform = sys.platform,
        action = LINUX_INSTALL,
        steps = tuple(steps),
        manual_command = manual_command(steps),
        reason = (
            "bubblewrap is not installed."
            if bwrap_missing
            else "Ubuntu's AppArmor setting stops bubblewrap from starting a sandbox."
        ),
    )


# Same floor as mxc_probe: older Windows has no MXC ProcessContainer to run.
MXC_MIN_WINDOWS_BUILD = 26100


def windows_runtime_unsupported() -> str | None:
    """None when this Windows can run MXC; else "arch" (not x64 or ARM64) or "build" (older than 26100)."""
    from .wsl_host import native_machine

    if native_machine() not in ("x86_64", "arm64"):
        return "arch"
    try:
        build = sys.getwindowsversion().build
    except AttributeError:  # not Windows
        return None
    return "build" if build < MXC_MIN_WINDOWS_BUILD else None


# First update revision (UBR) with Windows' built-in container (BaseContainer) per release, from MXC's
# docs/backends/process-container/os-version-support.md ("Process Isolation"). Older revisions fall back to
# AppContainer, which needs Unsloth's fallback sandbox and its administrator step.
BUILTIN_CONTAINER_MIN_UBR = {26100: 9278, 26200: 9278, 26300: 9550, 28000: 2804}


def windows_builtin_container_update() -> tuple[str, str] | None:
    """(this PC's build, the first build with the built-in container) when a Windows update adds it, else None."""
    if sys.platform != "win32":
        return None
    try:
        import winreg

        version = sys.getwindowsversion()
        # The table is Windows 11 only: Server 2025 shares build 26100 but has no BaseContainer.
        if version.product_type != 1:  # VER_NT_WORKSTATION
            return None
        build = version.build
        with winreg.OpenKey(
            winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\Microsoft\Windows NT\CurrentVersion"
        ) as key:
            ubr = int(winreg.QueryValueEx(key, "UBR")[0])
    except (OSError, ValueError, TypeError, AttributeError):  # unreadable: say nothing
        return None
    needed = BUILTIN_CONTAINER_MIN_UBR.get(build)
    if needed is None or ubr >= needed:
        return None
    return f"{build}.{ubr}", f"{build}.{needed}"


def windows_runtime_supported() -> bool:
    """The MXC runtime Unsloth installs is built for x64 and ARM64 Windows 11 build 26100 or newer."""
    return windows_runtime_unsupported() is None


_UNSUPPORTED_NOTES = {
    "arch": "The MXC runtime is built for x64 and ARM64 Windows, and this PC is neither.",
    "build": (
        f"The MXC sandbox needs Windows 11 build {MXC_MIN_WINDOWS_BUILD} (24H2) or newer, "
        "and this PC runs an older build."
    ),
}


def windows_runtime_installed() -> bool:
    from . import mxc_runtime
    try:
        mxc_runtime.installation_identity()
    except Exception:  # noqa: BLE001 - no runtime yet
        return False
    return True


def windows_runtime_plan() -> SetupPlan:
    if windows_runtime_installed():
        return SetupPlan(platform = sys.platform, reason = "The MXC runtime is already installed.")
    unsupported = windows_runtime_unsupported()
    if unsupported is not None:
        return SetupPlan(platform = sys.platform, reason = _UNSUPPORTED_NOTES[unsupported])
    step = tuple(windows_runtime_install_command())
    return SetupPlan(
        platform = sys.platform,
        action = WINDOWS_RUNTIME,
        steps = (step,),
        manual_command = powershell_command((step,)),
        reason = "The MXC runtime is not installed.",
    )


def powershell_command(steps) -> str:
    """What to paste into PowerShell (5.1 has no `&&`): one call-operator line per step."""

    def quote(arg: str) -> str:
        # PowerShell also ends a single-quoted string at a curly quote (about_Quoting_Rules).
        return "'" + re.sub("(['‘’‚‛])", r"\1\1", str(arg)) + "'"

    return "\n".join("& " + " ".join(quote(arg) for arg in step) for step in steps)


def windows_runtime_install_command() -> list[str]:
    from . import mxc_runtime
    return [
        sys.executable,
        str(Path(__file__).resolve().parents[3] / "install_mxc_prebuilt.py"),
        "--install-dir",
        str(mxc_runtime._installed_package_root()),
    ]


def _windows_plan() -> SetupPlan:
    from . import mxc_adapter, mxc_policy, mxc_probe, mxc_runtime
    from utils import mxc_isolation_settings as saved

    unsupported = windows_runtime_unsupported()
    if unsupported is not None:
        return SetupPlan(platform = sys.platform, reason = _UNSUPPORTED_NOTES[unsupported])
    installed = windows_runtime_installed()
    missing = None
    if installed:
        try:
            missing = mxc_runtime.probe_host_prep_steps(env = mxc_adapter._control_environment())
        except Exception:  # noqa: BLE001 - unknown: prepare anyway, the helper is idempotent
            missing = None
    opted_in = mxc_policy.dacl_fallback_enabled()
    locked_off = not opted_in and saved.locked_by_environment(mxc_policy.DACL_FALLBACK_ENV)
    steps: list[tuple[str, ...]] = []
    if not installed:
        steps.append(tuple(windows_runtime_install_command()))
    if not installed or missing is None or missing:
        steps.append(tuple(mxc_probe.host_prep_command()))
    manual = powershell_command(steps)
    if locked_off:
        return SetupPlan(
            platform = sys.platform,
            manual_command = manual,
            reason = (
                f"{mxc_policy.DACL_FALLBACK_ENV} is set in the environment Unsloth runs in and keeps "
                "MXC's AppContainer tier off."
            ),
        )
    if not steps and opted_in:
        return SetupPlan(
            platform = sys.platform,
            reason = "MXC is installed, allowed and prepared, but its live check did not pass.",
        )
    parts = []
    if not installed:
        parts.append("the MXC runtime is not installed")
    if not opted_in:
        parts.append("the Windows sandbox is not turned on yet")
    if installed and missing:
        # Plain words; the MXC step names mean nothing to a user. Only the null device step repeats per boot.
        again = list(missing) == ["prepare-null-device"]
        parts.append(
            "this PC needs its administrator step again after the restart"
            if again
            else "this PC still needs its one-time administrator step"
        )
    elif installed and missing is None:
        parts.append("Unsloth could not tell whether this PC had its administrator step")
    return SetupPlan(
        platform = sys.platform,
        action = WINDOWS_SETUP,
        elevation = "uac" if any("--prepare-host" in step for step in steps) else None,
        steps = tuple(steps),
        manual_command = manual,
        reason = _sentence("; ".join(parts)),
        needs_consent = not opted_in,
    )


def _sentence(text: str) -> str:
    return f"{text[:1].upper()}{text[1:]}." if text else ""


def setup_fields_for(
    request,
    user = None,
    *,
    available: bool | None = None,
) -> dict:
    """Setup fields for a capability response: the action only for the owner, here or without a prompt."""
    from utils.client_ip import is_direct_local_request

    plan = detect(available)
    local = False
    try:
        local = is_direct_local_request(request)
    except Exception:  # noqa: BLE001 - an unreadable request is not local
        local = False
    owner = _is_owner(user)
    can_run = can_run_here(plan, owner = owner, local = local)
    blocked = None
    if plan.action and not can_run:
        blocked = "not_owner" if not owner else "not_local" if not local else "no_elevation"
    # Windows commands leak this install's paths (account name, home): owner only.
    command = plan.manual_command if owner or not sys.platform.startswith("win") else ""
    return {
        "setup_action": plan.action if can_run else None,
        "manual_command": command,
        "can_run_setup": can_run,
        "setup_blocked": blocked,
        "needs_consent": plan.needs_consent if can_run else False,
        "reason": plan.reason,
    }


# Nothing to answer on this computer, so a remote owner session (e.g. behind Colab's proxy) may start it.
PROMPTLESS_ELEVATION = ("root", "sudo")


def can_run_here(plan: SetupPlan, *, owner: bool, local: bool) -> bool:
    """Whether this caller gets the setup button. Blocking: may run the Linux elevation check."""
    if not (plan.action and owner):
        return False
    if plan.action == LINUX_INSTALL:
        return linux_install_allowed(local = local)[0]
    return local


def linux_install_allowed(*, local: bool, force: bool = False) -> tuple[bool, str | None]:
    """(allowed, elevation kind): any elevation for a direct local request, otherwise only one with no prompt."""
    kind = linux_elevation(force = force)[0]
    return kind is not None and (local or kind in PROMPTLESS_ELEVATION), kind


def remote_start_allowed(operation: str) -> bool:
    """Whether a request that is not direct-local may start `operation`: only where no prompt appears here."""
    if operation == WINDOWS_RUNTIME:
        return True
    return (
        operation == LINUX_INSTALL
        and sys.platform.startswith("linux")
        and linux_install_allowed(local = False, force = True)[0]
    )


def _is_owner(user) -> bool:
    if user is None:
        from utils.account_context import is_owner_context
        return is_owner_context()
    if isinstance(user, bool):
        return user
    return bool(getattr(user, "is_owner", False))