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: limit model download speed (#16819)

Nilayfa78cf69488f
diff --git a/studio/backend/hub/schemas/downloads.py b/studio/backend/hub/schemas/downloads.py
index 1006b1cf292..0f3d6611c7b 100644
--- a/studio/backend/hub/schemas/downloads.py
+++ b/studio/backend/hub/schemas/downloads.py
@@ -143,6 +143,8 @@ class TransportCapabilities(BaseModel):
auto_reason: Optional[str] = None
# False when huggingface_hub refetches interrupted files from zero; no transport can byte-resume, so the UI must not label one.
partials_resumable: bool = True
+ # A download speed limit puts every download that fits under the HTTPS ceiling on HTTP.
+ speed_limited: bool = False
class TransportStatusResponse(BaseModel):
diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index c01d84b7c92..f666c3c14cd 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -26,6 +26,7 @@ from hub.utils import inventory_scan as hf_cache_scan
from hub.utils.hf_cache_state import EXIT_CANCELLED
from hub.utils.hf_tokens import HfTokenArg, hf_token_arg
from hub.utils.state_dir import RepoType
+from utils.download_speed_limit import DOWNLOAD_SPEED_LIMIT_ENV, get_download_speed_limit_mbps
logger = logging.getLogger(__name__)
@@ -259,6 +260,15 @@ def resolve_requested_use_xet(
) -> tuple[bool, str]:
"""Resolve the current transport mode, falling back to the legacy ``use_xet`` flag."""
mode = (transport_mode or "").strip().lower()
+ if get_download_speed_limit_mbps():
+ # Only the HTTP stream can be paced: hf_xet transfers natively.
+ if download_registry.http_size_ceiling_reason(largest_file_bytes) is None:
+ return (False, "HTTP (download speed limit)")
+ if mode != download_registry.TRANSPORT_HTTP:
+ return (
+ resolve_effective_use_xet(True),
+ "Xet (download speed limit not applied: HTTPS cannot fetch a file this large)",
+ )
if mode == download_registry.TRANSPORT_HTTP:
return (False, "HTTP (requested)")
if mode == download_registry.TRANSPORT_XET:
@@ -391,6 +401,11 @@ def spawn_worker(
env["UNSLOTH_PROTECTED_BLOB_HASHES"] = ",".join(sorted(protected_blob_hashes))
else:
env.pop("UNSLOTH_PROTECTED_BLOB_HASHES", None)
+ speed_limit = get_download_speed_limit_mbps()
+ if speed_limit:
+ env[DOWNLOAD_SPEED_LIMIT_ENV] = str(speed_limit)
+ else:
+ env.pop(DOWNLOAD_SPEED_LIMIT_ENV, None)
env["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
env["HF_HUB_DISABLE_TELEMETRY"] = "1"
env["HF_HUB_DISABLE_XET"] = "0" if use_xet else "1"
diff --git a/studio/backend/hub/workers/hf_download.py b/studio/backend/hub/workers/hf_download.py
index a34b8952e5c..b7bb2d7877b 100644
--- a/studio/backend/hub/workers/hf_download.py
+++ b/studio/backend/hub/workers/hf_download.py
@@ -42,6 +42,7 @@ from hub.utils.gguf_plan import (
sibling_sha256,
)
from hub.utils.state_dir import RepoType
+from utils.download_speed_limit import DOWNLOAD_SPEED_LIMIT_ENV, speed_limit_bytes_per_second
from hub.utils.resumable_partials import (
LAST_STOCK_RESUMABLE_VERSION,
_hub_version,
@@ -86,6 +87,70 @@ def _lift_http_ceiling_on_modelscope() -> None:
constants.MAX_HTTP_DOWNLOAD_SIZE = sys.maxsize
+class _Pacer:
+ def __init__(self, bytes_per_second: float):
+ self._rate = bytes_per_second
+ self._lock = threading.Lock()
+ self._ready_at = time.monotonic()
+
+ def wait(self, nbytes: int) -> None:
+ with self._lock:
+ now = time.monotonic()
+ # A quarter second of credit, so sleep overshoot (15ms on Windows) does not erode the rate.
+ self._ready_at = max(self._ready_at, now - 0.25) + nbytes / self._rate
+ delay = self._ready_at - now
+ if delay > 0:
+ time.sleep(delay)
+
+
+def _paced_stream(inner, pacer: _Pacer):
+ # iter_raw demands its own library's SyncByteStream: httpx on hub 1.x, httpx2 on 2.x.
+ base = sys.modules[type(inner).__module__.partition(".")[0]].SyncByteStream
+
+ class _PacedStream(base):
+ def __iter__(self):
+ for chunk in inner:
+ pacer.wait(len(chunk))
+ yield chunk
+
+ def close(self) -> None:
+ inner.close()
+
+ return _PacedStream()
+
+
+def _install_speed_limit() -> None:
+ bytes_per_second = speed_limit_bytes_per_second(os.environ.get(DOWNLOAD_SPEED_LIMIT_ENV))
+ if not bytes_per_second:
+ return
+ try:
+ from huggingface_hub import constants, set_client_factory
+ from huggingface_hub.utils._http import default_client_factory
+ except ImportError:
+ print(
+ "download speed limit needs huggingface_hub 1.x; downloading at full speed",
+ file = sys.stderr,
+ )
+ return
+
+ pacer = _Pacer(bytes_per_second)
+ # http_get writes (and progress reads) per DOWNLOAD_CHUNK_SIZE: 10 MB stalls the bar for minutes at a low limit.
+ constants.DOWNLOAD_CHUNK_SIZE = max(
+ 64 * 1024, min(constants.DOWNLOAD_CHUNK_SIZE, int(bytes_per_second // 2))
+ )
+
+ def pace(response) -> None:
+ response.stream = _paced_stream(response.stream, pacer)
+
+ def paced_client():
+ client = default_client_factory()
+ hooks = client.event_hooks
+ client.event_hooks = {"request": hooks["request"], "response": [*hooks["response"], pace]}
+ return client
+
+ set_client_factory(paced_client)
+
+
def _install_signal_handlers() -> None:
signal.signal(signal.SIGTERM, _on_signal)
signal.signal(signal.SIGINT, _on_signal)
@@ -1424,6 +1489,7 @@ def main() -> None:
hf_token = os.environ.get("HF_TOKEN") or None
_lift_http_ceiling_on_modelscope()
+ _install_speed_limit()
if args.transport == "xet" and os.environ.get("UNSLOTH_HF_XET_FORCE_STALL") == "1":
_force_stall_for_tests(args.repo_id, "dataset" if args.dataset else "model")
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 07bfb65a96d..0c412adf616 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -2411,7 +2411,9 @@ def studio_download_transport_capabilities(
probe: bool = False, _current_subject: str = Depends(get_current_subject)
):
# Sync def, so FastAPI runs this in the threadpool and an opted-in probe cannot block the loop.
- return asdict(get_download_transport_capabilities(probe = probe))
+ from utils.download_speed_limit import get_download_speed_limit_mbps
+ caps = asdict(get_download_transport_capabilities(probe = probe))
+ return {**caps, "speed_limited": get_download_speed_limit_mbps() is not None}
@app.post(
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 91a9a003eb2..271cebc2085 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -112,6 +112,10 @@ from utils.helper_precache_settings import (
)
from utils import first_token_timeout, sandbox_memory_limit, systemone_settings, tool_result_limit
from utils import video_cpu_settings
+from utils.download_speed_limit import (
+ get_download_speed_limit_mbps,
+ set_download_speed_limit_mbps,
+)
from utils.download_transport_settings import (
get_download_transport_mode,
set_download_transport_mode,
@@ -819,6 +823,14 @@ class DownloadTransportResponse(BaseModel):
auto_reason: Optional[str] = None
+class DownloadSpeedLimitPayload(BaseModel):
+ mbps: Optional[float] = Field(default = None, ge = 0)
+
+
+class DownloadSpeedLimitResponse(BaseModel):
+ mbps: Optional[float] = None
+
+
class HubSettingsPayload(BaseModel):
hf_endpoint: str = Field(max_length = 2048)
datasets_server_follows_endpoint: StrictBool
@@ -1991,6 +2003,30 @@ def update_download_transport(
return _download_transport_response(mode)
+@_shared_settings_router.get("/download-speed-limit", response_model = DownloadSpeedLimitResponse)
+def get_download_speed_limit(
+ current_subject: str = Depends(get_current_subject),
+) -> DownloadSpeedLimitResponse:
+ return DownloadSpeedLimitResponse(mbps = get_download_speed_limit_mbps())
+
+
+@_owner_settings_router.put("/download-speed-limit", response_model = DownloadSpeedLimitResponse)
+def update_download_speed_limit(
+ payload: DownloadSpeedLimitPayload, current_subject: str = Depends(get_current_subject)
+) -> DownloadSpeedLimitResponse:
+ try:
+ mbps = set_download_speed_limit_mbps(payload.mbps)
+ except ValueError as exc:
+ raise log_and_http_error(
+ exc,
+ 400,
+ safe_error_detail(exc, fallback = "Invalid download speed limit."),
+ event = "settings.update_download_speed_limit_failed",
+ log = logger,
+ ) from exc
+ return DownloadSpeedLimitResponse(mbps = mbps)
+
+
def _hub_settings_response(settings: HubSettings) -> HubSettingsResponse:
return HubSettingsResponse(
hf_endpoint = settings.hf_endpoint,
diff --git a/studio/backend/tests/test_download_speed_limit.py b/studio/backend/tests/test_download_speed_limit.py
new file mode 100644
index 00000000000..cbd14b18101
--- /dev/null
+++ b/studio/backend/tests/test_download_speed_limit.py
@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A download speed limit is stored per install, keeps a limited job on HTTP, and paces the worker's transfer."""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+import sys
+import time
+import types as _types
+from pathlib import Path
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+ sys.path.insert(0, _BACKEND_DIR)
+
+_loggers_stub = _types.ModuleType("loggers")
+_loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
+sys.modules.setdefault("loggers", _loggers_stub)
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+import routes.settings as settings
+import storage.studio_db as studio_db
+import utils.download_speed_limit as speed_limit
+from hub.services import download_lifecycle
+
+from .test_hf_download_pinned_revision import _OLD, _REPO, _WORKER, _FakeHub, _repo_dir
+from .test_hf_download_reclaim_race import _worker_env
+
+
+def store(monkeypatch):
+ values: dict = {}
+ monkeypatch.setattr(
+ studio_db, "get_app_setting", lambda key, fallback = None: values.get(key, fallback)
+ )
+ monkeypatch.setattr(
+ studio_db, "upsert_app_settings", lambda updates: values.update(updates) or values
+ )
+ return values
+
+
+def test_nothing_stored_means_no_limit(store):
+ assert speed_limit.get_download_speed_limit_mbps() is None
+ assert store == {}
+
+
+def test_a_stored_limit_is_returned(store):
+ store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] = 8
+ assert speed_limit.get_download_speed_limit_mbps() == 8.0
+
+
[email protected]("junk", ["fast", -3, 0, True, None])
+def test_junk_on_disk_reads_as_no_limit(store, junk):
+ store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] = junk
+ assert speed_limit.get_download_speed_limit_mbps() is None
+
+
+def test_set_validates_and_persists(store):
+ assert speed_limit.set_download_speed_limit_mbps(8) == 8.0
+ assert store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] == 8.0
+ assert speed_limit.set_download_speed_limit_mbps(None) is None
+ assert store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] is None
+ assert speed_limit.set_download_speed_limit_mbps(2.5) == 2.5
+ assert speed_limit.set_download_speed_limit_mbps(0) is None
+ for junk in ("8", -1, True, float("nan"), float("inf")):
+ with pytest.raises(ValueError):
+ speed_limit.set_download_speed_limit_mbps(junk)
+
+
+def client(store):
+ app = FastAPI()
+ app.include_router(settings.router)
+ app.dependency_overrides[settings.get_current_subject] = lambda: "admin"
+ return TestClient(app, raise_server_exceptions = False)
+
+
+def test_route_reports_no_limit_by_default(client):
+ assert client.get("/download-speed-limit").json() == {"mbps": None}
+
+
+def test_route_saves_and_clears_a_limit(client, store):
+ assert client.put("/download-speed-limit", json = {"mbps": 8}).json() == {"mbps": 8.0}
+ assert store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] == 8.0
+ assert client.put("/download-speed-limit", json = {"mbps": None}).json() == {"mbps": None}
+ assert store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] is None
+
+
+def test_route_rejects_a_negative_limit(client):
+ assert client.put("/download-speed-limit", json = {"mbps": -1}).status_code == 422
+
+
+def test_a_managed_account_downloads_under_the_owners_limit(monkeypatch):
+ from utils.account_context import AccountContext, current_account_id, run_as
+
+ dbs: dict = {}
+
+ def _db() -> dict:
+ return dbs.setdefault(current_account_id(), {})
+
+ monkeypatch.setattr(
+ studio_db, "get_app_setting", lambda key, fallback = None: _db().get(key, fallback)
+ )
+ monkeypatch.setattr(
+ studio_db, "upsert_app_settings", lambda updates: _db().update(updates) or _db()
+ )
+ speed_limit.set_download_speed_limit_mbps(8)
+
+ user = AccountContext("alice", "alice")
+ assert run_as(user, speed_limit.get_download_speed_limit_mbps) == 8.0
+ assert run_as(user, download_lifecycle.resolve_requested_use_xet, "xet", True)[0] is False
+
+
+def _spawn_env(monkeypatch) -> dict:
+ captured = {}
+
+ class _Fake:
+ pid = 4242
+
+ def _fake_popen(*_args, **popen_kwargs):
+ captured.update(popen_kwargs["env"])
+ return _Fake()
+
+ monkeypatch.setattr(download_lifecycle.subprocess, "Popen", _fake_popen)
+ download_lifecycle.spawn_worker(["--repo-id", _REPO], None, use_xet = False)
+ return captured
+
+
+def test_spawn_worker_hands_the_limit_to_the_worker(monkeypatch, store):
+ monkeypatch.delenv(speed_limit.DOWNLOAD_SPEED_LIMIT_ENV, raising = False)
+ assert speed_limit.DOWNLOAD_SPEED_LIMIT_ENV not in _spawn_env(monkeypatch)
+ store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] = 8
+ assert _spawn_env(monkeypatch)[speed_limit.DOWNLOAD_SPEED_LIMIT_ENV] == "8.0"
+
+
[email protected]("mode", ["xet", "auto", None])
+def test_a_limit_keeps_a_download_on_http(store, mode):
+ store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] = 8
+ use_xet, reason = download_lifecycle.resolve_requested_use_xet(mode, True)
+ assert use_xet is False
+ assert "limit" in reason.lower()
+
+
[email protected]("mode", ["xet", "auto", None])
[email protected]("limit", [None, 8])
+def test_a_file_too_large_for_https_stays_on_xet(store, monkeypatch, mode, limit):
+ monkeypatch.setattr(
+ download_lifecycle, "resolve_effective_use_xet", lambda requested: requested
+ )
+ store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] = limit
+ use_xet, reason = download_lifecycle.resolve_requested_use_xet(
+ mode, True, largest_file_bytes = 54_400_261_312
+ )
+ assert use_xet is True
+ assert ("limit" in reason.lower()) is (limit is not None)
+
+
+_BIG = hashlib.sha256(b"paced").digest() * (24 * 1024 * 1024 // 32)
+
+
+def _timed_run(hub: _FakeHub, root: Path, limit_mbps: str | None) -> float:
+ env = _worker_env(hub, root)
+ env.pop(speed_limit.DOWNLOAD_SPEED_LIMIT_ENV, None)
+ if limit_mbps is not None:
+ env[speed_limit.DOWNLOAD_SPEED_LIMIT_ENV] = limit_mbps
+ started = time.monotonic()
+ result = subprocess.run(
+ [sys.executable, str(_WORKER), "--repo-id", _REPO, "--transport", "http"],
+ cwd = _BACKEND_DIR,
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 180,
+ )
+ elapsed = time.monotonic() - started
+ assert result.returncode == 0, result.stderr
+ assert (_repo_dir(root) / "snapshots" / _OLD / "model.safetensors").read_bytes() == _BIG
+ return elapsed
+
+
+def test_the_worker_paces_the_transfer_to_the_limit(tmp_path):
+ hub = _FakeHub()
+ hub.commits[_OLD]["model.safetensors"] = _BIG
+ try:
+ unlimited = _timed_run(hub, tmp_path / "unlimited", None)
+ # 24 MB at 32 Mbit/s is six seconds of pacing, less the 0.25 s burst credit.
+ limited = _timed_run(hub, tmp_path / "limited", "32")
+ finally:
+ hub.close()
+ assert limited >= 5.7, (unlimited, limited)
+ assert limited - unlimited >= 3.0, (unlimited, limited)
+
+
+ "limit, chunk", [("8", 500_000), ("0.1", 64 * 1024), (None, 10 * 1024 * 1024)]
+)
+def test_a_limit_shrinks_the_write_chunk_so_progress_keeps_moving(monkeypatch, limit, chunk):
+ monkeypatch.delenv(speed_limit.DOWNLOAD_SPEED_LIMIT_ENV, raising = False)
+ if limit is not None:
+ monkeypatch.setenv(speed_limit.DOWNLOAD_SPEED_LIMIT_ENV, limit)
+ code = (
+ f"import runpy; runpy.run_path({str(_WORKER)!r}, run_name = 'w')['_install_speed_limit']()\n"
+ "from huggingface_hub import constants; print(constants.DOWNLOAD_CHUNK_SIZE)"
+ )
+ result = subprocess.run(
+ [sys.executable, "-c", code], cwd = _BACKEND_DIR, capture_output = True, text = True, timeout = 120
+ )
+ assert result.returncode == 0, result.stderr
+ assert int(result.stdout.split()[-1]) == chunk
+
+
[email protected]("limit", [None, 8])
+def test_capabilities_tell_the_frontend_a_limit_forces_http(store, limit):
+ import main
+
+ store[speed_limit.DOWNLOAD_SPEED_LIMIT_SETTING_KEY] = limit
+ caps = main.studio_download_transport_capabilities(_current_subject = "admin")
+ assert main.TransportCapabilities(**caps).speed_limited is (limit is not None)
diff --git a/studio/backend/utils/download_speed_limit.py b/studio/backend/utils/download_speed_limit.py
new file mode 100644
index 00000000000..c9452529c37
--- /dev/null
+++ b/studio/backend/utils/download_speed_limit.py
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Download speed limit in Mbit/s saved per install; nothing stored means no limit."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+DOWNLOAD_SPEED_LIMIT_SETTING_KEY = "download_speed_limit_mbps"
+DOWNLOAD_SPEED_LIMIT_ENV = "UNSLOTH_DOWNLOAD_SPEED_LIMIT_MBPS"
+
+
+def normalize_speed_limit_mbps(value: Any) -> Optional[float]:
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ return None
+ mbps = float(value)
+ if not math.isfinite(mbps) or mbps <= 0:
+ return None
+ return mbps
+
+
+def get_download_speed_limit_mbps() -> Optional[float]:
+ try:
+ from storage.studio_db import get_app_setting
+ from utils.account_context import OWNER, run_as
+
+ stored = run_as(OWNER, get_app_setting, DOWNLOAD_SPEED_LIMIT_SETTING_KEY, None)
+ return normalize_speed_limit_mbps(stored)
+ except Exception as exc: # noqa: BLE001 - an unreadable db reports no limit, not a 500
+ logger.debug("download speed limit read failed (%s)", exc)
+ return None
+
+
+def set_download_speed_limit_mbps(value: Any) -> Optional[float]:
+ if value is None or value == 0:
+ mbps = None
+ else:
+ mbps = normalize_speed_limit_mbps(value)
+ if mbps is None:
+ raise ValueError(
+ "Download speed limit must be a number of Mbit/s above zero, or empty."
+ )
+
+ from storage.studio_db import upsert_app_settings
+ from utils.account_context import OWNER, run_as
+
+ run_as(OWNER, upsert_app_settings, {DOWNLOAD_SPEED_LIMIT_SETTING_KEY: mbps})
+ return mbps
+
+
+def speed_limit_bytes_per_second(raw: Optional[str]) -> Optional[float]:
+ try:
+ mbps = normalize_speed_limit_mbps(float(raw)) if raw else None
+ except ValueError:
+ return None
+ return None if mbps is None else mbps * 125_000
diff --git a/studio/frontend/src/features/hub/download-manager/transport-capabilities.ts b/studio/frontend/src/features/hub/download-manager/transport-capabilities.ts
index 354aa8a04a6..2c68098b569 100644
--- a/studio/frontend/src/features/hub/download-manager/transport-capabilities.ts
+++ b/studio/frontend/src/features/hub/download-manager/transport-capabilities.ts
@@ -16,6 +16,7 @@ export interface DownloadTransportCapabilities {
auto_reason?: string | null;
// Server-side: only the backend knows which huggingface_hub writer is installed.
partials_resumable?: boolean;
+ speed_limited?: boolean;
}
export const DOWNLOAD_TRANSPORT_CAPABILITIES_FALLBACK: DownloadTransportCapabilities = {
@@ -64,6 +65,7 @@ export function normalizeDownloadTransportCapabilities(
auto_resolves_to?: unknown;
auto_reason?: unknown;
partials_resumable?: unknown;
+ speed_limited?: unknown;
};
return {
http: normalizeDownloadTransportCapability(candidate.http, {
@@ -82,5 +84,6 @@ export function normalizeDownloadTransportCapabilities(
auto_reason:
typeof candidate.auto_reason === "string" ? candidate.auto_reason : null,
partials_resumable: candidate.partials_resumable === true,
+ speed_limited: candidate.speed_limited === true,
};
}
diff --git a/studio/frontend/src/features/hub/download-manager/transport-conflict.ts b/studio/frontend/src/features/hub/download-manager/transport-conflict.ts
index 7d379718b30..c531b7743bb 100644
--- a/studio/frontend/src/features/hub/download-manager/transport-conflict.ts
+++ b/studio/frontend/src/features/hub/download-manager/transport-conflict.ts
@@ -4,7 +4,7 @@
import { checkDiskSpace } from "@/features/settings/low-disk-check";
import { toast } from "@/lib/toast";
import { disposableTimeoutSignal } from "../lib/abort-signals";
-import { getActiveModelDownloads } from "./api";
+import { getActiveModelDownloads, getDownloadTransportCapabilities } from "./api";
import {
DOWNLOAD_KIND,
mismatchStartAction,
@@ -187,11 +187,18 @@ export async function requestStart(
err,
);
}
+ // A limit moves the backend onto HTTP unless a file passes the HTTPS ceiling, which only it can see:
+ // preflight assumes HTTP (or a live sibling's transport), and the start still sends the preference.
+ const speedLimited = await getDownloadTransportCapabilities()
+ .then((caps) => caps.speed_limited === true)
+ .catch(() => false);
+ if (speedLimited) mode = TRANSPORT.HTTP;
let siblingTransport: ResolvedTransport | null = null;
let siblingProbed = false;
try {
siblingTransport = await activeSiblingTransport(req);
siblingProbed = true;
+ if (speedLimited) mode = siblingTransport ?? TRANSPORT.HTTP;
if (
siblingTransport &&
siblingTransport !== mode &&
@@ -278,7 +285,7 @@ export async function requestStart(
}
await startJob(req, {
- useXet: mode === TRANSPORT.XET,
+ useXet: speedLimited ? undefined : mode === TRANSPORT.XET,
originRoute,
originSelectionEpoch,
restartDisclosure,
diff --git a/studio/frontend/src/features/settings/api/download-speed-limit.ts b/studio/frontend/src/features/settings/api/download-speed-limit.ts
new file mode 100644
index 00000000000..c948f86af09
--- /dev/null
+++ b/studio/frontend/src/features/settings/api/download-speed-limit.ts
@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+import { clearDownloadTransportCapabilitiesCache } from "@/features/hub";
+import { readFastApiError } from "@/lib/format-fastapi-error";
+
+const DOWNLOAD_SPEED_LIMIT_EVENT = "unsloth-download-speed-limit-change";
+
+/** Mbit/s; null means no limit. */
+export type DownloadSpeedLimitSettings = {
+ mbps: number | null;
+};
+
+export function subscribeDownloadSpeedLimitSettings(
+ listener: (settings: DownloadSpeedLimitSettings) => void,
+) {
+ const handleChange = (event: Event) => {
+ listener((event as CustomEvent<DownloadSpeedLimitSettings>).detail);
+ };
+ window.addEventListener(DOWNLOAD_SPEED_LIMIT_EVENT, handleChange);
+ return () =>
+ window.removeEventListener(DOWNLOAD_SPEED_LIMIT_EVENT, handleChange);
+}
+
+export async function loadDownloadSpeedLimitSettings(): Promise<DownloadSpeedLimitSettings> {
+ const res = await authFetch("/api/settings/download-speed-limit");
+ if (!res.ok) {
+ throw new Error(
+ await readFastApiError(res, "Failed to load download speed limit"),
+ );
+ }
+ return (await res.json()) as DownloadSpeedLimitSettings;
+}
+
+export async function updateDownloadSpeedLimitSettings(
+ mbps: number | null,
+): Promise<DownloadSpeedLimitSettings> {
+ const res = await authFetch("/api/settings/download-speed-limit", {
+ method: "PUT",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ mbps }),
+ });
+ if (!res.ok) {
+ throw new Error(
+ await readFastApiError(res, "Failed to update download speed limit"),
+ );
+ }
+ const settings = (await res.json()) as DownloadSpeedLimitSettings;
+ clearDownloadTransportCapabilitiesCache();
+ window.dispatchEvent(
+ new CustomEvent(DOWNLOAD_SPEED_LIMIT_EVENT, { detail: settings }),
+ );
+ return settings;
+}
diff --git a/studio/frontend/src/features/settings/components/download-speed-limit-row.tsx b/studio/frontend/src/features/settings/components/download-speed-limit-row.tsx
new file mode 100644
index 00000000000..73c2387b57f
--- /dev/null
+++ b/studio/frontend/src/features/settings/components/download-speed-limit-row.tsx
@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { useT } from "@/i18n";
+import { useEffect, useRef, useState } from "react";
+import {
+ loadDownloadSpeedLimitSettings,
+ updateDownloadSpeedLimitSettings,
+} from "../api/download-speed-limit";
+import { SettingsRow } from "./settings-row";
+
+function asDraft(mbps: number | null) {
+ return mbps === null ? "" : String(mbps);
+}
+
+export function DownloadSpeedLimitRow() {
+ const t = useT();
+ const [draft, setDraft] = useState("");
+ const [error, setError] = useState<string | null>(null);
+ const [isSaving, setIsSaving] = useState(false);
+ const edited = useRef(false);
+
+ useEffect(() => {
+ let cancelled = false;
+ loadDownloadSpeedLimitSettings()
+ .then((settings) => {
+ if (!(cancelled || edited.current)) {
+ setDraft(asDraft(settings.mbps));
+ }
+ })
+ .catch(() => undefined);
+ return () => {
+ cancelled = true;
+ };
+ }, []);
+
+ const save = async () => {
+ const trimmed = draft.trim();
+ const mbps = trimmed === "" ? null : Number(trimmed);
+ if (mbps !== null && (!Number.isFinite(mbps) || mbps < 0)) {
+ setError(t("settings.general.downloads.speedLimitInvalid"));
+ return;
+ }
+ setIsSaving(true);
+ setError(null);
+ try {
+ const settings = await updateDownloadSpeedLimitSettings(
+ mbps === 0 ? null : mbps,
+ );
+ setDraft(asDraft(settings.mbps));
+ } catch (saveError) {
+ setError(
+ saveError instanceof Error
+ ? saveError.message
+ : t("settings.general.downloads.speedLimitInvalid"),
+ );
+ } finally {
+ setIsSaving(false);
+ }
+ };
+
+ return (
+ <SettingsRow
+ label={t("settings.general.downloads.speedLimit")}
+ description={t("settings.general.downloads.speedLimitDescription")}
+ below={
+ error ? (
+ <span className="max-w-[calc(260px*var(--ui-space-scale,1))] text-right text-xs text-destructive">
+ {error}
+ </span>
+ ) : null
+ }
+ >
+ <div className="flex items-center gap-2">
+ <div className="flex items-center gap-1.5">
+ <Input
+ type="number"
+ min={0}
+ step={1}
+ value={draft}
+ placeholder={t("settings.general.downloads.speedLimitNoLimit")}
+ aria-label={t("settings.general.downloads.speedLimit")}
+ onChange={(event) => {
+ edited.current = true;
+ setDraft(event.target.value);
+ }}
+ className="h-control w-24"
+ />
+ <span className="text-xs font-medium text-muted-foreground">
+ Mbit/s
+ </span>
+ </div>
+ <Button
+ variant="outline"
+ size="sm"
+ disabled={isSaving}
+ onClick={() => void save()}
+ >
+ {isSaving ? t("common.saving") : t("common.save")}
+ </Button>
+ </div>
+ </SettingsRow>
+ );
+}
diff --git a/studio/frontend/src/features/settings/components/download-transport-row.tsx b/studio/frontend/src/features/settings/components/download-transport-row.tsx
index 2b2346ce6c6..a203a57c2ce 100644
--- a/studio/frontend/src/features/settings/components/download-transport-row.tsx
+++ b/studio/frontend/src/features/settings/components/download-transport-row.tsx
@@ -15,6 +15,10 @@ import {
import { type TranslationKey, useT } from "@/i18n";
import { cn } from "@/lib/utils";
import { useEffect, useId, useState } from "react";
+import {
+ loadDownloadSpeedLimitSettings,
+ subscribeDownloadSpeedLimitSettings,
+} from "../api/download-speed-limit";
import {
type DownloadTransportSettings,
loadDownloadTransportSettings,
@@ -70,6 +74,28 @@ export function DownloadTransportRow() {
return unsubscribe;
}, []);
+ const [speedLimited, setSpeedLimited] = useState(false);
+
+ useEffect(() => {
+ let cancelled = false;
+ let changed = false;
+ const unsubscribe = subscribeDownloadSpeedLimitSettings((next) => {
+ changed = true;
+ setSpeedLimited(next.mbps !== null);
+ });
+ loadDownloadSpeedLimitSettings()
+ .then((next) => {
+ if (!(cancelled || changed)) {
+ setSpeedLimited(next.mbps !== null);
+ }
+ })
+ .catch(() => undefined);
+ return () => {
+ cancelled = true;
+ unsubscribe();
+ };
+ }, []);
+
// Unknown counts as unavailable while loading, or Xet could be stored and silently ignored.
const xetUnavailable = capabilityPending || settings?.xetAvailable === false;
// Localized string first; the backend reason is English prose.
@@ -79,8 +105,9 @@ export function DownloadTransportRow() {
? t("settings.general.downloads.xetMissing")
: serverReason;
- const status =
- !capabilityPending && xetUnavailable && mode === "xet"
+ const status = speedLimited
+ ? t("settings.general.downloads.speedLimitUsesHttps")
+ : !capabilityPending && xetUnavailable && mode === "xet"
? xetReason
: mode === "auto" && settings
? t("settings.general.downloads.autoCurrently", {
@@ -96,7 +123,7 @@ export function DownloadTransportRow() {
// something to explain (stalls, low RAM, an env switch); on Xet the reason is bookkeeping
// like "Xet download succeeded" or "no cached verdict; defaulting to Xet".
const statusReason =
- mode === "auto" && settings?.autoResolvesTo === "http"
+ !speedLimited && mode === "auto" && settings?.autoResolvesTo === "http"
? (settings.autoReason ?? null)
: null;
diff --git a/studio/frontend/src/features/settings/tabs/general-tab.tsx b/studio/frontend/src/features/settings/tabs/general-tab.tsx
index 3d6623c5e93..2362e09e55c 100644
--- a/studio/frontend/src/features/settings/tabs/general-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/general-tab.tsx
@@ -95,6 +95,7 @@ import {
DOWNLOAD_DIR_STORAGE_KEY,
TRANSPORT_MODE_STORAGE_KEY,
} from "@/features/hub";
+import { DownloadSpeedLimitRow } from "../components/download-speed-limit-row";
import { DownloadTransportRow } from "../components/download-transport-row";
import { HubSettingsSection } from "../components/hub-settings-section";
import { MlWarmupSection } from "../components/ml-warmup-section";
@@ -766,6 +767,7 @@ export function GeneralTab() {
<SettingsSection title={t("settings.general.downloads.sectionTitle")}>
<DownloadTransportRow />
+ <DownloadSpeedLimitRow />
</SettingsSection>
<SettingsSection title={t("settings.general.uploads.sectionTitle")}>
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index 9e38baad707..207564c85ba 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -2100,6 +2100,12 @@ export const ar = {
"يختار حسب الجهاز وينتقل إلى HTTPS إذا تعطل Xet أو فشل هنا.",
autoCurrently: "يستخدم Auto على هذا الجهاز {transport}.",
xetMissing: "Xet غير متاح لأن hf_xet غير مثبت.",
+ speedLimit: "حد سرعة التنزيل",
+ speedLimitDescription:
+ "لا حد ما لم يُحدَّد رقم. يستخدم التنزيل المحدود HTTPS.",
+ speedLimitNoLimit: "بلا حد",
+ speedLimitInvalid: "أدخل عددًا بوحدة Mbit/s أو اترك الحقل فارغًا.",
+ speedLimitUsesHttps: "تستخدم التنزيلات HTTPS ما دام حد السرعة مضبوطًا. لا تزال الملفات التي يتجاوز حجمها 50 غيغابايت تستخدم Xet من دون الحد.",
},
uploads: {
sectionTitle: "عمليات الرفع",
diff --git a/studio/frontend/src/i18n/locales/cs.ts b/studio/frontend/src/i18n/locales/cs.ts
index d79ebc92826..d6fc3926208 100644
--- a/studio/frontend/src/i18n/locales/cs.ts
+++ b/studio/frontend/src/i18n/locales/cs.ts
@@ -2320,6 +2320,12 @@ export const cs = {
autoCurrently:
"Automatický režim na tomto počítači používá: {transport}.",
xetMissing: "Xet není k dispozici, protože není nainstalován hf_xet.",
+ speedLimit: "Limit rychlosti stahování",
+ speedLimitDescription:
+ "Bez limitu, dokud nezadáte hodnotu. Omezené stahování používá HTTPS.",
+ speedLimitNoLimit: "Bez limitu",
+ speedLimitInvalid: "Zadejte počet Mbit/s nebo nechte pole prázdné.",
+ speedLimitUsesHttps: "Když je nastaven limit rychlosti, stahování používá HTTPS. Soubory nad 50 GB stále používají Xet, bez limitu.",
},
uploads: {
sectionTitle: "Nahrávání",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index efcaa5ec739..7d5d51ebc20 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -2124,6 +2124,12 @@ export const de = {
"Wählt pro Rechner und wechselt zu HTTPS, wenn Xet hier stockt oder fehlschlägt.",
autoCurrently: "Auto verwendet auf diesem Rechner {transport}.",
xetMissing: "Xet ist nicht verfügbar, da hf_xet nicht installiert ist.",
+ speedLimit: "Download-Geschwindigkeitslimit",
+ speedLimitDescription:
+ "Kein Limit, solange kein Wert gesetzt ist. Ein begrenzter Download verwendet HTTPS.",
+ speedLimitNoLimit: "Kein Limit",
+ speedLimitInvalid: "Gib eine Zahl in Mbit/s ein oder lass das Feld leer.",
+ speedLimitUsesHttps: "Solange ein Geschwindigkeitslimit gesetzt ist, verwenden Downloads HTTPS. Dateien über 50 GB verwenden weiterhin Xet, ohne das Limit.",
},
uploads: {
sectionTitle: "Uploads",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 539417719e4..a30f563f38b 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -2134,6 +2134,12 @@ export const en = {
"Picks per machine and switches to HTTPS if Xet stalls or fails here.",
autoCurrently: "Auto is using {transport} on this machine.",
xetMissing: "Xet is unavailable because hf_xet is not installed.",
+ speedLimit: "Download speed limit",
+ speedLimitDescription:
+ "No limit unless a figure is set. A limited download uses HTTPS.",
+ speedLimitNoLimit: "No limit",
+ speedLimitInvalid: "Enter a number of Mbit/s, or leave the field empty.",
+ speedLimitUsesHttps: "Downloads use HTTPS while a speed limit is set. Files over 50 GB still use Xet, without the limit.",
},
uploads: {
sectionTitle: "Uploads",
diff --git a/studio/frontend/src/i18n/locales/es-419.ts b/studio/frontend/src/i18n/locales/es-419.ts
index 9ac689883f8..8a1a312b8cc 100644
--- a/studio/frontend/src/i18n/locales/es-419.ts
+++ b/studio/frontend/src/i18n/locales/es-419.ts
@@ -2335,6 +2335,12 @@ export const es419 = {
"Elige según la computadora y cambia a HTTPS si Xet se atasca o falla aquí.",
autoCurrently: "Auto está usando {transport} en esta computadora.",
xetMissing: "Xet no está disponible porque hf_xet no está instalado.",
+ speedLimit: "Límite de velocidad de descarga",
+ speedLimitDescription:
+ "Sin límite a menos que se indique un valor. Una descarga limitada usa HTTPS.",
+ speedLimitNoLimit: "Sin límite",
+ speedLimitInvalid: "Ingresa un número en Mbit/s o deja el campo vacío.",
+ speedLimitUsesHttps: "Las descargas usan HTTPS mientras haya un límite de velocidad. Los archivos de más de 50 GB siguen usando Xet, sin el límite.",
},
uploads: {
sectionTitle: "Subidas",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index 245ace36cfe..d70e206e7ce 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -2119,6 +2119,12 @@ export const es = {
"Elige según la máquina y cambia a HTTPS si Xet se atasca o falla aquí.",
autoCurrently: "Auto está usando {transport} en esta máquina.",
xetMissing: "Xet no está disponible porque hf_xet no está instalado.",
+ speedLimit: "Límite de velocidad de descarga",
+ speedLimitDescription:
+ "Sin límite a menos que se indique un valor. Una descarga limitada usa HTTPS.",
+ speedLimitNoLimit: "Sin límite",
+ speedLimitInvalid: "Introduce un número en Mbit/s o deja el campo vacío.",
+ speedLimitUsesHttps: "Las descargas usan HTTPS mientras haya un límite de velocidad. Los archivos de más de 50 GB siguen usando Xet, sin el límite.",
},
uploads: {
sectionTitle: "Subidas",
diff --git a/studio/frontend/src/i18n/locales/fa.ts b/studio/frontend/src/i18n/locales/fa.ts
index e77032edd52..c41d90302f5 100644
--- a/studio/frontend/src/i18n/locales/fa.ts
+++ b/studio/frontend/src/i18n/locales/fa.ts
@@ -2292,6 +2292,12 @@ export const fa = {
autoCurrently:
"حالت خودکار روی این دستگاه از {transport} استفاده می‌کند.",
xetMissing: "Xet در دسترس نیست، زیرا hf_xet نصب نشده است.",
+ speedLimit: "محدودیت سرعت دانلود",
+ speedLimitDescription:
+ "بدون محدودیت مگر اینکه عددی تعیین شود. دانلود محدودشده از HTTPS استفاده می‌کند.",
+ speedLimitNoLimit: "بدون محدودیت",
+ speedLimitInvalid: "عددی بر حسب Mbit/s وارد کنید یا فیلد را خالی بگذارید.",
+ speedLimitUsesHttps: "تا زمانی که محدودیت سرعت تنظیم شده باشد، دانلودها از HTTPS استفاده می‌کنند. فایل‌های بزرگ‌تر از ۵۰ گیگابایت همچنان بدون محدودیت از Xet استفاده می‌کنند.",
},
uploads: {
sectionTitle: "آپلودها",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index 739ab992b70..ba0b7fb4bba 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -2123,6 +2123,12 @@ export const fr = {
"Choisit selon la machine et passe à HTTPS si Xet se bloque ou échoue ici.",
autoCurrently: "Auto utilise {transport} sur cette machine.",
xetMissing: "Xet est indisponible car hf_xet n'est pas installé.",
+ speedLimit: "Limite de vitesse de téléchargement",
+ speedLimitDescription:
+ "Aucune limite tant qu'aucune valeur n'est définie. Un téléchargement limité utilise HTTPS.",
+ speedLimitNoLimit: "Aucune limite",
+ speedLimitInvalid: "Saisissez un nombre en Mbit/s ou laissez le champ vide.",
+ speedLimitUsesHttps: "Les téléchargements utilisent HTTPS tant qu'une limite de vitesse est définie. Les fichiers de plus de 50 Go utilisent toujours Xet, sans la limite.",
},
uploads: {
sectionTitle: "Téléversements",
diff --git a/studio/frontend/src/i18n/locales/he.ts b/studio/frontend/src/i18n/locales/he.ts
index 5bb734c3e04..e078ce1bf7a 100644
--- a/studio/frontend/src/i18n/locales/he.ts
+++ b/studio/frontend/src/i18n/locales/he.ts
@@ -2175,6 +2175,12 @@ export const he = {
autoHint: "בוחר לפי המחשב ועובר ל-HTTPS אם Xet נתקע או נכשל כאן.",
autoCurrently: "מצב אוטומטי משתמש כעת ב-{transport} במחשב זה.",
xetMissing: "Xet אינו זמין מכיוון ש-hf_xet אינו מותקן.",
+ speedLimit: "מגבלת מהירות הורדה",
+ speedLimitDescription:
+ "ללא מגבלה אלא אם הוגדר ערך. הורדה מוגבלת משתמשת ב-HTTPS.",
+ speedLimitNoLimit: "ללא מגבלה",
+ speedLimitInvalid: "הזינו מספר ב-Mbit/s או השאירו את השדה ריק.",
+ speedLimitUsesHttps: "כל עוד מוגדרת מגבלת מהירות, ההורדות משתמשות ב-HTTPS. קבצים מעל 50GB עדיין משתמשים ב-Xet, ללא המגבלה.",
},
uploads: {
sectionTitle: "העלאות",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index 6e97158c567..748f165ecc9 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -2104,6 +2104,12 @@ export const hi = {
"मशीन के अनुसार चुनता है और यहाँ Xet अटकने या विफल होने पर HTTPS पर चला जाता है।",
autoCurrently: "इस मशीन पर Auto {transport} उपयोग कर रहा है।",
xetMissing: "hf_xet इंस्टॉल नहीं है, इसलिए Xet उपलब्ध नहीं है।",
+ speedLimit: "डाउनलोड गति सीमा",
+ speedLimitDescription:
+ "कोई सीमा नहीं जब तक कोई मान सेट न हो। सीमित डाउनलोड HTTPS का उपयोग करता है।",
+ speedLimitNoLimit: "कोई सीमा नहीं",
+ speedLimitInvalid: "Mbit/s में कोई संख्या दर्ज करें या फ़ील्ड खाली छोड़ दें।",
+ speedLimitUsesHttps: "जब तक गति सीमा सेट है, डाउनलोड HTTPS का उपयोग करते हैं। 50 GB से बड़ी फ़ाइलें अब भी बिना सीमा के Xet का उपयोग करती हैं।",
},
uploads: {
sectionTitle: "अपलोड",
diff --git a/studio/frontend/src/i18n/locales/id.ts b/studio/frontend/src/i18n/locales/id.ts
index 8da138a1115..5265294ece8 100644
--- a/studio/frontend/src/i18n/locales/id.ts
+++ b/studio/frontend/src/i18n/locales/id.ts
@@ -2302,6 +2302,12 @@ export const id = {
"Memilih per mesin dan beralih ke HTTPS jika Xet macet atau gagal di sini.",
autoCurrently: "Otomatis menggunakan {transport} di mesin ini.",
xetMissing: "Xet tidak tersedia karena hf_xet tidak terinstal.",
+ speedLimit: "Batas kecepatan unduhan",
+ speedLimitDescription:
+ "Tanpa batas kecuali ada angka yang diatur. Unduhan yang dibatasi memakai HTTPS.",
+ speedLimitNoLimit: "Tanpa batas",
+ speedLimitInvalid: "Masukkan angka dalam Mbit/s, atau biarkan kolom kosong.",
+ speedLimitUsesHttps: "Unduhan menggunakan HTTPS selama batas kecepatan diatur. File di atas 50 GB tetap menggunakan Xet, tanpa batas.",
},
uploads: {
sectionTitle: "Unggahan",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index d5c3de259f0..f540f77d71c 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -2042,6 +2042,12 @@ export const it = {
"Sceglie in base alla macchina e passa a HTTPS se Xet si blocca o fallisce qui.",
autoCurrently: "Auto sta usando {transport} su questa macchina.",
xetMissing: "Xet non è disponibile perché hf_xet non è installato.",
+ speedLimit: "Limite di velocità dei download",
+ speedLimitDescription:
+ "Nessun limite finché non viene impostato un valore. Un download limitato usa HTTPS.",
+ speedLimitNoLimit: "Nessun limite",
+ speedLimitInvalid: "Inserisci un numero in Mbit/s oppure lascia il campo vuoto.",
+ speedLimitUsesHttps: "I download usano HTTPS finché è impostato un limite di velocità. I file oltre 50 GB usano comunque Xet, senza il limite.",
},
uploads: {
sectionTitle: "Caricamenti",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index 30aea938ccc..bc9e8e0c8d7 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -2091,6 +2091,12 @@ export const ja = {
"マシンごとに選び、ここで Xet が停滞または失敗した場合は HTTPS に切り替えます。",
autoCurrently: "このマシンでは Auto は {transport} を使用しています。",
xetMissing: "hf_xet がインストールされていないため Xet は利用できません。",
+ speedLimit: "ダウンロード速度制限",
+ speedLimitDescription:
+ "値を設定しない限り制限はありません。制限中のダウンロードは HTTPS を使用します。",
+ speedLimitNoLimit: "制限なし",
+ speedLimitInvalid: "Mbit/s の数値を入力するか、空欄のままにしてください。",
+ speedLimitUsesHttps: "速度制限が設定されている間、ダウンロードは HTTPS を使用します。50 GB を超えるファイルは引き続き Xet を使用し、制限は適用されません。",
},
uploads: {
sectionTitle: "アップロード",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index 64c6730182f..83caa25ec30 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -2097,6 +2097,12 @@ export const ko = {
"머신에 맞춰 고르고, 여기서 Xet이 멈추거나 실패하면 HTTPS로 바꿉니다.",
autoCurrently: "이 머신에서 Auto는 {transport}을 사용합니다.",
xetMissing: "hf_xet이 설치되지 않아 Xet을 사용할 수 없습니다.",
+ speedLimit: "다운로드 속도 제한",
+ speedLimitDescription:
+ "값을 설정하지 않으면 제한이 없습니다. 제한된 다운로드는 HTTPS를 사용합니다.",
+ speedLimitNoLimit: "제한 없음",
+ speedLimitInvalid: "Mbit/s 단위의 숫자를 입력하거나 비워 두세요.",
+ speedLimitUsesHttps: "속도 제한이 설정되어 있는 동안 다운로드는 HTTPS를 사용합니다. 50GB를 넘는 파일은 여전히 Xet을 사용하며 제한이 적용되지 않습니다.",
},
uploads: {
sectionTitle: "업로드",
diff --git a/studio/frontend/src/i18n/locales/nl.ts b/studio/frontend/src/i18n/locales/nl.ts
index efc928b3127..a55ed46df0b 100644
--- a/studio/frontend/src/i18n/locales/nl.ts
+++ b/studio/frontend/src/i18n/locales/nl.ts
@@ -2341,6 +2341,12 @@ export const nl = {
autoCurrently: "Automatisch gebruikt {transport} op deze machine.",
xetMissing:
"Xet is niet beschikbaar omdat hf_xet niet is geïnstalleerd.",
+ speedLimit: "Downloadsnelheidslimiet",
+ speedLimitDescription:
+ "Geen limiet zolang er geen waarde is ingesteld. Een beperkte download gebruikt HTTPS.",
+ speedLimitNoLimit: "Geen limiet",
+ speedLimitInvalid: "Voer een getal in Mbit/s in of laat het veld leeg.",
+ speedLimitUsesHttps: "Zolang er een snelheidslimiet is ingesteld, gebruiken downloads HTTPS. Bestanden groter dan 50 GB gebruiken nog steeds Xet, zonder de limiet.",
},
uploads: {
sectionTitle: "Uploads",
diff --git a/studio/frontend/src/i18n/locales/pl.ts b/studio/frontend/src/i18n/locales/pl.ts
index ac5ed4cb38e..38c0fdbc810 100644
--- a/studio/frontend/src/i18n/locales/pl.ts
+++ b/studio/frontend/src/i18n/locales/pl.ts
@@ -2333,6 +2333,12 @@ export const pl = {
"Opcja Automatycznie używa na tym komputerze metody {transport}.",
xetMissing:
"Xet jest niedostępny, ponieważ hf_xet nie jest zainstalowany.",
+ speedLimit: "Limit prędkości pobierania",
+ speedLimitDescription:
+ "Brak limitu, dopóki nie ustawisz wartości. Ograniczone pobieranie używa HTTPS.",
+ speedLimitNoLimit: "Brak limitu",
+ speedLimitInvalid: "Wpisz liczbę w Mbit/s albo zostaw pole puste.",
+ speedLimitUsesHttps: "Gdy ustawiony jest limit prędkości, pobieranie używa HTTPS. Pliki większe niż 50 GB nadal używają Xet, bez limitu.",
},
uploads: {
sectionTitle: "Przesyłanie",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index c6f400e8bd2..ad1bb48e22d 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -2112,6 +2112,12 @@ export const ptBR = {
"Escolhe por máquina e muda para HTTPS se o Xet travar ou falhar aqui.",
autoCurrently: "O Auto está usando {transport} nesta máquina.",
xetMissing: "O Xet está indisponível porque o hf_xet não está instalado.",
+ speedLimit: "Limite de velocidade de download",
+ speedLimitDescription:
+ "Sem limite até que um valor seja definido. Um download limitado usa HTTPS.",
+ speedLimitNoLimit: "Sem limite",
+ speedLimitInvalid: "Digite um número em Mbit/s ou deixe o campo vazio.",
+ speedLimitUsesHttps: "Os downloads usam HTTPS enquanto houver um limite de velocidade. Arquivos acima de 50 GB continuam usando Xet, sem o limite.",
},
uploads: {
sectionTitle: "Uploads",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index f943520f8d2..2167889df8a 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -2108,6 +2108,12 @@ export const ru = {
"Выбирает для этой машины и переключается на HTTPS, если Xet зависает или падает.",
autoCurrently: "Auto использует {transport} на этой машине.",
xetMissing: "Xet недоступен, так как hf_xet не установлен.",
+ speedLimit: "Ограничение скорости загрузки",
+ speedLimitDescription:
+ "Без ограничения, пока не задано значение. Ограниченная загрузка идёт по HTTPS.",
+ speedLimitNoLimit: "Без ограничения",
+ speedLimitInvalid: "Введите число в Мбит/с или оставьте поле пустым.",
+ speedLimitUsesHttps: "Пока задано ограничение скорости, загрузки используют HTTPS. Файлы больше 50 ГБ по-прежнему загружаются через Xet без ограничения.",
},
uploads: {
sectionTitle: "Загрузки",
diff --git a/studio/frontend/src/i18n/locales/sv.ts b/studio/frontend/src/i18n/locales/sv.ts
index bdf48638f3c..09b41281f89 100644
--- a/studio/frontend/src/i18n/locales/sv.ts
+++ b/studio/frontend/src/i18n/locales/sv.ts
@@ -2242,6 +2242,12 @@ export const sv = {
"Automatiskt läge använder {transport} på den här datorn.",
xetMissing:
"Xet är inte tillgängligt eftersom hf_xet inte är installerat.",
+ speedLimit: "Hastighetsgräns för nedladdning",
+ speedLimitDescription:
+ "Ingen gräns om inget värde anges. En begränsad nedladdning använder HTTPS.",
+ speedLimitNoLimit: "Ingen gräns",
+ speedLimitInvalid: "Ange ett tal i Mbit/s eller lämna fältet tomt.",
+ speedLimitUsesHttps: "Så länge en hastighetsgräns är satt använder nedladdningar HTTPS. Filer över 50 GB använder fortfarande Xet, utan gränsen.",
},
uploads: {
sectionTitle: "Uppladdningar",
diff --git a/studio/frontend/src/i18n/locales/th.ts b/studio/frontend/src/i18n/locales/th.ts
index de4602881aa..db61696d731 100644
--- a/studio/frontend/src/i18n/locales/th.ts
+++ b/studio/frontend/src/i18n/locales/th.ts
@@ -2201,6 +2201,12 @@ export const th = {
autoHint: "เลือกตามเครื่อง และเปลี่ยนเป็น HTTPS หาก Xet ค้างหรือล้มเหลวบนเครื่องนี้",
autoCurrently: "อัตโนมัติกำลังใช้ {transport} บนเครื่องนี้",
xetMissing: "Xet ใช้งานไม่ได้เนื่องจากไม่ได้ติดตั้ง hf_xet",
+ speedLimit: "จำกัดความเร็วดาวน์โหลด",
+ speedLimitDescription:
+ "ไม่จำกัดจนกว่าจะตั้งค่าตัวเลข การดาวน์โหลดที่ถูกจำกัดจะใช้ HTTPS",
+ speedLimitNoLimit: "ไม่จำกัด",
+ speedLimitInvalid: "กรอกตัวเลขเป็น Mbit/s หรือเว้นว่างไว้",
+ speedLimitUsesHttps: "การดาวน์โหลดจะใช้ HTTPS ขณะที่ตั้งค่าขีดจำกัดความเร็วไว้ ไฟล์ที่ใหญ่กว่า 50 GB ยังคงใช้ Xet โดยไม่จำกัดความเร็ว",
},
uploads: {
sectionTitle: "การอัปโหลด",
diff --git a/studio/frontend/src/i18n/locales/tr.ts b/studio/frontend/src/i18n/locales/tr.ts
index 29a5b700b20..1ffe8aa861d 100644
--- a/studio/frontend/src/i18n/locales/tr.ts
+++ b/studio/frontend/src/i18n/locales/tr.ts
@@ -2297,6 +2297,12 @@ export const tr = {
autoCurrently:
"Otomatik, bu makinede şu aktarımı kullanıyor: {transport}",
xetMissing: "hf_xet yüklü olmadığı için Xet kullanılamıyor.",
+ speedLimit: "İndirme hızı sınırı",
+ speedLimitDescription:
+ "Bir değer girilmedikçe sınır yoktur. Sınırlı indirme HTTPS kullanır.",
+ speedLimitNoLimit: "Sınır yok",
+ speedLimitInvalid: "Mbit/s cinsinden bir sayı girin veya alanı boş bırakın.",
+ speedLimitUsesHttps: "Hız sınırı ayarlıyken indirmeler HTTPS kullanır. 50 GB'tan büyük dosyalar sınırsız olarak Xet kullanmaya devam eder.",
},
uploads: {
sectionTitle: "Karşıya yüklemeler",
diff --git a/studio/frontend/src/i18n/locales/uk.ts b/studio/frontend/src/i18n/locales/uk.ts
index 930ba58b014..b1f58faf9a7 100644
--- a/studio/frontend/src/i18n/locales/uk.ts
+++ b/studio/frontend/src/i18n/locales/uk.ts
@@ -2326,6 +2326,12 @@ export const uk = {
autoCurrently:
"На цьому комп’ютері автоматичний режим використовує {transport}.",
xetMissing: "Xet недоступний, бо hf_xet не інстальовано.",
+ speedLimit: "Обмеження швидкості завантаження",
+ speedLimitDescription:
+ "Без обмеження, доки не задано значення. Обмежене завантаження йде через HTTPS.",
+ speedLimitNoLimit: "Без обмеження",
+ speedLimitInvalid: "Введіть число в Мбіт/с або залиште поле порожнім.",
+ speedLimitUsesHttps: "Поки встановлено обмеження швидкості, завантаження використовують HTTPS. Файли понад 50 ГБ і далі завантажуються через Xet без обмеження.",
},
uploads: {
sectionTitle: "Вивантаження",
diff --git a/studio/frontend/src/i18n/locales/vi.ts b/studio/frontend/src/i18n/locales/vi.ts
index 2dbb85f8b26..230a7239b68 100644
--- a/studio/frontend/src/i18n/locales/vi.ts
+++ b/studio/frontend/src/i18n/locales/vi.ts
@@ -2307,6 +2307,12 @@ export const vi = {
"Chọn theo từng máy và chuyển sang HTTPS nếu Xet bị đứng hoặc lỗi ở đây.",
autoCurrently: "Tự động đang dùng {transport} trên máy này.",
xetMissing: "Xet không khả dụng vì chưa cài đặt hf_xet.",
+ speedLimit: "Giới hạn tốc độ tải xuống",
+ speedLimitDescription:
+ "Không giới hạn trừ khi đặt một giá trị. Tải xuống bị giới hạn dùng HTTPS.",
+ speedLimitNoLimit: "Không giới hạn",
+ speedLimitInvalid: "Nhập một số Mbit/s hoặc để trống.",
+ speedLimitUsesHttps: "Khi đặt giới hạn tốc độ, các lượt tải xuống dùng HTTPS. Các tệp trên 50 GB vẫn dùng Xet, không bị giới hạn.",
},
uploads: {
sectionTitle: "Tải lên",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index 68b3266941c..61040d53f46 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -2079,6 +2079,12 @@ export const zhCN = {
autoHint: "按本机情况选择,若 Xet 在这里卡住或失败则切换到 HTTPS。",
autoCurrently: "本机上 Auto 正在使用 {transport}。",
xetMissing: "未安装 hf_xet,因此无法使用 Xet。",
+ speedLimit: "下载速度限制",
+ speedLimitDescription:
+ "未设置数值时不限速。限速下载使用 HTTPS。",
+ speedLimitNoLimit: "不限速",
+ speedLimitInvalid: "请输入 Mbit/s 数值,或留空。",
+ speedLimitUsesHttps: "设置了速度限制时,下载使用 HTTPS。超过 50 GB 的文件仍使用 Xet,不受限制。",
},
uploads: {
sectionTitle: "上传",
diff --git a/studio/frontend/src/i18n/locales/zh-TW.ts b/studio/frontend/src/i18n/locales/zh-TW.ts
index ffbc9da6b6d..fb781214308 100644
--- a/studio/frontend/src/i18n/locales/zh-TW.ts
+++ b/studio/frontend/src/i18n/locales/zh-TW.ts
@@ -2188,6 +2188,12 @@ export const zhTW = {
autoHint: "依每台電腦自動選擇,若 Xet 在此停滯或失敗則改用 HTTPS。",
autoCurrently: "「自動」在這台電腦上使用 {transport}。",
xetMissing: "由於未安裝 hf_xet,無法使用 Xet。",
+ speedLimit: "下載速度限制",
+ speedLimitDescription:
+ "未設定數值時不限速。限速下載使用 HTTPS。",
+ speedLimitNoLimit: "不限速",
+ speedLimitInvalid: "請輸入 Mbit/s 數值,或留空。",
+ speedLimitUsesHttps: "設定速度限制時,下載會使用 HTTPS。超過 50 GB 的檔案仍使用 Xet,不受限制。",
},
uploads: {
sectionTitle: "上傳",
diff --git a/studio/frontend/tests/download-speed-limit-preflight.test.ts b/studio/frontend/tests/download-speed-limit-preflight.test.ts
new file mode 100644
index 00000000000..500bde81142
--- /dev/null
+++ b/studio/frontend/tests/download-speed-limit-preflight.test.ts
@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test, { after } from "node:test";
+import { register } from "node:module";
+
+import { installLocalStorageFake } from "./helpers/kit.ts";
+
+register("./helpers/download-lifecycle-resolver.mjs", import.meta.url);
+
+const { storage } = installLocalStorageFake();
+Object.assign(globalThis.window, {
+ location: { protocol: "http:", pathname: "/chat" },
+ setTimeout: globalThis.setTimeout.bind(globalThis),
+ clearTimeout: globalThis.clearTimeout.bind(globalThis),
+});
+storage.setItem("unsloth.studio.transportMode", "xet");
+
+const originalFetch = globalThis.fetch;
+after(() => {
+ globalThis.fetch = originalFetch;
+});
+
+const { requestStart } =
+ await import("../src/features/hub/download-manager/transport-conflict.ts");
+const { clearDownloadTransportCapabilitiesCache } =
+ await import("../src/features/hub/download-manager/api.ts");
+const { removeJob, jobKeyOf } =
+ await import("../src/features/hub/download-manager/download-manager-state.ts");
+const { finalize } =
+ await import("../src/features/hub/download-manager/poll-loop.ts");
+
+function json(body: unknown): Response {
+ return Response.json(body, { status: 200 });
+}
+
+function stubBackend(speedLimited: boolean, sibling: "http" | "xet") {
+ const starts: Array<{ transport_mode?: string }> = [];
+ globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+ const url = String(input);
+ if (url.startsWith("/api/studio/download-transport-capabilities")) {
+ return json({
+ http: { available: true, reason: null },
+ xet: { available: true, reason: null },
+ auto_resolves_to: "xet",
+ speed_limited: speedLimited,
+ });
+ }
+ if (url.startsWith("/api/hub/active-downloads")) {
+ return json({ downloads: [{ variant: "Q8_0", transport: sibling, state: "running" }] });
+ }
+ if (url.startsWith("/api/hub/transport-status")) {
+ return json({ has_partial: false, last_transport: null, resumable: false });
+ }
+ if (url === "/api/system/disk") return new Response(null, { status: 503 });
+ if (url === "/api/hub/download") {
+ starts.push(JSON.parse(String(init?.body)));
+ return json({ accepted: true, attached: false, state: "running", generation: 1, transport: sibling });
+ }
+ if (url === "/api/settings/xet-notice/reserve") {
+ return json({ granted: false, shown: 3, limit: 3 });
+ }
+ throw new Error(`Unexpected request: ${url}`);
+ }) as typeof fetch;
+ return starts;
+}
+
+for (const sibling of ["http", "xet"] as const) {
+ test(`under a limit a variant joins a sibling already on ${sibling}`, async () => {
+ clearDownloadTransportCapabilitiesCache();
+ const starts = stubBackend(true, sibling);
+ const req = { kind: "model" as const, repoId: `org/limited-${sibling}`, variant: "Q4_K_M", expectedBytes: 4096 };
+ const key = jobKeyOf(req.kind, req.repoId, req.variant);
+ try {
+ assert.equal(await requestStart(req), "started");
+ // The preference goes through: only the backend knows whether a file fits under the HTTPS ceiling.
+ assert.equal(starts[0]?.transport_mode, "xet");
+ } finally {
+ finalize(key, "complete");
+ removeJob(key);
+ }
+ });
+}
+
+test("without a limit an explicit Xet choice still refuses an HTTP sibling", async () => {
+ clearDownloadTransportCapabilitiesCache();
+ const starts = stubBackend(false, "http");
+ const req = { kind: "model" as const, repoId: "org/unlimited", variant: "Q4_K_M", expectedBytes: 4096 };
+ assert.equal(await requestStart(req), "busy");
+ assert.equal(starts.length, 0);
+});
diff --git a/studio/frontend/tests/download-transport-setting.test.ts b/studio/frontend/tests/download-transport-setting.test.ts
index bc0fa4209c1..9a3a86fb1cd 100644
--- a/studio/frontend/tests/download-transport-setting.test.ts
+++ b/studio/frontend/tests/download-transport-setting.test.ts
@@ -139,7 +139,7 @@ test("the health reason shows only when Auto falls back to HTTPS", () => {
// as a stray status line under the toggle.
assert.match(
ROW,
- /const statusReason =\s*mode === "auto" && settings\?\.autoResolvesTo === "http"/,
+ /const statusReason =\s*!speedLimited &&\s*mode === "auto" && settings\?\.autoResolvesTo === "http"/,
);
});
diff --git a/studio/frontend/tests/general-settings-token-sync.test.ts b/studio/frontend/tests/general-settings-token-sync.test.ts
index cd4bb1f4c58..97b700ee80f 100644
--- a/studio/frontend/tests/general-settings-token-sync.test.ts
+++ b/studio/frontend/tests/general-settings-token-sync.test.ts
@@ -209,6 +209,7 @@ function generalTab(initialToken: string) {
"../components/desktop-update-control": componentStub,
"../components/documents-rag-section": componentStub,
"../components/language-select": componentStub,
+ "../components/download-speed-limit-row": componentStub,
"../components/download-transport-row": componentStub,
"../components/developer-mode-section": componentStub,
"../components/engine-versions-section": componentStub,
diff --git a/studio/frontend/tests/transport-capabilities.test.ts b/studio/frontend/tests/transport-capabilities.test.ts
index 6ef816edfbf..3172cda39c8 100644
--- a/studio/frontend/tests/transport-capabilities.test.ts
+++ b/studio/frontend/tests/transport-capabilities.test.ts
@@ -68,3 +68,15 @@ test("a junk auto verdict is not trusted", () => {
assert.equal(caps.auto_resolves_to, "xet");
assert.equal(caps.auto_reason, null);
});
+
+test("the speed-limit flag survives normalization and defaults off", () => {
+ const base = {
+ http: { available: true, reason: null },
+ xet: { available: true, reason: null },
+ };
+ assert.equal(
+ normalizeDownloadTransportCapabilities({ ...base, speed_limited: true }).speed_limited,
+ true,
+ );
+ assert.equal(normalizeDownloadTransportCapabilities(base).speed_limited, false);
+});