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.

11.9 KB
Raw Blame
// 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.";
  }
}