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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Fix managed vLLM startup in Windows Studio (#12750)
Lee Jacksonad00855f0ae2
diff --git a/studio/backend/core/inference/engine_install.py b/studio/backend/core/inference/engine_install.pyindex fe9070cba85..91783b82f7d 100644--- a/studio/backend/core/inference/engine_install.py+++ b/studio/backend/core/inference/engine_install.py@@ -598,7 +598,22 @@ def _atomic_json(path: Path, data: dict) -> None:tmp = path.with_name(path.name + "." + uuid.uuid4().hex + ".tmp")try:tmp.write_text(json.dumps(data), encoding = "utf-8")- os.replace(tmp, path)+ # Windows readers (including status polling in another Studio process) can+ # briefly deny deletion of the destination. Keep the previous JSON intact+ # and retry the atomic rename; permanent permission errors still surface.+ deadline = time.monotonic() + 1.0+ while True:+ try:+ os.replace(tmp, path)+ break+ except OSError as exc:+ if (+ sys.platform != "win32"+ or getattr(exc, "winerror", None) not in (5, 32, 33)+ or time.monotonic() >= deadline+ ):+ raise+ time.sleep(0.01)finally:tmp.unlink(missing_ok = True)@@ -869,7 +884,9 @@ def _run(argv: list[str],cancel: threading.Event,env: dict | None = None,-) -> None:+ *,+ stdin_pipe: bool = False,+) -> str:from utils.process_lifetime import (adopt_pid,child_popen_kwargs,@@ -880,12 +897,15 @@ def _run()tail: deque[str] = deque(maxlen = 20)+ if (engine_root() / f"{engine}.cancel").exists():+ cancel.set()if cancel.is_set() or is_process_shutting_down():raise RuntimeError("Installation cancelled or Studio is shutting down.")proc = spawn_on_lifetime_thread(lambda: subprocess.Popen(argv,env = install_environment() if env is None else env,+ stdin = subprocess.PIPE if stdin_pipe else None,stdout = subprocess.PIPE,stderr = subprocess.STDOUT,text = True,@@ -946,9 +966,20 @@ def _run("Installation timed out. Retry when the connection is available.")reader.join(timeout = 2)+ if cancel.is_set() or is_process_shutting_down():+ raise RuntimeError("Installation cancelled or Studio is shutting down.")if proc.returncode:raise RuntimeError("Engine installation failed. " + "\n".join(tail))+ return "\n".join(tail)finally:+ if proc.stdin is not None:+ # Closing the WSL runner's pipe stops its guest process group, including+ # apt/dpkg children; terminating wsl.exe alone can leave them running.+ try:+ proc.stdin.close()+ proc.wait(timeout = 15)+ except (OSError, subprocess.TimeoutExpired):+ passif proc.poll() is None:terminate_pid(proc.pid, timeout = 5, owner_verified = True)proc.wait(timeout = 10)@@ -1172,14 +1203,18 @@ def _install_wsl(engine: str, cancel: threading.Event) -> None:"UV_HTTP_RETRIES": "5",# Cache and environments share the distro's ext4 disk."UV_LINK_MODE": "hardlink",+ "DEBIAN_FRONTEND": "noninteractive",}secrets = {key: os.environ[key] for key in _PROXIES if os.environ.get(key)}def guest_run(argv):- command, windows_env = wsl_host.guest_command(argv, env = env, secrets = secrets)- _run(engine, command, cancel, env = windows_env)+ command, windows_env = wsl_host.guest_command(+ [f"{guest_root}/bin/run-engine", *argv], env = env, secrets = secrets+ )+ return _run(engine, command, cancel, env = windows_env, stdin_pipe = True)try:+ wsl_host.ensure_build_tools(guest_run, lambda text: _update(engine, activity = text))_update(engine, phase = "creating", message = "Preparing an isolated Python environment")guest_run([uv, "venv", "--python", "{}.{}".format(*PYTHON), destination])_update(engine, phase = "installing", message = "Downloading and installing engine packages")diff --git a/studio/backend/core/inference/managed_engine.py b/studio/backend/core/inference/managed_engine.pyindex 657211e8cf6..7f32f20dc27 100644--- a/studio/backend/core/inference/managed_engine.py+++ b/studio/backend/core/inference/managed_engine.py@@ -326,7 +326,7 @@ class ManagedEngine:with socket.socket() as sock:sock.bind(("127.0.0.1", 0))port = sock.getsockname()[1]- if port <= 55535:+ if self.engine != "sglang" or port <= 55535:breakelse:raise RuntimeError("Could not allocate an inference server port.")@@ -494,6 +494,8 @@ class ManagedEngine:str(i) for i in wsl_host.guest_gpu_indices(list(gpu_ids or [0]))),"PYTHONNOUSERSITE": "1",+ # C++ links FlashInfer JIT kernels against WSL's driver, outside the usual linker paths.+ "LIBRARY_PATH": "/usr/lib/wsl/lib",# Weights download inside the distro's own disk; /mnt/c reads are far slower."HF_HOME": f"{guest_root}/hf","VLLM_CACHE_ROOT": cache,diff --git a/studio/backend/core/inference/wsl_host.py b/studio/backend/core/inference/wsl_host.pyindex dbebbe49782..d1c19fbd272 100644--- a/studio/backend/core/inference/wsl_host.py+++ b/studio/backend/core/inference/wsl_host.py@@ -315,7 +315,8 @@ def guest_command(if item.split("/")[0] not in secrets and item.split("/")[0].upper() not in withhold]windows_env["WSLENV"] = ":".join([*shared, *(f"{key}/u" for key in secrets)])- command = [exe, "-d", distro_name(), "-u", "root", "--cd", "/root", "--", "/usr/bin/env"]+ # Bypass the default shell so it cannot expand $0/$1 in scripts such as put().+ command = [exe, "-d", distro_name(), "-u", "root", "--cd", "/root", "--exec", "/usr/bin/env"]command += [f"{key}={value}" for key, value in (env or {}).items()]return command + list(argv), windows_env@@ -398,6 +399,36 @@ def _sha256(path: Path) -> str:return digest.hexdigest()+def ensure_build_tools(run_guest, progress = None) -> None:+ """Use the installer's cancellable runner for every prerequisite command."""+ # A successful shell reports absent tools explicitly. Transport/shell failures+ # propagate through run_guest rather than being mistaken for missing packages.+ state = (+ run_guest(+ [+ "sh",+ "-c",+ "if command -v cc >/dev/null && command -v c++ >/dev/null "+ "&& command -v make >/dev/null && test -f /usr/include/stdio.h; "+ "then echo UNSLOTH_BUILD_TOOLS_READY; else echo UNSLOTH_BUILD_TOOLS_MISSING; fi",+ ]+ )+ .strip()+ .splitlines()+ )+ if state and state[-1] == "UNSLOTH_BUILD_TOOLS_READY":+ return+ if not state or state[-1] != "UNSLOTH_BUILD_TOOLS_MISSING":+ raise RuntimeError("Could not check WSL build tools. Retry the installation.")+ if progress:+ progress("Installing WSL build tools")+ # Cancellation can leave a package unpacked but unconfigured. Repair it before+ # retrying the same signed Ubuntu packages in this Studio-owned distro.+ run_guest(["dpkg", "--configure", "-a"])+ run_guest(["apt-get", "update"])+ run_guest(["apt-get", "install", "-y", "--no-install-recommends", "build-essential"])++def ensure_distro(progress = None, cancel = None) -> None:"""Idempotent: import the private distro, configure it, and install uv inside it."""from utils.paths.storage_roots import studio_rootdiff --git a/studio/backend/tests/fake_wsl.py b/studio/backend/tests/fake_wsl.pyindex 2889b6e7de5..c44deb90f9c 100644--- a/studio/backend/tests/fake_wsl.py+++ b/studio/backend/tests/fake_wsl.py@@ -39,9 +39,9 @@ def main(argv):return int(os.environ.get("FAKE_WSL_UNREGISTER", "0"))if argv[:1] in (["--import"], ["--terminate"]):return 0- if "--" not in argv:+ if "--exec" not in argv:return 2- command = argv[argv.index("--") + 1 :]+ command = argv[argv.index("--exec") + 1 :]return subprocess.call(command)diff --git a/studio/backend/tests/test_engine_atomic_json.py b/studio/backend/tests/test_engine_atomic_json.pynew file mode 100644index 00000000000..d813cc5bb2f--- /dev/null+++ b/studio/backend/tests/test_engine_atomic_json.py@@ -0,0 +1,122 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""Atomic engine status writes under Windows file-sharing contention."""++import errno+import json+import sys+import threading++import pytest++from core.inference import engine_install as install+++def _windows_error(code):+ error = PermissionError(errno.EACCES, "file is open")+ error.winerror = code+ return error++[email protected](sys.platform != "win32", reason = "Windows read handles deny deletion")+def test_atomic_json_waits_for_real_windows_reader(tmp_path, monkeypatch):+ path = tmp_path / "vllm.job.json"+ path.write_text('{"state":"queued"}', encoding = "utf-8")+ replace = install.os.replace+ denied = threading.Event()+ errors = []++ def observed_replace(source, destination):+ try:+ return replace(source, destination)+ except PermissionError:+ denied.set()+ raise++ monkeypatch.setattr(install.os, "replace", observed_replace)++ def writer():+ try:+ install._atomic_json(path, {"state": "running"})+ except Exception as error:+ errors.append(error)++ with path.open(encoding = "utf-8") as reader:+ assert json.load(reader) == {"state": "queued"}+ thread = threading.Thread(target = writer)+ thread.start()+ saw_denial = denied.wait(5)+ # Close the reader before joining, allowing the retried rename to complete.+ thread.join(5)+ assert not thread.is_alive()+ assert saw_denial, "Windows did not refuse replacement of the open file"+ assert not errors+ assert json.loads(path.read_text()) == {"state": "running"}+ assert not list(tmp_path.glob("*.tmp"))++[email protected]("code", [5, 32, 33])+def test_atomic_json_retries_windows_contention(tmp_path, monkeypatch, code):+ monkeypatch.setattr(install.sys, "platform", "win32")+ path = tmp_path / "vllm.job.json"+ path.write_text('{"state":"queued"}')+ replace = install.os.replace+ calls = []++ def transient(source, destination):+ calls.append(source)+ if len(calls) == 1:+ assert json.loads(path.read_text()) == {"state": "queued"}+ raise _windows_error(code)+ return replace(source, destination)++ monkeypatch.setattr(install.os, "replace", transient)+ install._atomic_json(path, {"state": "running"})+ assert len(calls) == 2+ assert calls[0] == calls[1]+ assert json.loads(path.read_text()) == {"state": "running"}+ assert not list(tmp_path.glob("*.tmp"))+++def test_atomic_json_permanent_denial_is_bounded_and_preserves_previous(tmp_path, monkeypatch):+ monkeypatch.setattr(install.sys, "platform", "win32")+ path = tmp_path / "vllm.job.json"+ path.write_text('{"state":"queued"}')+ clock = iter([0, 0.25, 0.5, 0.75, 1.0])+ monkeypatch.setattr(install.time, "monotonic", lambda: next(clock))+ monkeypatch.setattr(install.time, "sleep", lambda _: None)+ calls = []+ error = _windows_error(5)++ def denied(source, destination):+ calls.append(source)+ raise error++ monkeypatch.setattr(install.os, "replace", denied)+ with pytest.raises(PermissionError) as caught:+ install._atomic_json(path, {"state": "running"})+ assert caught.value is error+ assert len(calls) == 4+ assert json.loads(path.read_text()) == {"state": "queued"}+ assert not list(tmp_path.glob("*.tmp"))++[email protected]("platform,code", [("linux", 5), ("win32", 112)])+def test_atomic_json_other_errors_are_not_retried(tmp_path, monkeypatch, platform, code):+ monkeypatch.setattr(install.sys, "platform", platform)+ path = tmp_path / "vllm.job.json"+ error = _windows_error(code)+ calls = []++ def denied(source, destination):+ calls.append(source)+ raise error++ monkeypatch.setattr(install.os, "replace", denied)+ with pytest.raises(PermissionError) as caught:+ install._atomic_json(path, {"state": "running"})+ assert caught.value is error+ assert len(calls) == 1+ assert not path.exists()+ assert not list(tmp_path.glob("*.tmp"))diff --git a/studio/backend/tests/test_engine_ports.py b/studio/backend/tests/test_engine_ports.pynew file mode 100644index 00000000000..18805c60b73--- /dev/null+++ b/studio/backend/tests/test_engine_ports.py@@ -0,0 +1,53 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""Engine-specific bounds on operating-system-assigned HTTP ports."""++from contextlib import nullcontext++import pytest++from core.inference import managed_engine+++ "name,ports,expected",+ [+ ("vllm", [60000] * 100, 60000),+ ("sglang", [60000, 8123], 8123),+ ("sglang", [60000] * 100, None),+ ],+)+def test_only_sglang_reserves_space_for_its_derived_port(monkeypatch, name, ports, expected):+ assigned = iter(ports)++ class Socket:+ def __enter__(self):+ return self++ def __exit__(self, *_):+ pass++ def bind(self, _):+ pass++ def getsockname(self):+ return "127.0.0.1", next(assigned)++ monkeypatch.setattr(managed_engine.socket, "socket", Socket)+ monkeypatch.setattr(managed_engine, "engine_lease", lambda _: nullcontext())+ monkeypatch.setattr(managed_engine, "installed", lambda _: {"host": "wsl"})+ engine = managed_engine.ManagedEngine(name)+ selected = []++ def launch(*args):+ selected.append(args[-1])+ raise RuntimeError("test reached engine launch")++ monkeypatch.setattr(engine, "_wsl_command", launch)+ message = (+ "test reached engine launch" if expected else "Could not allocate an inference server port"+ )+ with pytest.raises(RuntimeError, match = message):+ engine.start("model", 2048, [0], {})+ assert selected == ([] if expected is None else [expected])diff --git a/studio/backend/tests/test_wsl_guest_argv.py b/studio/backend/tests/test_wsl_guest_argv.pynew file mode 100644index 00000000000..b6154592395--- /dev/null+++ b/studio/backend/tests/test_wsl_guest_argv.py@@ -0,0 +1,38 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""Opt-in Windows checks against Studio's disposable WSL environment."""++import os+import sys+import uuid++import pytest++from core.inference import wsl_host+++ sys.platform != "win32" or not os.environ.get("UNSLOTH_TEST_WSL_DISTRO"),+ reason = "requires Windows and an explicitly selected Studio test WSL distro",+)+def test_real_wsl_preserves_shell_arguments(monkeypatch):+ monkeypatch.setattr(wsl_host, "distro_name", lambda: os.environ["UNSLOTH_TEST_WSL_DISTRO"])+ output = wsl_host.guest(+ ["sh", "-c", 'printf "%s\n" "$0" "$1"', "literal $HOME", 'value "quotes"']+ )+ assert output.splitlines() == ["literal $HOME", 'value "quotes"']+++ sys.platform != "win32" or not os.environ.get("UNSLOTH_TEST_WSL_DISTRO"),+ reason = "requires Windows and an explicitly selected Studio test WSL distro",+)+def test_real_wsl_put_writes_only_its_destination(monkeypatch):+ monkeypatch.setattr(wsl_host, "distro_name", lambda: os.environ["UNSLOTH_TEST_WSL_DISTRO"])+ path = "/tmp/unsloth put " + uuid.uuid4().hex+ try:+ wsl_host.put(path, "first line\nsecond line\n")+ assert wsl_host.guest(["cat", path]) == "first line\nsecond line\n"+ finally:+ wsl_host.guest(["rm", "-f", "--", path])diff --git a/studio/backend/tests/test_wsl_host.py b/studio/backend/tests/test_wsl_host.pyindex 5c542b71c4f..70c031b17ad 100644--- a/studio/backend/tests/test_wsl_host.py+++ b/studio/backend/tests/test_wsl_host.py@@ -117,7 +117,7 @@ def test_secrets_cross_through_wslenv_not_argv(wsl, monkeypatch):["python", "-V"], env = {"CUDA_VISIBLE_DEVICES": "GPU-1"}, secrets = {"HF_TOKEN": "hf_secret"})assert "hf_secret" not in " ".join(command)- assert command[1:8] == ["-d", "Unsloth-Engines-test", "-u", "root", "--cd", "/root", "--"]+ assert command[1:8] == ["-d", "Unsloth-Engines-test", "-u", "root", "--cd", "/root", "--exec"]assert "CUDA_VISIBLE_DEVICES=GPU-1" in commandassert env["HF_TOKEN"] == "hf_secret"assert env["WSLENV"] == "USERPROFILE/p:HF_TOKEN/u"@@ -336,8 +336,9 @@ def test_wsl_launch_command(wsl, monkeypatch):8123,)joined = " ".join(command)- assert command[command.index("--") + 2].endswith("/bin/run-engine")+ assert command[command.index("--exec") + 2].endswith("/bin/run-engine")assert "CUDA_VISIBLE_DEVICES=0,2" in command and "CUDA_DEVICE_ORDER=PCI_BUS_ID" in command+ assert "LIBRARY_PATH=/usr/lib/wsl/lib" in commandassert "VLLM_USE_DEEP_GEMM=0" in command and "CUDA_HOME=/env/cuda" in commandassert f"HF_HOME={wsl_host.GUEST_ROOT}/hf" in command# Windows paths and secrets never reach the guest command line.@@ -559,3 +560,180 @@ def test_host_gpu_probes_hide_their_console_window(monkeypatch):except Exception:passassert seen == [0x08000000] * 2++[email protected]("present", [True, False])+def test_wsl_build_tools_are_provisioned_only_when_missing(present):+ calls = []+ messages = []++ def run_guest(argv):+ calls.append(argv)+ if len(calls) == 1:+ return "UNSLOTH_BUILD_TOOLS_READY" if present else "UNSLOTH_BUILD_TOOLS_MISSING"+ return ""++ wsl_host.ensure_build_tools(run_guest, messages.append)+ assert calls[0][:2] == ["sh", "-c"]+ if present:+ assert len(calls) == 1 and not messages+ else:+ assert messages == ["Installing WSL build tools"]+ assert calls[1:] == [+ ["dpkg", "--configure", "-a"],+ ["apt-get", "update"],+ ["apt-get", "install", "-y", "--no-install-recommends", "build-essential"],+ ]+++def test_wsl_build_tool_probe_failure_does_not_install_packages():+ calls = []+ error = RuntimeError("WSL could not start")++ def run_guest(argv):+ calls.append(argv)+ raise error++ with pytest.raises(RuntimeError) as caught:+ wsl_host.ensure_build_tools(run_guest)+ assert caught.value is error+ assert len(calls) == 1++[email protected]("output", ["", "unexpected WSL output"])+def test_wsl_build_tool_probe_requires_an_explicit_result(output):+ calls = []++ def run_guest(argv):+ calls.append(argv)+ return output++ with pytest.raises(RuntimeError, match = "Could not check WSL build tools"):+ wsl_host.ensure_build_tools(run_guest)+ assert len(calls) == 1+++def test_wsl_build_tool_failure_is_reported():+ calls = []++ def run_guest(argv):+ calls.append(argv)+ if len(calls) == 1:+ return "UNSLOTH_BUILD_TOOLS_MISSING"+ raise RuntimeError("package repair failed")++ with pytest.raises(RuntimeError, match = "package repair failed"):+ wsl_host.ensure_build_tools(run_guest)+ assert len(calls) == 2+++@_GUEST_RUNNER[email protected]("cancel_source", ["event", "file"])+def test_build_tool_cancellation_reaps_the_guest_process_group(+ tmp_path, monkeypatch, cancel_source+):+ import threading++ monkeypatch.setattr(install, "engine_root", lambda: tmp_path)+ monkeypatch.setattr(install, "_update", lambda *args, **kwargs: None)+ pids = tmp_path / "apt-pids"+ code = (+ "import os, subprocess, time; child = subprocess.Popen(['sleep', '300']); "+ f"open({str(pids)!r}, 'w').write(f'{{os.getpid()}} {{child.pid}}'); time.sleep(300)"+ )+ cancel = threading.Event()+ calls, errors = [], []++ def run_guest(argv):+ calls.append(argv)+ if argv[0] == "sh":+ return "UNSLOTH_BUILD_TOOLS_MISSING"+ if argv[0] == "dpkg":+ return ""+ return install._run(+ "vllm",+ [str(_runner(tmp_path)), sys.executable, "-I", "-S", "-u", "-c", code],+ cancel,+ stdin_pipe = True,+ )++ def provision():+ try:+ wsl_host.ensure_build_tools(run_guest)+ except RuntimeError as exc:+ errors.append(exc)++ thread = threading.Thread(target = provision)+ thread.start()+ try:+ # Python start-up on a loaded -n 4 runner, not the cancellation, sets this wait.+ deadline = time.monotonic() + 60+ while (+ not (pids.exists() and pids.read_text())+ and thread.is_alive()+ and time.monotonic() < deadline+ ):+ time.sleep(0.05)+ assert pids.exists() and pids.read_text(), errors+ apt_pid, child_pid = map(int, pids.read_text().split())+ if cancel_source == "file":+ (tmp_path / "vllm.cancel").touch()+ else:+ cancel.set()+ thread.join(20)+ assert not thread.is_alive()+ assert errors and "cancelled" in str(errors[0]).lower()+ assert _gone(apt_pid, 5) and _gone(child_pid, 5)+ assert [+ "apt-get",+ "install",+ "-y",+ "--no-install-recommends",+ "build-essential",+ ] not in calls+ finally:+ cancel.set()+ thread.join(20)+++def test_cancelled_preparation_does_not_start_a_guest_command(tmp_path, monkeypatch):+ import threading++ monkeypatch.setattr(install, "engine_root", lambda: tmp_path)+ (tmp_path / "vllm.cancel").touch()+ started = tmp_path / "started"+ command = [sys.executable, "-c", f"open({str(started)!r}, 'w').close()"]+ with pytest.raises(RuntimeError, match = "cancelled"):+ install._run("vllm", command, threading.Event(), stdin_pipe = True)+ assert not started.exists()+++def test_preparation_pipe_close_failure_still_cleans_up(tmp_path, monkeypatch):+ import io+ import threading+ from utils import process_lifetime++ class Stdin:+ def close(self):+ raise OSError("pipe already disconnected")++ class Process:+ pid = 123456+ returncode = 0+ stdin = Stdin()+ stdout = io.StringIO()++ def poll(self):+ return 0++ def wait(self, timeout):+ return 0++ proc, forgotten = Process(), []+ monkeypatch.setattr(install, "engine_root", lambda: tmp_path)+ monkeypatch.setattr(process_lifetime, "spawn_on_lifetime_thread", lambda factory: proc)+ monkeypatch.setattr(process_lifetime, "adopt_pid", lambda pid: None)+ monkeypatch.setattr(process_lifetime, "forget_pid", forgotten.append)+ monkeypatch.setattr(process_lifetime, "is_process_shutting_down", lambda: False)+ assert install._run("vllm", ["unused"], threading.Event(), stdin_pipe = True) == ""+ assert forgotten == [proc.pid] and proc.stdout.closed