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
Studio: fix unsloth start when port 8888 is already in use (#10942)
Nilay676332d38292
diff --git a/tests/studio/test_cli_start_download_liveness.py b/tests/studio/test_cli_start_download_liveness.pyindex c2b6766792f..c1a9bd4862f 100644--- a/tests/studio/test_cli_start_download_liveness.py+++ b/tests/studio/test_cli_start_download_liveness.py@@ -217,7 +217,7 @@ class Harness:return Falsedef start(self):- return start_cli._start_studio_server(BASE, MODEL, start_cli.LoadOptions())+ return start_cli._start_studio_server(BASE, MODEL, start_cli.LoadOptions())[1]def test_a_live_download_survives_past_the_idle_cap(monkeypatch):diff --git a/tests/studio/test_studio_pid_file_contract.py b/tests/studio/test_studio_pid_file_contract.pyindex 82f2494e2bb..d88abcd3794 100644--- a/tests/studio/test_studio_pid_file_contract.py+++ b/tests/studio/test_studio_pid_file_contract.py@@ -51,6 +51,33 @@ def test_stop_finds_a_pid_file_named_the_way_the_backend_writes_it(tmp_path, monassert [pid for pid, _times, _files in cli._pid_file_entries()] == [os.getpid()]+def test_discovery_reads_the_bind_addresses_the_backend_records(tmp_path, monkeypatch):+ """Discovery probes a recorded port on the addresses _write_pid_file put in the record, not an+ assumed 127.0.0.1 that reaches a stranger."""+ from unsloth_cli import _inference+ from unsloth_cli.commands import studio as cli++ ns = {+ "os": os,+ "Path": Path,+ "_studio_root": lambda: tmp_path,+ "_PID_FILE": tmp_path / "studio.pid",+ "_pid_file_for_port": lambda port: _backend_pid_path(tmp_path, port),+ "_process_create_time": lambda pid: None,+ "_bind_addresses": lambda host, port: {"::1"},+ "_read_pid_record": lambda path: None,+ "_pid_alive": lambda pid: False,+ "_OWN_PID_FILE": None,+ }+ exec(_func_source(_RUN_SRC, "_write_pid_file"), ns)+ ns["_write_pid_file"](8901, "localhost")++ monkeypatch.setattr(cli, "STUDIO_HOME", tmp_path)+ monkeypatch.setattr(cli, "_pid_alive", lambda pid: True)++ assert list(_inference._recorded_studio_bases([])) == ["http://[::1]:8901"]++def test_the_legacy_file_stays_a_bare_pid_an_older_cli_can_parse(tmp_path, monkeypatch):# An older `unsloth studio stop` reads studio.pid and requires str.isdigit(), so the compatibility file must never# gain the extra metadata lines.diff --git a/unsloth_cli/_inference.py b/unsloth_cli/_inference.pyindex 48210252e8b..10ad1cf1c3e 100644--- a/unsloth_cli/_inference.py+++ b/unsloth_cli/_inference.py@@ -4,6 +4,7 @@"""Model loading and streaming shared by `inference` and `chat`."""import asyncio+import itertoolsimport jsonimport osimport re@@ -643,19 +644,80 @@ def _loopback_candidate_bases(base: str) -> list:return bases or [base]+_STUDIO_SERVICE_MARKER = "Unsloth UI Backend"+++def _recorded_loopback_bases(address: Optional[str], port: str) -> list:+ """Loopback bases for a server recorded at *address*. The wrong family reaches whoever else+ holds that port number."""+ import ipaddress++ loopback, parsed_any = set(), False+ for text in (address or "").split(","):+ try:+ ip = ipaddress.ip_address(text.strip())+ except ValueError:+ continue+ parsed_any = True+ if ip.is_unspecified:+ loopback.add(ipaddress.ip_address("::1" if ip.version == 6 else "127.0.0.1"))+ elif ip.is_loopback:+ loopback.add(ip)+ if not parsed_any:+ loopback.add(ipaddress.ip_address("127.0.0.1"))+ return [+ f"http://[{ip.compressed}]:{port}" if ip.version == 6 else f"http://{ip.compressed}:{port}"+ for ip in sorted(loopback, key = lambda ip: (ip.version, ip.compressed))+ ]+++def _recorded_studio_bases(tried: list):+ from unsloth_cli.commands.studio import (+ PID_FILE_GLOB,+ STUDIO_HOME,+ _pid_alive,+ _pid_is_studio_server,+ _read_pid_record,+ )++ seen = set(tried)+ try:+ paths = sorted(STUDIO_HOME.glob(PID_FILE_GLOB))+ except OSError:+ return+ for path in paths:+ match = re.fullmatch(r"studio-(\d+)-\d+\.pid", path.name)+ record = _read_pid_record(path) if match else None+ if record is None:+ continue+ pid, created, address = record+ if not _pid_alive(pid) or not _pid_is_studio_server(pid, [created]):+ continue+ for candidate in _recorded_loopback_bases(address, match.group(1)):+ if candidate not in seen:+ seen.add(candidate)+ yield candidate++def find_studio_server(timeout: float = 3.0) -> Optional[str]:import urllib.requestbase = os.environ.get("UNSLOTH_STUDIO_URL", "http://127.0.0.1:8888").rstrip("/")+ candidates = _loopback_candidate_bases(base)+ if not os.environ.get("UNSLOTH_STUDIO_URL"):+ candidates = itertools.chain(candidates, _recorded_studio_bases(candidates))# Try the concrete loopback addresses in order and return the first that answers, so the rest of# the flow talks to that exact address.- for candidate in _loopback_candidate_bases(base):+ for candidate in candidates:request = urllib.request.Request(f"{candidate}/api/health", headers = {"User-Agent": _USER_AGENT})try:- with urllib.request.urlopen(request, timeout = timeout):- return candidate+ with urllib.request.urlopen(request, timeout = timeout) as response:+ # A live port is not Studio: a stranger answering every path would get our key.+ body = json.loads(response.read(65536).decode() or "{}")+ if body.get("service") == _STUDIO_SERVICE_MARKER:+ return candidateexcept Exception:continuereturn Nonediff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.pyindex c9cd0e01bc1..30e32275827 100644--- a/unsloth_cli/commands/start.py+++ b/unsloth_cli/commands/start.py@@ -796,6 +796,7 @@ _DOWNLOAD_POLL_INTERVAL_S = 1.0# Ceiling on the doubling back-off the progress reader uses after a polling error._DOWNLOAD_POLL_MAX_BACKOFF_S = 60.0_START_API_KEY_PREFIX = "UNSLOTH_START_API_KEY: "+_START_PORT_PREFIX = "UNSLOTH_START_PORT: "_START_API_KEY_MARKER_ENV = "_UNSLOTH_START_API_KEY_MARKER"@@ -1091,13 +1092,17 @@ def _studio_healthy(base: str, timeout: float = 3.0) -> bool:return False-def _log_tail(path: Path, lines: int = 20) -> str:+def _read_log(path: Path) -> str:try:- return "\n".join(path.read_text(encoding = "utf-8", errors = "replace").splitlines()[-lines:])+ return path.read_text(encoding = "utf-8", errors = "replace")except OSError:return "(no server log)"+def _log_tail(path: Path, lines: int = 20) -> str:+ return "\n".join(_read_log(path).splitlines()[-lines:])++def _redacted_log_tail(path: Path, lines: int = 20) -> str:"""Tail with minted keys removed; only for tails shown on the terminal."""return re.sub(r"sk-unsloth-\S+", "sk-unsloth-[redacted]", _log_tail(path, lines))@@ -1155,8 +1160,8 @@ def _start_studio_server(model: str,load: LoadOptions,server: ServerOptions = ServerOptions(),-) -> subprocess.Popen:- """Spawn `unsloth run` for `model`, wait until it is fully ready, and return it."""+) -> tuple:+ """Spawn `unsloth run` for `model`, wait until it is fully ready, and return (base, server)."""global _auto_served_server# Windows goes through this interpreter, not the launcher on PATH: shutil.which resolves `unsloth` to the denied unsloth.exe, since PATHEXT puts .EXE ahead of the .cmd shim (#8490). Without this, a user who reached the CLI through unsloth.cmd would still fail here. sys.executable is the interpreter already running this command, so the child inherits the same environment.if sys.platform == "win32":@@ -1246,6 +1251,7 @@ def _start_studio_server(progress: Optional[_ModelDownloadProgress] = Nonedownloaded_bytes = 0early_key_seen = False+ port_followed = Falsetry:while time.monotonic() < deadline:if server.poll() is not None:@@ -1254,6 +1260,17 @@ def _start_studio_server(_shutdown_auto_served()_fail(f"The Unsloth server stopped before it was ready. Last log lines:\n{tail}")tail = _log_tail(log_path, lines = 400)+ # `unsloth run` falls forward off a taken port, so poll the port it reports. Printed+ # once, so read the whole log, not the tail below.+ if not port_followed:+ bound_port = re.search(+ rf"^{re.escape(_START_PORT_PREFIX)}(\d+)$",+ _read_log(log_path),+ flags = re.MULTILINE,+ )+ if bound_port:+ port_followed = True+ base = _effective_base(base, int(bound_port.group(1)))if progress is None:marker = re.search(rf"^{re.escape(_START_API_KEY_PREFIX)}(sk-unsloth-[^\s]+)$",@@ -1287,7 +1304,7 @@ def _start_studio_server(progress.complete()progress.close()progress = None- return server+ return base, servertime.sleep(2.0)finally:if progress is not None:@@ -1299,13 +1316,13 @@ def _start_studio_server()-def _effective_base(base: str) -> str:+def _effective_base(base: str, port: Optional[int] = None) -> str:# `unsloth run` binds to `parsed.port or 8888` and serves at the root, so normalize UNSLOTH_STUDIO_URL to plain scheme://host:port. A portless http://127.0.0.1 would otherwise launch on 8888 but poll port 80, and a path like /studio would poll /studio/api/health (404), either way hitting the startup timeout. IPv6 literals stay bracketed.parsed = urlparse(base)host = parsed.hostname or "127.0.0.1"if ":" in host: # bare IPv6 literal (urlparse strips the brackets)host = f"[{host}]"- return f"{parsed.scheme or 'http'}://{host}:{parsed.port or 8888}"+ return f"{parsed.scheme or 'http'}://{host}:{port or parsed.port or 8888}"def _require_studio(@@ -1370,7 +1387,7 @@ def _require_studio(expected = _effective_base(expected)load = load or LoadOptions()# Leave a bare GGUF repo's variant unset: the server's own quant preference already picks the best available (UD-Q4_K_XL for Unsloth uploads, else Q4_K_M) and falls back when that exact quant is missing, which forcing a fixed variant here would break.- return expected, _start_studio_server(expected, model, load, server_options)+ return _start_studio_server(expected, model, load, server_options)model_hint = "" if model else " Pass --model to have it start one for you, or"_fail(f"No running Unsloth server found at {expected}.{model_hint} start one with "diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.pyindex d04637fcd52..3f09582b200 100644--- a/unsloth_cli/commands/studio.py+++ b/unsloth_cli/commands/studio.py@@ -2570,6 +2570,7 @@ def run(api_key = _create_api_key_inprocess(api_key_name)if start_api_key_marker:+ typer.echo(f"UNSLOTH_START_PORT: {actual_port}")typer.echo(f"UNSLOTH_START_API_KEY: {api_key}")if not silent:@@ -2727,7 +2728,7 @@ def _pid_alive(pid: int) -> bool:return True-def _parse_pid_record(text: str) -> "tuple[int, float | None] | None":+def _parse_pid_record(text: str) -> "tuple[int, float | None, str | None] | None":lines = text.splitlines()if not lines or not lines[0].strip().isdigit():return None@@ -2745,10 +2746,12 @@ def _parse_pid_record(text: str) -> "tuple[int, float | None] | None":created = float(lines[1].strip())except ValueError:created = None- return pid, created+ # Third line: the addresses run.py bound, absent in a legacy record.+ address = lines[2].strip() if len(lines) > 2 and lines[2].strip() else None+ return pid, created, address-def _read_pid_record(path: Path) -> "tuple[int, float | None] | None":+def _read_pid_record(path: Path) -> "tuple[int, float | None, str | None] | None":try:text = path.read_text(encoding = "utf-8")except (OSError, UnicodeDecodeError):@@ -2804,7 +2807,7 @@ def _pid_file_entries(typer.echo(f"Ignoring invalid PID file {path.name}")_unlink_quietly(path)continue- pid, created = record+ pid, created, _address = recordcreated_times, files = by_pid.setdefault(pid, ([], []))created_times.append(created)files.append(path)diff --git a/unsloth_cli/tests/test_inference_chat.py b/unsloth_cli/tests/test_inference_chat.pyindex 50a5ce059da..7e6b1517a41 100644--- a/unsloth_cli/tests/test_inference_chat.py+++ b/unsloth_cli/tests/test_inference_chat.py@@ -942,6 +942,20 @@ def test_chat_no_arg_chats_with_picked_trained_model(monkeypatch):assert resolved == ["outputs/run-42"]+class _HealthResponse:+ def __init__(self, body = b'{"status": "healthy", "service": "Unsloth UI Backend"}'):+ self._body = body++ def read(self, _limit = None):+ return self._body++ def __enter__(self):+ return self++ def __exit__(self, *a):+ return False++def test_find_studio_server_none_when_not_running(monkeypatch):import urllib.request@@ -954,6 +968,125 @@ def test_find_studio_server_none_when_not_running(monkeypatch):assert _inference.find_studio_server() is None+def test_find_studio_server_falls_back_to_a_recorded_studio_port(monkeypatch, tmp_path):+ import importlib+ import os+ import urllib.request++ from unsloth_cli import _inference++ studio = importlib.import_module("unsloth_cli.commands.studio")+ monkeypatch.delenv("UNSLOTH_STUDIO_URL", raising = False)+ monkeypatch.setattr(studio, "STUDIO_HOME", tmp_path)+ monkeypatch.setattr(studio, "_pid_alive", lambda pid: pid == os.getpid())+ # Legacy records: a bare PID, no start time and no bind-address line.+ (tmp_path / "studio-8887-424242.pid").write_text("424242", encoding = "utf-8")+ (tmp_path / f"studio-8889-{os.getpid()}.pid").write_text(str(os.getpid()), encoding = "utf-8")+ probed = []++ def default_port_taken(request, *a, **k):+ probed.append(request.full_url)+ if ":8888/" in request.full_url:+ raise OSError("HTTP Error 404: File not found")+ return _HealthResponse()++ monkeypatch.setattr(urllib.request, "urlopen", default_port_taken)+ assert _inference.find_studio_server() == "http://127.0.0.1:8889"+ assert probed == ["http://127.0.0.1:8888/api/health", "http://127.0.0.1:8889/api/health"]++ probed.clear()+ monkeypatch.setenv("UNSLOTH_STUDIO_URL", "http://127.0.0.1:8888")+ assert _inference.find_studio_server() is None+ assert probed == ["http://127.0.0.1:8888/api/health"]+++def test_find_studio_server_skips_a_recorded_pid_reused_by_another_process(monkeypatch, tmp_path):+ import importlib+ import sys+ import types+ import urllib.request++ from unsloth_cli import _inference++ studio = importlib.import_module("unsloth_cli.commands.studio")+ monkeypatch.delenv("UNSLOTH_STUDIO_URL", raising = False)+ monkeypatch.setattr(studio, "STUDIO_HOME", tmp_path)+ monkeypatch.setattr(studio, "_pid_alive", lambda pid: True)+ process = types.SimpleNamespace(create_time = lambda: 1000.0)+ monkeypatch.setitem(sys.modules, "psutil", types.SimpleNamespace(Process = lambda pid: process))+ # A crashed Studio's record whose PID now belongs to another process, next to a live one.+ (tmp_path / "studio-8887-4242.pid").write_text("4242\n500.0\n127.0.0.1", encoding = "utf-8")+ (tmp_path / "studio-8889-4343.pid").write_text("4343\n1000.0\n127.0.0.1", encoding = "utf-8")+ probed = []++ def urlopen(request, *a, **k):+ probed.append(request.full_url)+ if ":8888/" in request.full_url:+ raise OSError("connection refused")+ return _HealthResponse()++ monkeypatch.setattr(urllib.request, "urlopen", urlopen)+ assert _inference.find_studio_server() == "http://127.0.0.1:8889"+ assert probed == ["http://127.0.0.1:8888/api/health", "http://127.0.0.1:8889/api/health"]+++def test_find_studio_server_probes_a_recorded_port_on_the_family_it_bound(monkeypatch, tmp_path):+ # An IPv6-only Studio shares its port number with whoever holds 127.0.0.1.+ import importlib+ import urllib.request++ from unsloth_cli import _inference++ studio = importlib.import_module("unsloth_cli.commands.studio")+ monkeypatch.delenv("UNSLOTH_STUDIO_URL", raising = False)+ monkeypatch.setattr(studio, "STUDIO_HOME", tmp_path)+ monkeypatch.setattr(studio, "_pid_alive", lambda pid: True)+ (tmp_path / "studio-8889-4343.pid").write_text("4343\n\n::1", encoding = "utf-8")+ # `::` is v6only on macOS; a LAN-only bind is not reachable from this flow at all.+ (tmp_path / "studio-8890-4344.pid").write_text("4344\n\n0.0.0.0,::", encoding = "utf-8")+ (tmp_path / "studio-8891-4345.pid").write_text("4345\n\n::", encoding = "utf-8")+ (tmp_path / "studio-8892-4346.pid").write_text("4346\n\n192.168.1.5", encoding = "utf-8")+ probed = []++ def nothing_answers(request, *a, **k):+ probed.append(request.full_url)+ raise OSError("connection refused")++ monkeypatch.setattr(urllib.request, "urlopen", nothing_answers)+ assert _inference.find_studio_server() is None+ assert probed == [+ "http://127.0.0.1:8888/api/health",+ "http://[::1]:8889/api/health",+ "http://127.0.0.1:8890/api/health",+ "http://[::1]:8890/api/health",+ "http://[::1]:8891/api/health",+ ]+++def test_find_studio_server_keeps_looking_past_a_stranger_on_the_default_port(+ monkeypatch, tmp_path+):+ # Whatever took 8888 answers a health payload of its own for every path.+ import importlib+ import urllib.request++ from unsloth_cli import _inference++ studio = importlib.import_module("unsloth_cli.commands.studio")+ monkeypatch.delenv("UNSLOTH_STUDIO_URL", raising = False)+ monkeypatch.setattr(studio, "STUDIO_HOME", tmp_path)+ monkeypatch.setattr(studio, "_pid_alive", lambda pid: True)+ (tmp_path / "studio-8889-4343.pid").write_text("4343\n\n127.0.0.1", encoding = "utf-8")++ def stranger_on_8888(request, *a, **k):+ if ":8888/" in request.full_url:+ return _HealthResponse(b'{"status": "healthy", "service": "some-other-app"}')+ return _HealthResponse()++ monkeypatch.setattr(urllib.request, "urlopen", stranger_on_8888)+ assert _inference.find_studio_server() == "http://127.0.0.1:8889"++def test_find_studio_server_prefers_ipv4_loopback_for_localhost(monkeypatch):# localhost resolving ::1-first must not hide an Unsloth bound to 127.0.0.1: discovery tries each# loopback address and returns the one that answers.@@ -972,17 +1105,10 @@ def test_find_studio_server_prefers_ipv4_loopback_for_localhost(monkeypatch):],)- class _OK:- def __enter__(self):- return self-- def __exit__(self, *a):- return False-def only_ipv4(request, *a, **k):if "127.0.0.1" not in request.full_url:raise OSError("connection refused")- return _OK()+ return _HealthResponse()monkeypatch.setattr(urllib.request, "urlopen", only_ipv4)assert _inference.find_studio_server() == "http://127.0.0.1:8888"diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.pyindex 37c323372f6..4f876bd9b94 100644--- a/unsloth_cli/tests/test_start.py+++ b/unsloth_cli/tests/test_start.py@@ -6,6 +6,7 @@from __future__ import annotationsimport http.client+import http.serverimport ioimport jsonimport os@@ -13,6 +14,7 @@ import reimport shleximport signalimport sys+import threadingimport timeimport urllib.errorfrom pathlib import Path@@ -3041,7 +3043,7 @@ def test_start_positional_model_routes_to_model_on_auto_serve(fake_studio, monkecaptured["load"] = loadcaptured["server_options"] = server_optionsstart._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(start, "_shutdown_server", lambda server: None)@@ -3072,7 +3074,7 @@ def test_start_local_gguf_path_keeps_no_default_variant(fake_studio, monkeypatch):captured["load"] = loadstart._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(start, "_shutdown_server", lambda server: None)@@ -3347,7 +3349,7 @@ def test_start_claude_parses_sampling_flags(fake_studio, monkeypatch):):captured["server_options"] = server_optionsstart._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(start, "_shutdown_server", lambda server: None)@@ -3895,7 +3897,7 @@ def test_start_studio_server_builds_command_and_waits(monkeypatch, capsys):monkeypatch.setattr(start, "_log_tail", lambda path, lines = 20: "API Key: sk-unsloth-abc123")monkeypatch.setattr(start.time, "sleep", lambda _s: None)- server = start._start_studio_server(+ returned_base, server = start._start_studio_server("http://127.0.0.1:8888","unsloth/Qwen3-1.7B-GGUF:UD-Q4_K_XL",start.LoadOptions(@@ -3920,6 +3922,7 @@ def test_start_studio_server_builds_command_and_waits(monkeypatch, capsys):assert captured["kwargs"]["env"][start._START_API_KEY_MARKER_ENV] == "1"assert start.os.environ[start._START_API_KEY_MARKER_ENV] == "parent"assert cmd[cmd.index("-p") + 1] == "8888"+ assert returned_base == "http://127.0.0.1:8888"assert start.LoadOptions().load_in_4bit is True and "--no-load-in-4bit" not in cmdassert captured["kwargs"].get("start_new_session") is True # own process groupassert server.pid == 4321@@ -3971,19 +3974,140 @@ def test_start_studio_server_polls_progress_from_early_key(monkeypatch):lambda message = "", **_kwargs: created.append(("echo", message)),)- server = start._start_studio_server(+ returned_base, server = start._start_studio_server(BASE,"owner/model-GGUF",start.LoadOptions(gguf_variant = "Q4_K_M"),)- assert server.pid == 4321+ assert (returned_base, server.pid) == (BASE, 4321)assert (BASE, "sk-unsloth-early", "owner/model-GGUF", "Q4_K_M", "created") in createdassert created.count("poll") == 2assert created[-2:] == ["complete", "close"]assert not any(isinstance(event, tuple) and "server ready" in event[-1] for event in created)+def test_start_studio_server_follows_the_port_the_child_bound(monkeypatch, tmp_path):+ requests = {"occupant": [], "studio": []}++ def handler(name, status, body):+ class Handler(http.server.BaseHTTPRequestHandler):+ def do_GET(self):+ requests[name].append(self.path)+ self.send_response(status)+ self.send_header("Content-Length", str(len(body)))+ self.end_headers()+ self.wfile.write(body)++ def log_message(self, *_args):+ pass++ return Handler++ occupant = http.server.ThreadingHTTPServer(("127.0.0.1", 0), handler("occupant", 404, b"{}"))+ studio = http.server.ThreadingHTTPServer(+ ("127.0.0.1", 0), handler("studio", 200, b'{"status": "healthy"}')+ )+ for httpd in (occupant, studio):+ threading.Thread(target = httpd.serve_forever, daemon = True).start()+ requested_port, bound_port = occupant.server_address[1], studio.server_address[1]+ fake = SimpleNamespace(pid = 4242, poll = lambda: None)+ commands = []+ progress_bases = []++ def fake_popen(command, **kwargs):+ commands.append(command)+ kwargs["stdout"].write(+ f"UNSLOTH_START_PORT: {bound_port}\n"+ "UNSLOTH_START_API_KEY: sk-unsloth-early\n"+ "Model loaded: owner/model\n".encode()+ )+ kwargs["stdout"].flush()+ return fake++ class FakeProgress:+ downloaded_bytes = 0++ def __init__(self, base, *_args):+ progress_bases.append(base)++ def poll(self):+ pass++ def complete(self):+ pass++ def close(self):+ pass++ monkeypatch.setattr(start.tempfile, "gettempdir", lambda: str(tmp_path))+ monkeypatch.setattr(start.subprocess, "Popen", fake_popen)+ monkeypatch.setattr(start, "_ModelDownloadProgress", FakeProgress)+ monkeypatch.setattr(start, "_SERVER_START_TIMEOUT_S", 5)+ try:+ base, server = start._start_studio_server(+ f"http://127.0.0.1:{requested_port}", "owner/model", start.LoadOptions()+ )+ finally:+ for httpd in (occupant, studio):+ httpd.shutdown()+ httpd.server_close()++ assert (base, server) == (f"http://127.0.0.1:{bound_port}", fake)+ assert commands[0][commands[0].index("-p") + 1] == str(requested_port)+ assert progress_bases == [base]+ assert requests == {"occupant": [], "studio": ["/api/health"]}+++def test_start_studio_server_reads_the_port_the_child_reported_once(monkeypatch):+ # The child reports its port once, before the loader pushes it out of the tail the key uses.+ class FakePopen:+ pid = 4321++ def poll(self):+ return None++ # 401 lines: the 400-line tail starts one line past the port.+ log = (+ "UNSLOTH_START_PORT: 8889\n"+ "UNSLOTH_START_API_KEY: sk-unsloth-early\n"+ + "loading tensors\n" * 398+ + "Model loaded: owner/model"+ )+ healthy = []+ progress_bases = []++ class FakeProgress:+ downloaded_bytes = 0++ def __init__(self, base, *_args):+ progress_bases.append(base)++ def poll(self):+ pass++ def complete(self):+ pass++ def close(self):+ pass++ monkeypatch.setattr(start.subprocess, "Popen", lambda *a, **k: FakePopen())+ monkeypatch.setattr(start, "_studio_healthy", lambda base, **_k: healthy.append(base) or True)+ monkeypatch.setattr(start, "_read_log", lambda _path: log)+ monkeypatch.setattr(start, "_log_tail", lambda *a, **k: "\n".join(log.splitlines()[-400:]))+ monkeypatch.setattr(start, "_ModelDownloadProgress", FakeProgress)+ monkeypatch.setattr(start.time, "sleep", lambda _s: None)++ base, _server = start._start_studio_server(BASE, "owner/model", start.LoadOptions())++ tail = "\n".join(log.splitlines()[-400:])+ assert start._START_API_KEY_PREFIX in tail and start._START_PORT_PREFIX not in tail+ assert base == "http://127.0.0.1:8889"+ assert progress_bases == [base]+ assert healthy == [base]++def test_load_model_with_progress_uses_selected_gguf_size(monkeypatch, capsys):release = start.threading.Event()calls = []@@ -4333,7 +4457,7 @@ def test_auto_serves_when_no_server_then_keeps_server(fake_studio, monkeypatch):):started.update(base = base, model = model, load = load)start._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(@@ -4359,6 +4483,29 @@ def test_auto_serves_when_no_server_then_keeps_server(fake_studio, monkeypatch):assert "unsloth studio stop" in result.output+def test_auto_served_session_uses_the_port_the_server_bound(fake_studio, monkeypatch):+ monkeypatch.setattr(start, "find_studio_server", lambda: None)+ bound = "http://127.0.0.1:8889"+ fake = SimpleNamespace(pid = 999, poll = lambda: None)+ launched = {}++ def fake_start(*_args):+ start._auto_served_server = fake+ return bound, fake++ monkeypatch.setattr(start, "_start_studio_server", fake_start)+ monkeypatch.setattr(start, "_launch", lambda command, env, **_kwargs: launched.update(env) or 0)++ result = CliRunner().invoke(start.start_app, ["claude", "--model", "unsloth/Qwen3-1.7B-GGUF"])++ assert result.exit_code == 0, result.output+ assert f"Unsloth ready at {bound} " in result.output+ assert launched["ANTHROPIC_BASE_URL"] == bound+ assert fake_studio and all(+ url.startswith(f"{bound}/") for _method, url, _payload in fake_studio+ )++def test_auto_served_agent_launch_failure_stops_server(fake_studio, monkeypatch):monkeypatch.setattr(start, "find_studio_server", lambda: None)stopped = []@@ -4366,7 +4513,7 @@ def test_auto_served_agent_launch_failure_stops_server(fake_studio, monkeypatch)def fake_start(*_args):start._auto_served_server = fake- return fake+ return _args[0], fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(start, "_shutdown_server", stopped.append)@@ -4392,7 +4539,7 @@ def test_auto_served_server_exit_is_not_reported_as_running(fake_studio, monkeypdef fake_start(*_args):start._auto_served_server = fake- return fake+ return _args[0], fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(start, "_launch", lambda *a, **k: 0)@@ -4496,7 +4643,7 @@ def test_codex_preflight_failure_tears_down_auto_served(fake_studio, monkeypatch):started.update(base = base, model = model)start._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(@@ -4596,7 +4743,7 @@ def test_auto_serve_normalizes_portless_url(fake_studio, monkeypatch):):started["base"] = basestart._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(start, "_shutdown_server", lambda server: None)@@ -5610,7 +5757,7 @@ def test_start_dsh_forwards_reasoning_effort(fake_studio, monkeypatch):):captured["server_options"] = server_optionsstart._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(start, "_shutdown_server", lambda server: None)@@ -8498,7 +8645,7 @@ def test_claude_post_connect_failure_tears_down_auto_served(fake_studio, monkeyp):started.update(base = base, model = model)start._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(@@ -8703,7 +8850,7 @@ def test_an_unreadable_status_leaves_the_auto_served_server_alone(fake_studio, m):started.update(base = base, model = model)start._auto_served_server = fake- return fake+ return base, fakemonkeypatch.setattr(start, "_start_studio_server", fake_start)monkeypatch.setattr(diff --git a/unsloth_cli/tests/test_studio_run_parallel_flag.py b/unsloth_cli/tests/test_studio_run_parallel_flag.pyindex d6e177b5333..56ed158473c 100644--- a/unsloth_cli/tests/test_studio_run_parallel_flag.py+++ b/unsloth_cli/tests/test_studio_run_parallel_flag.py@@ -305,6 +305,57 @@ def test_reexeced_child_consumes_start_api_key_marker_env(monkeypatch):assert studio_mod._START_API_KEY_MARKER_ENV not in studio_mod.os.environ+def test_in_venv_child_reports_bound_port_before_start_api_key(+ monkeypatch, tmp_path, stub_tool_policy_state+):+ import types++ studio_mod = _load_run_command()+ fake_venv = tmp_path / "studio" / "venv" / "unsloth_studio"+ monkeypatch.setattr(sys, "prefix", str(fake_venv))+ monkeypatch.setattr(studio_mod, "STUDIO_HOME", fake_venv.parent)++ from unsloth_cli import _tool_policy as _tp_mod++ monkeypatch.setattr(_tp_mod, "resolve_tool_policy", lambda host, flag, yes, silent: False)++ class _App:+ class state:+ server_port = 8889+ server_request_host = "127.0.0.1"++ backend = types.ModuleType("studio.backend.run")+ backend.run_server = lambda **_kwargs: _App()+ backend._server = object()+ backend._graceful_shutdown = lambda server: None+ monkeypatch.setitem(sys.modules, "studio.backend.run", backend)+ monkeypatch.setattr(studio_mod, "_RUN_MODULE", backend)+ monkeypatch.setattr(studio_mod, "_wait_for_server", lambda port, **_kwargs: True)+ monkeypatch.setattr(studio_mod, "_create_api_key_inprocess", lambda name: "sk-unsloth-test")++ def stop_before_load(**_kwargs):+ raise RuntimeError("stopped before load")++ monkeypatch.setattr(studio_mod, "_load_model_via_http", stop_before_load)++ import typer as _typer++ app = _typer.Typer()+ app.command(+ context_settings = {+ "allow_extra_args": True,+ "ignore_unknown_options": True,+ },+ )(studio_mod.run)+ result = CliRunner().invoke(+ app,+ _BASE + ["--port", "8888", "--start-api-key-marker"],+ catch_exceptions = True,+ )++ assert "UNSLOTH_START_PORT: 8889\nUNSLOTH_START_API_KEY: sk-unsloth-test\n" in result.output++def test_run_default_sets_tool_call_env(monkeypatch):"""Plain `unsloth run` enables healing and nudging via the inherited env(written before the re-exec so the child server picks them up at import)."""