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.

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.py
index 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 False
def 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.py
index 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, mon
assert [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.py
index 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 itertools
import json
import os
import 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.request
base = 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 candidate
except Exception:
continue
return None
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index 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] = None
downloaded_bytes = 0
early_key_seen = False
+ port_followed = False
try:
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, server
time.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.py
index 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 = record
created_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.py
index 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.py
index 37c323372f6..4f876bd9b94 100644
--- a/unsloth_cli/tests/test_start.py
+++ b/unsloth_cli/tests/test_start.py
@@ -6,6 +6,7 @@
from __future__ import annotations
import http.client
+import http.server
import io
import json
import os
@@ -13,6 +14,7 @@ import re
import shlex
import signal
import sys
+import threading
import time
import urllib.error
from pathlib import Path
@@ -3041,7 +3043,7 @@ def test_start_positional_model_routes_to_model_on_auto_serve(fake_studio, monke
captured["load"] = load
captured["server_options"] = server_options
start._auto_served_server = fake
- return fake
+ return base, fake
monkeypatch.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"] = load
start._auto_served_server = fake
- return fake
+ return base, fake
monkeypatch.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_options
start._auto_served_server = fake
- return fake
+ return base, fake
monkeypatch.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 cmd
assert captured["kwargs"].get("start_new_session") is True # own process group
assert 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 created
assert created.count("poll") == 2
assert 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, fake
monkeypatch.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], fake
monkeypatch.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, monkeyp
def fake_start(*_args):
start._auto_served_server = fake
- return fake
+ return _args[0], fake
monkeypatch.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, fake
monkeypatch.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"] = base
start._auto_served_server = fake
- return fake
+ return base, fake
monkeypatch.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_options
start._auto_served_server = fake
- return fake
+ return base, fake
monkeypatch.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, fake
monkeypatch.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, fake
monkeypatch.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.py
index 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)."""