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.

Desktop: allow a custom backend port with UNSLOTH_DESKTOP_PORT (#16523)

Daniel Hana68651efa845
diff --git a/README.md b/README.md
index 6dd58c91710..42b7a027812 100644
--- a/README.md
+++ b/README.md
@@ -162,6 +162,8 @@ Unsloth can be used in three ways: **[Unsloth Desktop](https://unsloth.ai/downlo
</tr>
</table>
+To choose Desktop's local HTTP port, set `UNSLOTH_DESKTOP_PORT=9000` in the environment that launches the app, then fully quit and reopen Desktop. Unset or empty keeps the default port 8888. If the selected port is busy, Desktop tries the next 20 ports. Choose a port between 1024 and 65515; Desktop rejects ranges containing a browser-restricted port. This setting applies to Desktop, including backend restarts after updates; it does not change the web UI's `unsloth studio -p` option or the separate LAN access port.
+
### Unsloth Studio (web UI)
#### macOS, Linux, WSL:
diff --git a/studio/src-tauri/src/desktop_backend_owner.rs b/studio/src-tauri/src/desktop_backend_owner.rs
index e0727e6219f..14016a26ffc 100644
--- a/studio/src-tauri/src/desktop_backend_owner.rs
+++ b/studio/src-tauri/src/desktop_backend_owner.rs
@@ -23,8 +23,6 @@ const STUDIO_INSTALL_ID_HEX_LEN: usize = 64;
const STUDIO_INSTALL_ID_BYTES: usize = STUDIO_INSTALL_ID_HEX_LEN / 2;
const STUDIO_INSTALL_ID_LOCK_FILE: &str = ".studio_install_id.lock";
const OWNER_TOKEN_BYTES: usize = 32;
-const DESKTOP_PORT_START: u16 = 8888;
-const DESKTOP_PORT_END: u16 = 8908;
const LOCAL_HTTP_TIMEOUT: Duration = Duration::from_secs(2);
#[derive(Clone, Debug)]
@@ -177,8 +175,13 @@ fn probe_credential(body: &[u8], secret: &str) -> Result<ProbeCredential, String
}
}
-pub(crate) fn desktop_candidate_ports() -> std::ops::RangeInclusive<u16> {
- DESKTOP_PORT_START..=DESKTOP_PORT_END
+pub(crate) fn desktop_candidate_ports() -> std::vec::IntoIter<u16> {
+ let configured = crate::desktop_port::configured_port(
+ std::env::var_os(crate::desktop_port::PORT_ENV).as_deref(),
+ )
+ .ok()
+ .flatten();
+ crate::desktop_port::discovery_ports(configured).into_iter()
}
pub(crate) fn is_valid_studio_root_id(value: &str) -> bool {
@@ -1027,7 +1030,7 @@ pub(crate) async fn probe_owned_backend_state_with_timeout(
) -> OwnedBackendProbe {
let ports: Vec<u16> = match port {
Some(port) => vec![port],
- None => desktop_candidate_ports().collect(),
+ None => crate::desktop_port::fallback_ports(owner.requested_port()).collect(),
};
probe_owned_backend_state_on_ports(owner, ports, require_desktop_secret, timeout).await
}
diff --git a/studio/src-tauri/src/desktop_port.rs b/studio/src-tauri/src/desktop_port.rs
new file mode 100644
index 00000000000..ec2e4363c43
--- /dev/null
+++ b/studio/src-tauri/src/desktop_port.rs
@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+use std::ffi::OsStr;
+
+pub(crate) const PORT_ENV: &str = "UNSLOTH_DESKTOP_PORT";
+// Fetch forbids these HTTP ports: https://fetch.spec.whatwg.org/#port-blocking
+const BROWSER_BLOCKED_PORTS: &[u16] = &[
+ 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669,
+ 6679, 6697, 10080,
+];
+
+pub(crate) fn configured_port(value: Option<&OsStr>) -> Result<Option<u16>, String> {
+ let Some(value) = value else {
+ return Ok(None);
+ };
+ let invalid = || {
+ format!("{PORT_ENV} must be between 1024 and 65515; the chosen port and its next 20 ports must be allowed by browsers.")
+ };
+ let value = value.to_str().ok_or_else(invalid)?.trim();
+ if value.is_empty() {
+ return Ok(None);
+ }
+ value
+ .parse::<u16>()
+ .ok()
+ .filter(|&port| {
+ (1024..=65515).contains(&port)
+ && fallback_ports(port).all(|candidate| !BROWSER_BLOCKED_PORTS.contains(&candidate))
+ })
+ .map(Some)
+ .ok_or_else(invalid)
+}
+
+pub(crate) fn resolve_port(requested: u16, value: Option<&OsStr>) -> Result<u16, String> {
+ Ok(configured_port(value)?.unwrap_or(requested))
+}
+
+pub(crate) fn fallback_ports(start: u16) -> std::ops::RangeInclusive<u16> {
+ start..=start.saturating_add(20)
+}
+
+pub(crate) fn discovery_ports(configured: Option<u16>) -> Vec<u16> {
+ let mut ports: Vec<u16> = configured.into_iter().flat_map(fallback_ports).collect();
+ for port in fallback_ports(8888) {
+ if !ports.contains(&port) {
+ ports.push(port);
+ }
+ }
+ ports
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn absent_or_empty_keeps_the_requested_port() {
+ for requested in [8888, 9010] {
+ for value in [None, Some(OsStr::new("")), Some(OsStr::new(" "))] {
+ assert_eq!(resolve_port(requested, value), Ok(requested));
+ }
+ }
+ }
+
+ #[test]
+ fn custom_port_is_stable_across_start_requests() {
+ for requested in [8888, 9010] {
+ for _ in 0..3 {
+ assert_eq!(
+ resolve_port(requested, Some(OsStr::new(" 9123 "))),
+ Ok(9123)
+ );
+ }
+ }
+ }
+
+ #[test]
+ fn invalid_ports_are_rejected() {
+ for value in [
+ "0",
+ "80",
+ "65516",
+ "65535",
+ "65536",
+ "-1",
+ "localhost:9000",
+ "abc",
+ ] {
+ assert!(resolve_port(8888, Some(OsStr::new(value))).is_err());
+ }
+ }
+
+ #[test]
+ fn every_accepted_fallback_is_browser_reachable_and_in_range() {
+ for port in 1..=u16::MAX {
+ if let Ok(Some(start)) = configured_port(Some(OsStr::new(&port.to_string()))) {
+ assert_eq!(start, port);
+ let candidates: Vec<_> = fallback_ports(start).collect();
+ assert_eq!(candidates.len(), 21);
+ assert!(candidates
+ .iter()
+ .all(|p| !BROWSER_BLOCKED_PORTS.contains(p)));
+ }
+ }
+ for port in [1024, 3000, 8080, 9000, 65515] {
+ assert_eq!(
+ configured_port(Some(OsStr::new(&port.to_string()))),
+ Ok(Some(port))
+ );
+ }
+ for port in BROWSER_BLOCKED_PORTS {
+ for offset in 0..=20 {
+ assert!(configured_port(Some(OsStr::new(&(port - offset).to_string()))).is_err());
+ }
+ }
+ }
+
+ #[test]
+ fn default_discovery_is_unchanged() {
+ assert_eq!(discovery_ports(None), (8888..=8908).collect::<Vec<_>>());
+ assert_eq!(discovery_ports(Some(8888)), discovery_ports(None));
+ }
+
+ #[test]
+ fn custom_discovery_keeps_fallback_and_existing_backends() {
+ let ports = discovery_ports(Some(19000));
+ assert_eq!(&ports[..21], (19000..=19020).collect::<Vec<_>>());
+ assert_eq!(&ports[21..], (8888..=8908).collect::<Vec<_>>());
+ assert_eq!(discovery_ports(Some(8890)).len(), 23);
+ assert_eq!(fallback_ports(65535).collect::<Vec<_>>(), vec![65535]);
+ }
+}
diff --git a/studio/src-tauri/src/main.rs b/studio/src-tauri/src/main.rs
index f5981057bd7..54a372d1790 100644
--- a/studio/src-tauri/src/main.rs
+++ b/studio/src-tauri/src/main.rs
@@ -19,6 +19,7 @@ mod commands;
mod debian_update;
mod desktop_auth;
mod desktop_backend_owner;
+mod desktop_port;
mod desktop_update_policy;
mod desktop_updater;
mod diagnostics;
diff --git a/studio/src-tauri/src/process.rs b/studio/src-tauri/src/process.rs
index 87ecb0309a0..806b5de109c 100644
--- a/studio/src-tauri/src/process.rs
+++ b/studio/src-tauri/src/process.rs
@@ -3244,6 +3244,10 @@ pub fn start_backend(
shutdown: &ShutdownFlag,
diagnostics_state: &DiagnosticsState,
) -> Result<u64, String> {
+ let port = crate::desktop_port::resolve_port(
+ port,
+ std::env::var_os(crate::desktop_port::PORT_ENV).as_deref(),
+ )?;
let _runtime_launch_guard = acquire_studio_runtime_launch_guard()?;
// Checked on the spawn path: a webview remount can start a backend while the job is disarmed.
diff --git a/tests/python/test_desktop_port.py b/tests/python/test_desktop_port.py
new file mode 100644
index 00000000000..21506791e1d
--- /dev/null
+++ b/tests/python/test_desktop_port.py
@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SRC = ROOT / "studio" / "src-tauri" / "src"
+
+
+def _function(source, name):
+ start = source.index(f"fn {name}(")
+ return source[start : source.index("\n}", start) + 2]
+
+
[email protected](scope = "module")
+def desktop_port_binary(tmp_path_factory):
+ rustc = shutil.which("rustc")
+ assert rustc is not None, "rustc is required to exercise the Desktop launch code"
+ scratch = tmp_path_factory.mktemp("desktop-port")
+ process = (SRC / "process.rs").read_text(encoding = "utf-8")
+ owner = (SRC / "desktop_backend_owner.rs").read_text(encoding = "utf-8")
+ start = process.index("pub fn start_backend(")
+ start = process.index("{", start) + 1
+ prefix = process[start : process.index("let _runtime_launch_guard", start)]
+ probe = _function(owner, "probe_owned_backend_state_with_timeout")
+ owner_prefix = probe[
+ probe.index("{") + 1 : probe.index(" probe_owned_backend_state_on_ports")
+ ]
+ module = SRC / "desktop_port.rs"
+ modules = f'#[path = "{module.as_posix()}"] mod desktop_port;\n' if module.exists() else ""
+ constants = "\n".join(re.findall(r"^const DESKTOP_PORT_.*;$", owner, re.MULTILINE))
+ source = (
+ modules
+ + constants
+ + "\n"
+ + _function(process, "backend_args")
+ + "\n"
+ + _function(owner, "desktop_candidate_ports")
+ + "\nfn launch_port(port: u16) -> Result<u16, String> {"
+ + prefix
+ + "Ok(port)}\n"
+ + "struct Owner(u16); impl Owner { fn requested_port(&self) -> u16 { self.0 } }\n"
+ + "fn owned_ports(port: Option<u16>) -> Vec<u16> { let owner = Owner(9123);"
+ + owner_prefix
+ + "ports}\n"
+ + "fn main() { match launch_port(8888) { Ok(port) => { "
+ + 'println!("{}", backend_args(port).join("|")); '
+ + 'println!("{}", desktop_candidate_ports().map(|p| p.to_string()).collect::<Vec<_>>().join(",")); '
+ + 'if std::env::args().nth(1).as_deref() == Some("owner") { '
+ + 'println!("{:?}", owned_ports(None)); } '
+ + '}, Err(error) => {eprintln!("{error}"); std::process::exit(2);} } }\n'
+ )
+ path = scratch / "main.rs"
+ path.write_text(source, encoding = "utf-8")
+ binary = scratch / ("desktop-port.exe" if os.name == "nt" else "desktop-port")
+ result = subprocess.run(
+ [rustc, "--edition=2021", str(path), "-o", str(binary)],
+ text = True,
+ capture_output = True,
+ )
+ assert result.returncode == 0, result.stderr
+ return binary
+
+
+def _run(binary, value):
+ env = os.environ.copy()
+ env.pop("UNSLOTH_DESKTOP_PORT", None)
+ if value is not None:
+ env["UNSLOTH_DESKTOP_PORT"] = value
+ return subprocess.run([str(binary)], env = env, capture_output = True, text = True)
+
+
[email protected]("value", [None, "", " "])
+def test_default_launch_and_discovery_unchanged(desktop_port_binary, value):
+ result = _run(desktop_port_binary, value)
+ assert result.returncode == 0, result.stderr
+ argv, ports = result.stdout.strip().splitlines()
+ assert argv == "studio|--api-only|-H|127.0.0.1|-p|8888"
+ assert [int(port) for port in ports.split(",")] == list(range(8888, 8909))
+
+
+def test_custom_port_reaches_child_argv_and_discovery_on_repeated_launch(desktop_port_binary):
+ for _ in range(3):
+ result = _run(desktop_port_binary, " 9123 ")
+ assert result.returncode == 0, result.stderr
+ argv, ports = result.stdout.strip().splitlines()
+ assert argv == "studio|--api-only|-H|127.0.0.1|-p|9123"
+ discovered = [int(port) for port in ports.split(",")]
+ assert set(range(9123, 9144)).issubset(discovered)
+ assert set(range(8888, 8909)).issubset(discovered)
+ assert len(discovered) == len(set(discovered))
+
+
+ "value", ["0", "65536", "-1", "localhost:9123", "6000", "5999", "10080", "65535"]
+)
+def test_invalid_override_does_not_launch(desktop_port_binary, value):
+ result = _run(desktop_port_binary, value)
+ assert result.returncode == 2
+ assert result.stdout == ""
+ assert "UNSLOTH_DESKTOP_PORT" in result.stderr
+
+
+def test_portless_owner_uses_its_recorded_request_after_env_is_removed(desktop_port_binary):
+ env = os.environ.copy()
+ env.pop("UNSLOTH_DESKTOP_PORT", None)
+ result = subprocess.run(
+ [str(desktop_port_binary), "owner"], env = env, capture_output = True, text = True
+ )
+ assert result.returncode == 0, result.stderr
+ assert result.stdout.splitlines()[-1] == str(list(range(9123, 9144)))