studio: server binds to 127.0.0.1 only, localhost unreachable when Docker Desktop shifts resolution to ::1

[LeoBorcherding]

Summary

On machines where Docker Desktop has modified the hosts file, localhost resolves to ::1 (IPv6) instead of 127.0.0.1 (IPv4). The studio server only binds to 127.0.0.1 by default, so navigating to localhost:8888 fails to reach the server while 127.0.0.1:8888 works fine. This affects all installs on Windows with Docker Desktop, not just --local.

Steps to reproduce

1. Have Docker Desktop installed on Windows
2. Install and start Studio (any install method)
   Open localhost:8888 in browser - hits ::1 (IPv6), server not listening there, connection refused or stale cached page shown
3. Open 127.0.0.1:8888 - works correctly

Root cause

studio/backend/run.py line 611 defaults host to "127.0.0.1". Docker Desktop comments out the default localhost entries in C:\Windows\System32\drivers\etc\hosts, causing Windows DNS to fall back to resolving localhost as ::1. The server is only listening on IPv4 so the connection fails.

Suggested fix

Change the default bind host from 127.0.0.1 to 0.0.0.0 so the server binds all interfaces and both localhost and 127.0.0.1 work regardless of how the OS resolves localhost.

Environment

Windows, Docker Desktop installed.

[LeoBorcherding]

Proposed fix

Change the default bind host in studio/backend/run.py from 127.0.0.1 to 0.0.0.0 (two places: the run_server() function signature on line 611 and the argparse default on line 858).

# line 611
def run_server(
    host: str = "0.0.0.0",

# line 858
default = "0.0.0.0",
help = "Host to bind to (default: 0.0.0.0; use 0.0.0.0 with -H for network/cloud access)",

Binding to 0.0.0.0 makes uvicorn listen on all IPv4 interfaces including 127.0.0.1, so both localhost and 127.0.0.1 work regardless of how the OS resolves localhost.

[LeoBorcherding]

Closing PR #5966 after review feedback. The 0.0.0.0 approach has two problems:

1. Security: 0.0.0.0 exposes Studio (which has code execution capabilities) to the entire local network
2. Incomplete: 0.0.0.0 is IPv4 only and still doesn't fix localhost → ::1 (IPv6). Also, unsloth_cli/commands/studio.py lines 590 and 853 hardcode 127.0.0.1 and pass it explicitly, so the run.py default is bypassed for normal users anyway.

Leaving this open for a proper fix, options are:

• Detect at startup when localhost resolves to ::1 and show a warning pointing users to 127.0.0.1:8888
• Bind to both 127.0.0.1 and ::1 simultaneously (requires two uvicorn instances)

likely best to just show a warning.

[rolandtannous]

@LeoBorcherding this was switched from 0.0.0.0 to 127.0.0.1 for local installs intentionally in a previous PR because 0.0.0.0 exposes the machine to automatic traffic. users can still manually start on 0.0.0.0, using the -H switch.
127.0.0.1 means only local machine and the user is therefore supposed to open 127.0.0.1:8888 . is that not working on docker desktop. and which image are you actually using because this might need an edit in the docker file , not necessarily studio as its a system mechanism

note that in our official docker image, we still bind to 0.0.0.0 so its accessible from the outside.

[LeoBorcherding]

Hi @rolandtannous, to clarify, when I found this issue I was not using a Docker image for Studio. The issue is a side effect of having Docker Desktop installed on Windows. Docker Desktop commented out the default localhost entries in C:\Windows\System32\drivers\etc\hosts:

PS C:\> cat C:/Windows/System32/drivers/etc/hosts
# Copyright (c) 1993-2009 Microsoft Corp.
#
# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
#
# This file contains the mappings of IP addresses to host names. Each
# entry should be kept on an individual line. The IP address should
# be placed in the first column followed by the corresponding host name.
# The IP address and the host name should be separated by at least one
# space.
#
# Additionally, comments (such as these) may be inserted on individual
# lines or following the machine name denoted by a '#' symbol.
#
# For example:
#
#      102.54.94.97     rhino.acme.com          # source server
#       38.25.63.10     x.acme.com              # x client host

# localhost name resolution is handled within DNS itself.
#       127.0.0.1       localhost
#       ::1             localhost
# Added by Docker Desktop
192.168.1.14 host.docker.internal
192.168.1.14 gateway.docker.internal
# To allow the same kube context to work on the host and the container:
127.0.0.1 kubernetes.docker.internal
# End of section
PS C:\>

the browser reads the host file when you type localhost:8888. The chain:

1. You type localhost:8888 in the browser
2. Browser asks Windows "what IP is localhost?"
3. Windows checks the hosts file, both entries are commented out, so it falls back to built-in DNS which returns ::1 (IPv6)
4. Browser tries to connect to ::1:8888, but Studio is only listening on 127.0.0.1 (IPv4)
5. Connection refused

the following test shows localhost resolving to : :1 instead of the expected 127.0.0.1:

PS C:\> ping -n 1 localhost

Pinging Gr33n [::1] with 32 bytes of data:
Reply from ::1: time<1ms

Ping statistics for ::1:
    Packets: Sent = 1, Received = 1, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 0ms, Maximum = 0ms, Average = 0ms
PS C:\>

So yes, 127.0.0.1:8888 works fine, the issue is purely that localhost:8888 gets a stale (cached) page because the browser ends up on : :1.

You're right that 0.0.0.0 is the wrong fix (security + still IPv4 only), which is why I closed that PR. The minimal safe fix would just be a startup warning, something like: "localhost may not resolve correctly on this machine. Use http://127.0.0.1:8888/ instead.", shown when Docker Desktop's hosts file modification is detected.

[mvanhorn]

Implemented in #5994.