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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Extra LAN listener on each detected address, not 0.0.0.0 (collides with loopback); lifespan=off
so startup and shutdown stay with primary and never fire twice; settings listener IPv4 only;
link-local IPv6 omitted."""
from __future__ import annotations
import asyncio
import functools
import errno
import ipaddress
import platform
import re
import socket
import subprocess
import sys
import threading
import time
from typing import Any, Optional
import uvicorn
from loggers import get_logger
from utils.host_policy import set_lan_connector_active
logger = get_logger(__name__)
# local socket work either way, so exceeding these means the event loop is wedged
_START_TIMEOUT = 10.0
# kept under the ~5s Windows console-close budget run.py's shutdown path works to
_STOP_TIMEOUT = 3.0
# accepted LAN requests stay remote callers; on expiry the trust flag stays active
_DRAIN_TIMEOUT = 300.0
# networking mode rarely changes, but a failed wslinfo probe must eventually recover
_WSL_MODE_CACHE_TTL = 60.0
# uvicorn's own default, so a burst queues on the LAN socket as it does on loopback
_LISTEN_BACKLOG = 2048
_lock = threading.RLock()
_wsl_mode_lock = threading.Lock()
_wsl_mode_cache: Optional[tuple[float, str]] = None
_server: Any = None
_serve_loop: Any = None
_sockets: tuple[socket.socket, ...] = ()
_port: Optional[int] = None
_error: Optional[str] = None
# the trust flag stays up until every stopped listener's accepted requests have drained
_pending_drains = 0
# rebound whole, never mutated: request_on_lan_listener reads it without the lock
_bound_addresses: tuple[str, ...] = ()
def detect_lan_addresses(ip_version: int = 4) -> list[str]:
"""Loopback, link-local and multicast are dropped; public addresses are kept for the caller to
decide."""
# WSL NAT addresses sit on a private Hyper-V network other devices cannot reach
if _wsl_networking_mode() not in (None, "mirrored"):
return []
if ip_version == 4:
socket_family = socket.AF_INET
route_probe = ("8.8.8.8", 80)
elif ip_version == 6:
socket_family = socket.AF_INET6
route_probe = ("2001:4860:4860::8888", 80, 0, 0)
else:
raise ValueError("ip_version must be 4 or 6")
found: list[str] = []
# a UDP connect only fixes the local end of the socket; nothing is sent to the target
probe = None
try:
probe = socket.socket(socket_family, socket.SOCK_DGRAM)
probe.connect(route_probe)
found.append(probe.getsockname()[0])
except OSError:
pass
finally:
if probe is not None:
probe.close()
# Route probes and hostname lookup miss other adapters; an isolated LAN has no route at all.
found.extend(_interface_addresses(ip_version))
return _usable_addresses(found, ip_version)
def detect_host_only_addresses(ip_version: int = 4, carrier: bool = True) -> list[str]:
"""Addresses on virtual switches (libvirt, Docker, ...) that detection skips: offered for an explicit
choice, e.g. serving VMs on virbr0 (#17017), never bound by Automatic. ``carrier=False`` adds
bridges no guest is attached to yet, whose assigned address still binds."""
if _wsl_networking_mode() not in (None, "mirrored"):
return []
return _usable_addresses(
_interface_addresses(ip_version, host_only = True, carrier = carrier), ip_version
)
def _usable_addresses(found, ip_version: int) -> list[str]:
addresses: list[str] = []
for candidate in found:
try:
parsed = ipaddress.ip_address(candidate.split("%", 1)[0])
except ValueError:
continue
if parsed.version != ip_version:
continue
if parsed.is_loopback or parsed.is_link_local or parsed.is_multicast:
continue
if parsed.is_unspecified or parsed.is_reserved:
continue
normalized = str(parsed)
if normalized not in addresses:
addresses.append(normalized)
return addresses
def _wsl_networking_mode() -> Optional[str]:
"""Older WSL without wslinfo is unknown and not advertised, since older releases use NAT."""
global _wsl_mode_cache
if sys.platform != "linux" or "microsoft" not in platform.release().casefold():
return None
with _wsl_mode_lock:
now = time.monotonic()
cached = _wsl_mode_cache
if cached is not None and now - cached[0] < _WSL_MODE_CACHE_TTL:
return cached[1]
try:
result = subprocess.run(
["wslinfo", "--networking-mode"],
capture_output = True,
check = False,
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 1,
)
except (OSError, subprocess.SubprocessError):
mode = "unknown"
else:
mode = result.stdout.strip().casefold() or "unknown"
_wsl_mode_cache = (time.monotonic(), mode)
return mode
def _is_host_only_interface(name: str) -> bool:
"""True for virtual switches (Hyper-V, Docker, libvirt, VirtualBox, VMware) that do not face the physical LAN."""
normalized = name.strip().casefold()
# br-<12 hex> is a Docker network; a plain br0 is often the host's real LAN bridge, so it stays.
if normalized.startswith(("docker0", "virbr", "vboxnet", "vmnet")) or re.fullmatch(
r"br-[0-9a-f]{12}", normalized
):
return True
if not normalized.startswith("vethernet ("):
return False
return any(
marker in normalized
for marker in ("default switch", "wsl", "hyper-v firewall", "host-only")
)
def _interface_addresses(
ip_version: int = 4,
host_only: bool = False,
carrier: bool = True,
) -> list[str]:
"""Up interfaces, or every virtual switch when ``host_only``. Without psutil, hostname lookup is a
last resort: it misses hosts whose name maps to 127.0.1.1."""
try:
import psutil
except ImportError:
if host_only:
return []
try:
return [
info[4][0]
for info in socket.getaddrinfo(
socket.gethostname(),
None,
socket.AF_INET if ip_version == 4 else socket.AF_INET6,
)
]
except OSError:
return []
try:
stats = psutil.net_if_stats()
family = socket.AF_INET if ip_version == 4 else socket.AF_INET6
addresses = []
for name, entries in psutil.net_if_addrs().items():
if _is_host_only_interface(name) != host_only:
continue
interface = stats.get(name)
if carrier and interface is not None and not interface.isup:
continue
addresses.extend(e.address for e in entries if e.family == family)
return addresses
except Exception:
return []
def is_public_address(address: str) -> bool:
"""A VPS may carry a public IPv4 on its NIC, so callers surface that rather than refuse it."""
try:
return ipaddress.ip_address(address).is_global
except ValueError:
return False
def _already_served(address: str, port: int) -> bool:
try:
with socket.create_connection((address, port), timeout = 0.2):
return True
except OSError:
return False
def _bind_listener(address: str, port: int) -> socket.socket:
"""A listening socket on exactly ``address:port``."""
if sys.platform == "darwin" and _already_served(address, port):
# BSD SO_REUSEADDR binds under another app's 0.0.0.0 listener and steals its LAN traffic.
raise OSError(errno.EADDRINUSE, f"{address}:{port} is already served")
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
# skipped on Windows, where SO_REUSEADDR lets a socket take over a live listener
if sys.platform != "win32":
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
sock.bind((address, port))
sock.listen(_LISTEN_BACKLOG)
sock.set_inheritable(False)
except BaseException:
sock.close()
raise
return sock
def _listener_config(app, host: str, port: int):
from utils.forwarded_headers import uvicorn_forwarded_kwargs
from utils.uvicorn_h11_shutdown import uvicorn_http_protocol
# a TLS launch must not reopen plain HTTP on the network
tls = getattr(getattr(app, "state", None), "studio_tls", None)
if tls is not None:
from utils.studio_tls import StudioTLSConfig
config_class = functools.partial(StudioTLSConfig, tls = tls)
else:
config_class = uvicorn.Config
return config_class(
app,
host = host,
port = port,
# a second lifespan would re-fire the app's startup handlers
lifespan = "off",
# uvicorn.Config applies log_config eagerly, resetting run.py's startup log rewrite
log_config = None,
access_log = False,
server_header = False,
http = uvicorn_http_protocol(),
**uvicorn_forwarded_kwargs(is_colab = False),
)
def _running_on_event_loop() -> bool:
"""True when the caller is already inside a running event loop."""
try:
asyncio.get_running_loop()
except RuntimeError:
return False
return True
def _wait_until(predicate, timeout: float) -> bool:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
if predicate():
return True
time.sleep(0.01)
return predicate()
def start_lan_listener(
app,
loop,
port: int,
fallback_ports: tuple[int, ...] = (),
selected_addresses: Optional[tuple[str, ...]] = None,
) -> tuple[str, ...]:
"""Serve ``app`` on LAN addresses at the first bindable candidate port; ``selected_addresses=None`` binds all."""
global _server, _serve_loop, _sockets, _bound_addresses, _port, _error
with _lock:
if _server is not None:
return _bound_addresses
candidates = detect_lan_addresses()
if selected_addresses is not None:
# a saved virbr0 must bind at launch, before any VM has started
candidates += [
a for a in detect_host_only_addresses(carrier = False) if a not in candidates
]
if not candidates:
_error = "no_lan_address"
raise RuntimeError(_error)
if selected_addresses is not None:
# never widened back to the detected set: that would bind the addresses the user excluded
missing = [address for address in selected_addresses if address not in candidates]
candidates = [address for address in candidates if address in selected_addresses]
if not candidates:
_error = "selected_address_unavailable"
logger.warning(
"LAN access found none of the chosen addresses on this machine: %s",
", ".join(selected_addresses),
)
raise RuntimeError(_error)
if missing:
logger.info(
"LAN access skipped chosen addresses not on this machine: %s",
", ".join(missing),
)
sockets: list[socket.socket] = []
bound: list[str] = []
failures: list[str] = []
attempted: list[str] = []
for candidate_port in (port, *fallback_ports):
sockets = []
bound = []
failures = []
for address in candidates:
try:
sockets.append(_bind_listener(address, candidate_port))
except OSError as exc:
failures.append(f"{address}:{candidate_port} ({exc})")
continue
bound.append(address)
if sockets:
port = candidate_port
break
attempted.extend(failures)
if not sockets:
_error = "bind_failed"
logger.warning("LAN access could not bind: %s", "; ".join(attempted))
raise RuntimeError(_error)
if failures:
logger.info("LAN access skipped unbindable addresses: %s", "; ".join(failures))
server = uvicorn.Server(_listener_config(app, bound[0], port))
# published before accept, else a request in between reads loopback-only trust
set_lan_connector_active(True)
serving = server.serve(sockets = sockets)
try:
future = asyncio.run_coroutine_threadsafe(serving, loop)
except RuntimeError as exc:
# the loop can close between _server_loop validating it and this call
serving.close()
_fail_start(sockets, port, exc)
raise RuntimeError(_error) from exc
started = _wait_until(lambda: server.started or future.done(), _START_TIMEOUT)
if not started or not server.started:
server.should_exit = True
cause = future.exception(timeout = 0) if future.done() else None
future.cancel()
_fail_start(sockets, port, cause if cause is not None else "timed out")
raise RuntimeError(_error)
_server, _serve_loop, _sockets = server, loop, tuple(sockets)
_bound_addresses, _port, _error = tuple(bound), port, None
logger.info("LAN access listening on %s", ", ".join(f"{a}:{port}" for a in bound))
return _bound_addresses
def _sync_lan_trust() -> None:
"""Derive the beyond-loopback flag from server and drain state rather than caller assignment;
caller must hold _lock; racing stops cannot clear it early"""
set_lan_connector_active(_server is not None or _pending_drains > 0)
def _release_listener_state() -> None:
"""Drop the listener references. The caller holds ``_lock``."""
global _server, _serve_loop, _sockets, _port
_server = _serve_loop = None
_sockets = ()
_port = None
_sync_lan_trust()
def _fail_start(sockets, port: int, cause) -> None:
"""Undo a start that never came up. The caller holds ``_lock``."""
global _error
_close_sockets(sockets)
_sync_lan_trust()
_error = "listener_start_failed"
logger.warning("LAN access listener did not start on port %s: %s", port, cause)
def _arm_drain_watcher(server) -> None:
"""Own the trust flag until ``server``'s accepted requests end. Caller holds ``_lock``."""
global _pending_drains
_pending_drains += 1
threading.Thread(
target = _clear_trust_after_drain,
args = (server,),
name = "lan-access-drain",
daemon = True,
).start()
def _clear_trust_after_drain(server) -> None:
"""Keep LAN trust until drained requests finish: a LAN request stays a remote caller its whole life."""
global _pending_drains
state = getattr(server, "server_state", None)
deadline = time.monotonic() + _DRAIN_TIMEOUT
while state is not None and state.connections and time.monotonic() < deadline:
time.sleep(0.05)
with _lock:
if state is not None and state.connections:
# ownership is never given up: a request that never ended is still remote
logger.warning("LAN access kept the trust flag on: connections did not drain")
return
_pending_drains -= 1
_sync_lan_trust()
def _close_sockets(sockets) -> None:
for sock in sockets:
try:
sock.close()
except OSError:
pass
def stop_lan_listener() -> bool:
"""Waits for sockets, not serve(): a LAN Stop would otherwise wait out its own in-flight response."""
global _server, _serve_loop, _sockets, _bound_addresses, _port, _error
# a stop on the loop itself must not block on _lock held by a waiting start
if not _lock.acquire(blocking = not _running_on_event_loop()):
logger.info("LAN access stop deferred: a listener change is in flight")
return False
# held across the wait so a start cannot begin rebinding sockets still closing
try:
server, loop, sockets = _server, _serve_loop, _sockets
port = _port
# closed before the wait so a request landing mid-teardown already reads as off
_bound_addresses = ()
if server is None:
_release_listener_state()
return True
server.should_exit = True
if _running_on_event_loop():
# /api/shutdown runs on this loop, so waiting would deadlock; ownership is kept
logger.info("LAN access stopping")
return True
if loop is None or loop.is_closed() or not loop.is_running():
# nothing is left to run uvicorn's shutdown, so release the sockets here
_close_sockets(sockets)
_release_listener_state()
logger.info("LAN access stopped with its server loop")
return True
if _wait_until(lambda: all(sock.fileno() == -1 for sock in sockets), _STOP_TIMEOUT):
# armed before the release so the flag is never briefly unowned
_arm_drain_watcher(server)
_release_listener_state()
logger.info("LAN access stopped")
return True
# ownership kept: a retry waits on these sockets and a second stop cannot report success
_error = "stop_timed_out"
logger.warning("LAN access did not release port %s within %ss", port, _STOP_TIMEOUT)
return False
finally:
_lock.release()
def lan_listener_status() -> dict:
"""Runtime view of the listener: whether it serves, where, and why not."""
with _lock:
return {
"running": _server is not None,
"addresses": list(_bound_addresses),
"port": _port,
"error": _error,
}
def clear_lan_listener_error() -> None:
"""Drop a recorded failure so a retry starts from a clean status."""
global _error
with _lock:
_error = None
def request_on_lan_listener(scope) -> bool:
"""True if the request came in on a LAN listener rather than loopback; judged from the accepting
socket address in scope, never a client header"""
addresses = _bound_addresses
if not addresses:
return False
server = scope.get("server")
return bool(server) and server[0] in addresses
def close_lan_listener_lifecycle() -> None:
"""Shutdown hook: never raise, whatever state the listener is in."""
try:
stop_lan_listener()
except Exception as exc:
logger.warning("Error stopping the LAN listener: %s", exc)