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
export type LanAccessState = "off" | "online" | "error";
export type LanAccessOwner = "launch" | "settings" | null;
export type LanKeylessScope = "off" | "inference" | "full";
export type LanAccessAddress = {
address: string;
public: boolean;
hostOnly?: boolean;
};
type ApiLanAccessAddress = {
address: string;
public: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
host_only?: boolean;
};
export type LanAccessAddressChoice = LanAccessAddress & { detected: boolean };
export type LanAccessStatus = {
state: LanAccessState;
urls: string[];
publicUrls: string[];
error: string | null;
autoStart: boolean;
portConfigurationSupported: boolean;
configuredPort: number | null;
activePort: number | null;
addressConfigurationSupported: boolean;
// null is Automatic: every detected address, public ones included
configuredAddresses: string[] | null;
availableAddresses: LanAccessAddress[];
configuredPublicAddresses: string[];
managedBy: LanAccessOwner;
canStart: boolean;
canStop: boolean;
blockReason: string | null;
bindHost: string | null;
wildcardBind: boolean;
servesWebUi: boolean;
keylessLanEligible: boolean;
keylessScope: LanKeylessScope;
keylessTools: boolean;
};
export type ApiLanAccessStatus = {
state: LanAccessState;
urls?: string[] | null;
// biome-ignore lint/style/useNamingConvention: API schema
public_urls?: string[] | null;
error?: string | null;
// biome-ignore lint/style/useNamingConvention: API schema
auto_start: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
configured_port?: number | null;
// biome-ignore lint/style/useNamingConvention: API schema
active_port?: number | null;
// biome-ignore lint/style/useNamingConvention: API schema
configured_addresses?: string[] | null;
// biome-ignore lint/style/useNamingConvention: API schema
available_addresses?: ApiLanAccessAddress[] | null;
// biome-ignore lint/style/useNamingConvention: API schema
configured_public_addresses?: string[] | null;
// biome-ignore lint/style/useNamingConvention: API schema
managed_by?: LanAccessOwner;
// biome-ignore lint/style/useNamingConvention: API schema
can_start: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
can_stop: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
block_reason?: string | null;
// biome-ignore lint/style/useNamingConvention: API schema
bind_host?: string | null;
// biome-ignore lint/style/useNamingConvention: API schema
wildcard_bind?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
serves_web_ui?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
keyless_lan_eligible?: boolean | null;
// biome-ignore lint/style/useNamingConvention: API schema
keyless_scope?: LanKeylessScope | string | null;
// biome-ignore lint/style/useNamingConvention: API schema
keyless_tools?: boolean | null;
};
function normalizeAddresses(value: unknown): LanAccessAddress[] {
if (!Array.isArray(value)) {
return [];
}
return value.flatMap((entry) =>
entry && typeof entry.address === "string"
? [
{
address: entry.address,
public: entry.public === true,
...(entry.host_only === true ? { hostOnly: true } : {}),
},
]
: [],
);
}
function normalizeKeylessScope(value: unknown): LanKeylessScope {
return value === "inference" || value === "full" ? value : "off";
}
export function normalizeLanAccessStatus(
status: ApiLanAccessStatus,
): LanAccessStatus {
const keylessScope = normalizeKeylessScope(status.keyless_scope);
return {
state: status.state,
urls: Array.isArray(status.urls) ? status.urls : [],
publicUrls: Array.isArray(status.public_urls) ? status.public_urls : [],
error: status.error ?? null,
autoStart: status.auto_start,
portConfigurationSupported: Object.hasOwn(status, "configured_port"),
configuredPort:
typeof status.configured_port === "number"
? status.configured_port
: null,
activePort:
typeof status.active_port === "number" ? status.active_port : null,
addressConfigurationSupported: Object.hasOwn(
status,
"configured_addresses",
),
configuredAddresses: Array.isArray(status.configured_addresses)
? status.configured_addresses.filter(
(address) => typeof address === "string",
)
: null,
availableAddresses: normalizeAddresses(status.available_addresses),
configuredPublicAddresses: Array.isArray(status.configured_public_addresses)
? status.configured_public_addresses.filter(
(address) => typeof address === "string",
)
: [],
managedBy: status.managed_by ?? null,
canStart: status.can_start,
canStop: status.can_stop,
blockReason: status.block_reason ?? null,
bindHost: status.bind_host ?? null,
wildcardBind: status.wildcard_bind === true,
// older backends omit this field but still serve the web UI
servesWebUi: status.serves_web_ui !== false,
keylessLanEligible: status.keyless_lan_eligible === true,
keylessScope,
keylessTools: keylessScope !== "off" && status.keyless_tools === true,
};
}
// launch binds (-H 0.0.0.0, Docker) often use forwarded localhost ports
export function lanApiUrls(status: LanAccessStatus): string[] {
return status.managedBy === "settings" ? status.urls : [];
}
// A listener keeps the address it bound after Wi-Fi changes or DHCP renews, while detection is fresh.
export function staleLanUrls(status: LanAccessStatus): string[] {
if (
status.managedBy !== "settings" ||
status.availableAddresses.length === 0
) {
return [];
}
const present = new Set(
status.availableAddresses.map((entry) => entry.address),
);
return status.urls.filter((url) => {
try {
return !present.has(new URL(url).hostname.replace(/^\[|\]$/g, ""));
} catch {
return false;
}
});
}
export function keylessLanAccessDescription(
status: LanAccessStatus | null,
): string {
if (!status || status.keylessScope === "off") {
return "Authentication is required for LAN API requests.";
}
if (status.blockReason === "colab") {
return "Colab never receives keyless access, regardless of the saved scope.";
}
if (status.keylessScope === "full") {
return "Full keyless access is localhost-only and is never granted over LAN or public URLs.";
}
const tools = status.keylessTools
? " Agent tools are separately enabled."
: " Agent tools remain off unless separately granted.";
if (status.keylessLanEligible && status.publicUrls.length > 0) {
return `Inference can be keyless on localhost and an active private LAN, but never through the listed public URL.${tools}`;
}
if (status.keylessLanEligible) {
return `Inference can be keyless on localhost and this active private LAN.${tools}`;
}
return `Inference is keyless on localhost; LAN callers require an active private listener.${tools}`;
}
export const LAN_ACCESS_POLL_MS = 5000;
export function lanAccessAutoStartReadOnly(
status: LanAccessStatus | null,
): boolean {
return status === null || status.blockReason === "colab";
}
export function lanAccessPortReadOnly(status: LanAccessStatus | null): boolean {
return (
status === null ||
!status.portConfigurationSupported ||
status.state === "online" ||
status.blockReason === "colab"
);
}
export function lanAccessAddressesReadOnly(
status: LanAccessStatus | null,
): boolean {
return (
status === null ||
!status.addressConfigurationSupported ||
status.state === "online" ||
status.blockReason === "colab"
);
}
export function lanAccessAddressChoices(
status: LanAccessStatus | null,
selected: string[],
): LanAccessAddressChoice[] {
const detected = status?.availableAddresses ?? [];
// a -H launch skips detection, so an address missing from the list is unknown, not down
const detectionSkipped = status?.managedBy === "launch";
const choices: LanAccessAddressChoice[] = detected.map((entry) => ({
...entry,
detected: true,
}));
for (const address of [...(status?.configuredAddresses ?? []), ...selected]) {
if (!choices.some((choice) => choice.address === address)) {
choices.push({
address,
public: status?.configuredPublicAddresses.includes(address) ?? false,
detected: detectionSkipped,
});
}
}
return choices;
}
export function defaultLanAccessAddressSelection(
status: LanAccessStatus | null,
): string[] {
return (status?.availableAddresses ?? [])
.filter((entry) => !(entry.public || entry.hostOnly))
.map((entry) => entry.address);
}
export function sameLanAccessAddresses(
left: string[] | null,
right: string[] | null,
): boolean {
if (left === null || right === null) {
return left === right;
}
const a = new Set(left);
const b = new Set(right);
return a.size === b.size && [...a].every((address) => b.has(address));
}
export function validLanAccessPort(value: string): boolean {
const port = Number(value);
return Number.isInteger(port) && port >= 1 && port <= 65535;
}
export function lanAccessStopDisconnectsOrigin(
urls: string[],
browserOrigin: string,
): boolean {
let origin: string;
try {
origin = new URL(browserOrigin).origin;
} catch {
return false;
}
return urls.some((url) => {
try {
return new URL(url).origin === origin;
} catch {
return false;
}
});
}
function launchManagedMessage(status: LanAccessStatus): string {
if (status.wildcardBind) {
const option = status.bindHost ? ` (--host ${status.bindHost})` : "";
return `This launch binds every network interface${option}, so Unsloth is on the network already.`;
}
if (!status.bindHost) {
return "This launch already puts Unsloth on the network.";
}
return `This launch binds ${status.bindHost} (--host ${status.bindHost}), so Unsloth is on the network already.`;
}
export function lanAccessBlockMessage(
status: LanAccessStatus | null,
isDesktop: boolean,
): string | null {
switch (status?.blockReason) {
case "server_starting":
return "Unsloth is still starting.";
case "admin_password_change_required":
return isDesktop
? "Set a remote password before putting this server on the network."
: "Change the administrator password before putting this server on the network. In the desktop app, run unsloth studio reset-password.";
case "launch_managed":
return launchManagedMessage(status);
case "secure_launch":
return "This launch used --secure, which serves only through the Cloudflare link and keeps the raw port closed. Relaunch without --secure to use LAN access.";
case "colab":
return "LAN access is managed by the Colab runtime, which has no local network to join.";
default:
return null;
}
}
export function lanAccessErrorMessage(
error: string | null,
configuredPort: number | null = null,
): string | null {
switch (error) {
case "no_lan_address":
return "No network address found. Connect this machine to Wi-Fi or a wired network, then try again.";
case "bind_failed":
return configuredPort === null
? "Could not open any automatic LAN port from 8888 to 8908."
: `Port ${configuredPort} is unavailable. Stop the app using it or choose another custom port.`;
case "selected_address_unavailable":
return "None of the chosen addresses is on this machine right now. Connect that network, or choose another address.";
case "listener_start_failed":
return "The network listener did not start. Check the logs for details.";
case "stop_timed_out":
return "LAN access could not confirm the port closed. Check the logs, then try again.";
case null:
case undefined:
return null;
default:
return "LAN access failed to start.";
}
}