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: dial the bound address for in-process API calls, not a loopback literal (#10140)

Long Yixing6133092453f7
diff --git a/studio/backend/cloudflare_tunnel.py b/studio/backend/cloudflare_tunnel.py
index 85265cc2c70..54778bb58a7 100644
--- a/studio/backend/cloudflare_tunnel.py
+++ b/studio/backend/cloudflare_tunnel.py
@@ -391,10 +391,8 @@ def _process_exited(proc: subprocess.Popen) -> bool:
def _origin_url(host: str, port: int) -> str:
- url_host = host.replace("%", "%25")
- if ":" in url_host and not url_host.startswith("["):
- url_host = f"[{url_host}]"
- return f"http://{url_host}:{port}"
+ from utils.host_policy import published_url_host
+ return f"http://{published_url_host(host)}:{port}"
class CloudflareTunnel:
diff --git a/studio/backend/core/research_runs.py b/studio/backend/core/research_runs.py
index d5ac9e41eb9..6e09d05a4fb 100644
--- a/studio/backend/core/research_runs.py
+++ b/studio/backend/core/research_runs.py
@@ -62,6 +62,12 @@ from storage.studio_db import (
list_chat_messages,
upsert_chat_message,
)
+from utils.host_policy import (
+ LOOPBACK_FALLBACK_HOST,
+ dial_host,
+ prefer_loopback,
+ scope_request_host,
+)
logger = get_logger(__name__)
_URL_BLOCK = re.compile(
@@ -1105,8 +1111,19 @@ class ResearchSupervisor:
)
await asyncio.sleep(1)
- def note_server_port(self, server: Any) -> None:
- if isinstance(getattr(self.app.state, "server_port", None), int):
+ def note_server_address(self, server: Any) -> None:
+ state = self.app.state
+ # run_server publishes the port before it binds and the address only once the listener is
+ # up, so a known port must not suppress the address.
+ published = getattr(state, "server_request_host", None)
+ if not (isinstance(published, str) and published):
+ host = scope_request_host(server)
+ if host is not None:
+ state.research_request_host = prefer_loopback(
+ getattr(state, "research_request_host", None),
+ host,
+ )
+ if isinstance(getattr(state, "server_port", None), int):
return
if (
isinstance(server, tuple)
@@ -1114,10 +1131,10 @@ class ResearchSupervisor:
and isinstance(server[1], int)
and server[1] > 0
):
- self.app.state.research_request_port = server[1]
+ state.research_request_port = server[1]
- def note_request_port(self, request: Any) -> None:
- self.note_server_port(getattr(request, "scope", {}).get("server"))
+ def note_request_address(self, request: Any) -> None:
+ self.note_server_address(getattr(request, "scope", {}).get("server"))
async def _loop(self) -> None:
while not self._stopping.is_set():
@@ -1152,11 +1169,19 @@ class ResearchSupervisor:
return None
return port
+ def _server_host(self) -> str:
+ host = getattr(self.app.state, "server_request_host", None)
+ if not isinstance(host, str) or not host:
+ host = getattr(self.app.state, "research_request_host", None)
+ if not isinstance(host, str) or not host:
+ return LOOPBACK_FALLBACK_HOST
+ return host
+
def _endpoint(self) -> str:
port = self._server_port()
if port is None:
raise RuntimeError("Research is waiting for the Unsloth server port")
- return f"http://127.0.0.1:{port}/v1/chat/completions"
+ return f"http://{dial_host(self._server_host())}:{port}/v1/chat/completions"
async def _wait_for_local_model(
self,
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 541554d5575..f0565217d97 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -915,7 +915,7 @@ class ResearchPortMiddleware:
request_app = scope.get("app")
supervisor = getattr(getattr(request_app, "state", None), "research_supervisor", None)
if supervisor is not None:
- supervisor.note_server_port(scope.get("server"))
+ supervisor.note_server_address(scope.get("server"))
await self.app(scope, receive, send)
diff --git a/studio/backend/routes/data_recipe/jobs.py b/studio/backend/routes/data_recipe/jobs.py
index 07d63ca8ab1..355f402c9e1 100644
--- a/studio/backend/routes/data_recipe/jobs.py
+++ b/studio/backend/routes/data_recipe/jobs.py
@@ -36,6 +36,7 @@ from models.data_recipe import (
PublishDatasetResponse,
RecipePayload,
)
+from utils.host_policy import dial_host, self_request_host
from utils.utils import safe_error_detail, safe_curated_detail, log_and_http_error
logger = get_logger(__name__)
@@ -50,16 +51,13 @@ ViaApiKey = Annotated[bool, Depends(authenticated_via_api_key)]
def _resolve_local_v1_endpoint(request: Request) -> str:
- """Return the loopback /v1 URL for the actual backend listen port.
+ """The /v1 URL of this process's own backend, at the address it is bound to.
- Resolution order:
- 1. ``app.state.server_port`` (run.py, post-bind) - survives proxies/tunnels.
- 2. ``request.scope["server"]`` - when Unsloth starts outside ``run_server``.
- 3. parsed ``request.base_url`` - last resort for test fixtures.
+ Port order: ``server_port`` (survives proxies/tunnels), the request scope, ``base_url``.
"""
+ server = request.scope.get("server")
port: Any = getattr(request.app.state, "server_port", None)
if not isinstance(port, int) or port <= 0:
- server = request.scope.get("server")
if (
isinstance(server, tuple)
and len(server) >= 2
@@ -70,7 +68,8 @@ def _resolve_local_v1_endpoint(request: Request) -> str:
else:
parsed = urlparse(str(request.base_url))
port = parsed.port if parsed.port is not None else 8888
- return f"http://127.0.0.1:{int(port)}/v1"
+ host = dial_host(self_request_host(request.app.state, server))
+ return f"http://{host}:{int(port)}/v1"
def _request_has_desktop_access_token(request: Request) -> bool:
diff --git a/studio/backend/routes/research_runs.py b/studio/backend/routes/research_runs.py
index e557cdf63fb..4350f31e6b1 100644
--- a/studio/backend/routes/research_runs.py
+++ b/studio/backend/routes/research_runs.py
@@ -430,7 +430,7 @@ def create_research_run(
raise HTTPException(status_code = 404, detail = "Thread not found")
supervisor = getattr(request.app.state, "research_supervisor", None)
if supervisor is not None:
- supervisor.note_request_port(request)
+ supervisor.note_request_address(request)
supervisor.wake()
return run
@@ -480,7 +480,7 @@ def approve_research_plan(
raise HTTPException(status_code = 409, detail = str(exc)) from exc
supervisor = getattr(request.app.state, "research_supervisor", None)
if supervisor is not None:
- supervisor.note_request_port(request)
+ supervisor.note_request_address(request)
supervisor.wake()
run = _require_run(run_id)
_sync_assistant(run)
@@ -516,7 +516,7 @@ def retry_research_run(
raise HTTPException(status_code = 409, detail = str(exc)) from exc
supervisor = getattr(request.app.state, "research_supervisor", None)
if supervisor is not None:
- supervisor.note_request_port(request)
+ supervisor.note_request_address(request)
supervisor.wake()
run = _require_run(run_id)
_sync_assistant(run)
diff --git a/studio/backend/run.py b/studio/backend/run.py
index a4c02471eb7..e090e39478d 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -156,6 +156,7 @@ from utils.host_policy import (
is_wildcard_host,
normalize_wildcard_bind_host,
resolved_bind_address_count,
+ published_url_host as _url_host,
wildcard_ip_versions,
wildcard_loopback_host,
)
@@ -597,15 +598,6 @@ def _loopback_bind_host_for(host: str) -> str:
return wildcard_loopback_host(host) or "127.0.0.1"
-def _url_host(host: str) -> str:
- url_host = host.replace("%", "%25")
- return (
- f"[{url_host}]"
- if ":" in url_host and not (url_host.startswith("[") and url_host.endswith("]"))
- else url_host
- )
-
-
def _direct_server_url(host: str, port: int) -> "Optional[str]":
"""The API panel's direct (non-tunnel) base, or None when this launch has no
address worth publishing.
diff --git a/studio/backend/tests/test_bind_host_policy.py b/studio/backend/tests/test_bind_host_policy.py
index 47be9886147..394b5f85b49 100644
--- a/studio/backend/tests/test_bind_host_policy.py
+++ b/studio/backend/tests/test_bind_host_policy.py
@@ -3,6 +3,7 @@
import asyncio
import socket
+from types import SimpleNamespace
import pytest
@@ -11,6 +12,7 @@ from utils.host_policy import (
is_wildcard_host,
normalize_wildcard_bind_host,
resolved_bind_address_count,
+ published_url_host,
wildcard_ip_versions,
wildcard_loopback_host,
)
@@ -228,3 +230,105 @@ def test_run_server_rejects_an_ephemeral_multi_address_bind(monkeypatch):
from run import run_server
with pytest.raises(SystemExit, match = "--port 0 cannot be used"):
run_server(host = "dual-wildcard.test", port = 0)
+
+
+ "host, expected",
+ [
+ ("127.0.0.1", "127.0.0.1"),
+ ("localhost", "localhost"),
+ ("192.168.1.239", "192.168.1.239"),
+ ("::1", "[::1]"),
+ ("fe80::1234%eth0", "[fe80::1234%25eth0]"),
+ ("fe80::1234%12", "[fe80::1234%2512]"),
+ ("[::1]", "[::1]"),
+ ],
+)
+def test_published_url_host_builds_a_url_authority(host, expected):
+ assert published_url_host(host) == expected
+
+
+def test_run_server_publishes_urls_through_the_shared_formatter():
+ import run
+ assert run._url_host is published_url_host
+
+
+# ── self-call address resolution ─────────────────────────────────────
+
+
+def _resolve_recipe_endpoint(request):
+ from routes.data_recipe.jobs import _resolve_local_v1_endpoint
+ return _resolve_local_v1_endpoint(request)
+
+
+def _recipe_request(
+ *,
+ state = None,
+ server = None,
+ base_url = "http://testserver/",
+):
+ return SimpleNamespace(
+ app = SimpleNamespace(state = state if state is not None else SimpleNamespace()),
+ scope = {"server": server},
+ base_url = base_url,
+ )
+
+
+ "bound_host, expected_authority",
+ [
+ ("192.168.1.239", "192.168.1.239:8889"),
+ ("127.0.0.1", "127.0.0.1:8889"),
+ ("::1", "[::1]:8889"),
+ ("fe80::1234%eth0", "[fe80::1234%eth0]:8889"),
+ ],
+)
+def test_the_data_recipe_endpoint_dials_the_address_the_server_is_bound_to(
+ bound_host, expected_authority
+):
+ request = _recipe_request(
+ state = SimpleNamespace(server_port = 8889, server_request_host = bound_host),
+ )
+ assert _resolve_recipe_endpoint(request) == f"http://{expected_authority}/v1"
+
+
+def test_the_data_recipe_endpoint_falls_back_to_the_accepting_address_outside_run_server():
+ request = _recipe_request(server = ("192.168.1.239", 8889))
+ assert _resolve_recipe_endpoint(request) == "http://192.168.1.239:8889/v1"
+
+
+ "wildcard, expected_authority",
+ [("0.0.0.0", "127.0.0.1:8889"), ("::", "[::1]:8889")],
+)
+def test_the_data_recipe_endpoint_maps_a_wildcard_bind_back_to_loopback(
+ wildcard, expected_authority
+):
+ # The IPv6 family carries this: loopback is also the fallback.
+ request = _recipe_request(server = (wildcard, 8889), base_url = "http://testserver:1234/")
+ assert _resolve_recipe_endpoint(request) == f"http://{expected_authority}/v1"
+
+
[email protected]("server", [None, (), ("",), ("192.168.1.239",)])
+def test_the_data_recipe_endpoint_ignores_scope_values_that_carry_no_address(server):
+ request = _recipe_request(server = server, base_url = "http://testserver:8888/")
+ assert _resolve_recipe_endpoint(request) == "http://127.0.0.1:8888/v1"
+
+
+def test_a_data_recipe_scope_address_that_is_unusable_still_yields_its_port():
+ request = _recipe_request(server = ("", 8889), base_url = "http://testserver:8888/")
+ assert _resolve_recipe_endpoint(request) == "http://127.0.0.1:8889/v1"
+
+
+def test_the_data_recipe_endpoint_prefers_the_bound_host_over_the_accepting_address():
+ request = _recipe_request(
+ state = SimpleNamespace(server_port = 8889, server_request_host = "192.168.1.239"),
+ server = ("127.0.0.1", 9999),
+ )
+ assert _resolve_recipe_endpoint(request) == "http://192.168.1.239:8889/v1"
+
+
+def test_the_data_recipe_endpoint_uses_loopback_when_no_address_is_available():
+ assert _resolve_recipe_endpoint(_recipe_request(base_url = "http://testserver:8888/")) == (
+ "http://127.0.0.1:8888/v1"
+ )
diff --git a/studio/backend/tests/test_lan_share_host_resolution.py b/studio/backend/tests/test_lan_share_host_resolution.py
index c0583e8ab60..642bf159410 100644
--- a/studio/backend/tests/test_lan_share_host_resolution.py
+++ b/studio/backend/tests/test_lan_share_host_resolution.py
@@ -132,6 +132,18 @@ def test_direct_server_url_is_the_lan_address(monkeypatch):
assert _direct_server_url("0.0.0.0", 8888) == f"http://{LAN_IP}:8888"
+ "host, authority",
+ [
+ ("192.168.1.7", "192.168.1.7"),
+ ("::1", "[::1]"),
+ ("fe80::1234%eth0", "[fe80::1234%25eth0]"),
+ ],
+)
+def test_direct_server_url_formats_specific_bind_addresses(host, authority):
+ assert _direct_server_url(host, 8889) == f"http://{authority}:8889"
+
+
def test_direct_server_url_is_unset_when_no_lan_address_is_detectable(monkeypatch):
"""Never publish the wildcard: the frontend prefers any non-null server_url
over the origin the client actually reached, so http://0.0.0.0:8888 would be
diff --git a/studio/backend/tests/test_middleware.py b/studio/backend/tests/test_middleware.py
index 859ba956d1e..2aa66c5e8ef 100644
--- a/studio/backend/tests/test_middleware.py
+++ b/studio/backend/tests/test_middleware.py
@@ -888,7 +888,7 @@ class TestResearchPortMiddleware:
seen = {}
class Supervisor:
- def note_server_port(self, server):
+ def note_server_address(self, server):
seen["server"] = server
async def inner_app(scope, receive, send):
diff --git a/studio/backend/tests/test_research_runs_hardening.py b/studio/backend/tests/test_research_runs_hardening.py
index 625233e8bfd..761cb12bd87 100644
--- a/studio/backend/tests/test_research_runs_hardening.py
+++ b/studio/backend/tests/test_research_runs_hardening.py
@@ -2632,3 +2632,107 @@ def test_a_cancel_during_the_rate_limit_wait_is_not_held_for_the_retry_after(mon
assert ended, "the wait never re-checked the run"
assert ended[0] - started[0] <= research_runs._MODEL_WAIT_POLL_SECONDS
+
+
+# ── self-call endpoint address ───────────────────────────────────────
+
+
+def _endpoint_supervisor(**state) -> ResearchSupervisor:
+ return ResearchSupervisor(SimpleNamespace(state = SimpleNamespace(server_port = 8889, **state)))
+
+
+ "bound_host, expected_authority",
+ [
+ ("192.168.1.239", "192.168.1.239:8889"),
+ ("127.0.0.1", "127.0.0.1:8889"),
+ ("::1", "[::1]:8889"),
+ ("fe80::1234%eth0", "[fe80::1234%eth0]:8889"),
+ ],
+)
+def test_endpoint_dials_the_address_the_server_is_bound_to(bound_host, expected_authority):
+ supervisor = _endpoint_supervisor(server_request_host = bound_host)
+ assert supervisor._endpoint() == f"http://{expected_authority}/v1/chat/completions"
+
+
+def test_endpoint_falls_back_to_the_noted_request_host():
+ supervisor = _endpoint_supervisor(research_request_host = "10.1.2.3")
+ assert supervisor._endpoint() == "http://10.1.2.3:8889/v1/chat/completions"
+
+
+def test_endpoint_prefers_the_bound_host_over_a_noted_one():
+ supervisor = _endpoint_supervisor(
+ server_request_host = "192.168.1.239",
+ research_request_host = "10.1.2.3",
+ )
+ assert supervisor._endpoint() == "http://192.168.1.239:8889/v1/chat/completions"
+
+
+def test_endpoint_uses_loopback_when_no_address_was_published():
+ assert _endpoint_supervisor()._endpoint() == "http://127.0.0.1:8889/v1/chat/completions"
+
+
+def test_note_server_address_records_the_accepting_address_outside_run_server():
+ state = SimpleNamespace()
+ supervisor = ResearchSupervisor(SimpleNamespace(state = state))
+ supervisor.note_server_address(("192.168.1.239", 8889))
+ assert state.research_request_host == "192.168.1.239"
+ assert supervisor._endpoint() == "http://192.168.1.239:8889/v1/chat/completions"
+
+
+def test_note_server_address_maps_a_wildcard_bind_back_to_loopback():
+ state = SimpleNamespace()
+ supervisor = ResearchSupervisor(SimpleNamespace(state = state))
+ supervisor.note_server_address(("0.0.0.0", 8889))
+ # On the recorded address, not the endpoint: loopback is also the fallback.
+ assert state.research_request_host == "127.0.0.1"
+ assert supervisor._endpoint() == "http://127.0.0.1:8889/v1/chat/completions"
+
+
+def test_note_server_address_records_the_address_when_only_the_port_is_published():
+ # run_server publishes the port before it binds, the address only once bound.
+ state = SimpleNamespace(server_port = 8889, server_request_host = None)
+ supervisor = ResearchSupervisor(SimpleNamespace(state = state))
+ supervisor.note_server_address(("192.168.1.239", 8889))
+ assert state.research_request_host == "192.168.1.239"
+ assert supervisor._endpoint() == "http://192.168.1.239:8889/v1/chat/completions"
+
+
+ "arrivals",
+ [
+ (("127.0.0.1", 8889), ("192.168.1.239", 8889)),
+ (("192.168.1.239", 8889), ("127.0.0.1", 8889)),
+ ],
+)
+def test_a_wildcard_bind_settles_on_loopback_in_either_arrival_order(arrivals):
+ state = SimpleNamespace()
+ supervisor = ResearchSupervisor(SimpleNamespace(state = state))
+ for server in arrivals:
+ supervisor.note_server_address(server)
+ assert state.research_request_host == "127.0.0.1"
+ assert supervisor._endpoint() == "http://127.0.0.1:8889/v1/chat/completions"
+
+
+def test_a_single_interface_bind_still_latches_its_own_address():
+ state = SimpleNamespace()
+ supervisor = ResearchSupervisor(SimpleNamespace(state = state))
+ supervisor.note_server_address(("192.168.1.239", 8889))
+ supervisor.note_server_address(("192.168.1.239", 8889))
+ assert state.research_request_host == "192.168.1.239"
+
+
[email protected]("server", [None, (), ("",), ("192.168.1.239",), ("", 8889), (8889,)])
+def test_note_server_address_ignores_scope_values_that_carry_no_address(server):
+ state = SimpleNamespace()
+ supervisor = ResearchSupervisor(SimpleNamespace(state = state))
+ supervisor.note_server_address(server)
+ assert getattr(state, "research_request_host", None) is None
+
+
+def test_note_server_address_defers_to_run_server_published_state():
+ state = SimpleNamespace(server_port = 8889, server_request_host = "192.168.1.239")
+ supervisor = ResearchSupervisor(SimpleNamespace(state = state))
+ supervisor.note_server_address(("127.0.0.1", 9999))
+ assert getattr(state, "research_request_host", None) is None
+ assert supervisor._endpoint() == "http://192.168.1.239:8889/v1/chat/completions"
diff --git a/studio/backend/tests/test_research_runs_storage.py b/studio/backend/tests/test_research_runs_storage.py
index c283c07ff29..3f05ee9ab79 100644
--- a/studio/backend/tests/test_research_runs_storage.py
+++ b/studio/backend/tests/test_research_runs_storage.py
@@ -1114,7 +1114,7 @@ def test_recovered_supervisor_waits_for_actual_server_port(research_home):
with pytest.raises(RuntimeError, match = "server port"):
supervisor._endpoint()
- supervisor.note_request_port(SimpleNamespace(scope = {"server": ("127.0.0.1", 4321)}))
+ supervisor.note_request_address(SimpleNamespace(scope = {"server": ("127.0.0.1", 4321)}))
assert supervisor._endpoint() == "http://127.0.0.1:4321/v1/chat/completions"
diff --git a/studio/backend/utils/host_policy.py b/studio/backend/utils/host_policy.py
index 679c9ef4c5c..265d27d8439 100644
--- a/studio/backend/utils/host_policy.py
+++ b/studio/backend/utils/host_policy.py
@@ -177,6 +177,59 @@ def wildcard_loopback_host(host: str) -> "str | None":
return "::1" if 6 in versions else None
+def published_url_host(host: str) -> str:
+ """Authority host for a URL Studio hands out - a banner line, `server_url`, a tunnel origin."""
+ escaped = host.replace("%", "%25")
+ if ":" not in escaped or (escaped.startswith("[") and escaped.endswith("]")):
+ return escaped
+ return f"[{escaped}]"
+
+
+def dial_host(host: str) -> str:
+ """Authority host for a URL this process dials itself. The IPv6 zone id stays literal: httpx
+ hands the RFC 6874 escaping `published_url_host` applies to the resolver unchanged."""
+ return f"[{host}]" if ":" in host else host
+
+
+# Self-call address resolution. A `--host` other than a wildcard binds one interface only, so
+# loopback is not served and a hardcoded `127.0.0.1` self-call cannot connect.
+LOOPBACK_FALLBACK_HOST = "127.0.0.1"
+
+
+def is_loopback_host(host: str) -> bool:
+ try:
+ return ipaddress.ip_address(host.split("%", 1)[0]).is_loopback
+ except ValueError:
+ return host.lower() == "localhost"
+
+
+def scope_request_host(server) -> "str | None":
+ """Accepting address from an ASGI `scope["server"]`. Never carries an IPv6 zone id."""
+ if not isinstance(server, (tuple, list)) or len(server) < 2:
+ return None
+ host = server[0]
+ if not isinstance(host, str) or not host:
+ return None
+ return wildcard_loopback_host(host) or host
+
+
+def prefer_loopback(current: "str | None", candidate: str) -> str:
+ """Keep loopback once seen: a wildcard bind reports whichever interface each request arrived
+ on, and that address can change while the loopback it also serves stays valid."""
+ if current is not None and is_loopback_host(current):
+ return current
+ return candidate
+
+
+def self_request_host(app_state, server = None) -> str:
+ """`server_request_host` is authoritative - run_server publishes it from the live listener
+ sockets; the scope pair covers running outside run_server."""
+ published = getattr(app_state, "server_request_host", None)
+ if isinstance(published, str) and published:
+ return published
+ return scope_request_host(server) or LOOPBACK_FALLBACK_HOST
+
+
# Tauri desktop webview origins. api-only serving (the desktop app calling a
# local backend) locks CORS to these.
_TAURI_CORS_ORIGINS = (