Why Docker Hub timeouts need a deliberate Clash TUN design

Docker Hub pull failures are often described as a Docker problem: i/o timeout, context deadline exceeded, TLS handshake timeout, or an image that stays at “Pulling from library” until the command gives up. Yet the Docker daemon is not the same traffic source as your browser. A browser can follow the operating system proxy, while dockerd may run as a background service, use its own DNS path, and create separate connections for registry authentication, manifest lookup, blob downloads, and image metadata.

This difference is why enabling a system proxy sometimes changes nothing. Docker Hub traffic may leave through a route that Clash never sees, resolve through a resolver that returns an unusable address, or reach the registry through DIRECT because the profile has no matching rule. A working browser tab proves only that one application can reach one endpoint. It does not prove that the Docker daemon can complete the complete registry workflow.

This guide presents an engineering-focused Clash TUN Docker Hub setup for a Linux host running Docker Engine and a Mihomo-compatible Clash core. The objective is not to force every packet through one node. The objective is to make the packet path observable, keep DNS behavior consistent, route Docker Hub’s control and data endpoints predictably, and test each failure layer independently.

Scope: Use this procedure with networks, registries, and proxy services you are authorized to operate. Docker Hub, your distribution mirrors, and your proxy provider may apply rate limits or access policies that routing alone cannot remove.

Map the Docker registry traffic before writing rules

A Docker image pull is a sequence of HTTPS conversations, not a single request to docker.io. The client normally begins with registry discovery, then contacts the registry API. If authentication is required, it is redirected to an authorization service before the daemon returns to the registry for a token, manifest, and layer blobs. A typical pull can therefore involve several hostnames even when the command contains only docker pull nginx:latest.

Common names include registry-1.docker.io for registry operations, auth.docker.io for token exchange, and index.docker.io or docker.io during discovery and compatibility flows. Blob delivery may involve content-addressed storage or CDN hostnames selected by Docker’s infrastructure. Those download hosts can change, so a rule that covers only the visible image name is not a complete policy.

Private repositories add another layer. An organization may use Docker Hub for public base images but a separate hostname for its private registry, SSO provider, object storage backend, or vulnerability scanner. Do not copy public Docker Hub rules into a private-registry policy without first observing the actual connection names.

Traffic stage What to observe Why it matters
Discovery docker.io, index.docker.io Identifies the registry service and redirect behavior.
Authentication auth.docker.io or an account login endpoint Token failures can look like registry connectivity failures.
Registry API registry-1.docker.io Manifest and catalog requests depend on this path.
Layer delivery CDN or storage hostnames returned during the pull Large blobs may use a different route than authentication.

Begin with a clean observation. Stop repeatedly retrying the pull, record the exact image reference, and note whether the failure occurs during authentication, manifest retrieval, or a particular layer. That timestamp will help you match Docker output with Clash connection logs later.

Prepare Clash TUN mode for daemon traffic

Clash TUN mode creates a virtual network interface and redirects IP traffic into the Clash core. This is important because a daemon does not necessarily honor the desktop HTTP proxy setting. TUN can capture traffic at the network layer, but it still depends on correct routing, DNS handling, permissions, and exclusions. Treat it as a transparent path, not a magic “proxy everything” switch.

Before changing the profile, verify that your Clash build supports the TUN fields used by the configuration. Mihomo-compatible clients usually expose options such as enable, stack, auto-route, and auto-detect-interface, but GUI labels and accepted values vary. Keep a backup of the working profile and validate the configuration in the client before applying it.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

The mixed stack is a practical starting point because it can handle both TCP and UDP-shaped traffic on many Linux systems. If your host or client behaves better with system or gvisor, test that choice rather than assuming one stack is universally faster. Docker image pulls are mostly HTTPS over TCP, but DNS queries, health checks, and unrelated container services can expose differences between stacks.

Run Clash with the privileges required to create the TUN device and install routes. On a host using NetworkManager, systemd-resolved, Docker’s own bridge, or a firewall manager such as nftables, inspect the resulting routes instead of stacking several transparent proxy mechanisms blindly. Two redirect layers can create loops, and a route that captures the proxy server’s own address can prevent the tunnel from establishing.

Prevent a loop: The proxy server address, local gateway, Docker bridge ranges, and the TUN interface itself may need exclusions depending on your client and network design. If Clash connects and then all traffic immediately dies, inspect routes and bypass rules before changing nodes.

Docker commonly uses a bridge such as 172.17.0.0/16, while custom networks may use other private ranges. The daemon’s registry traffic originates from the host process, but container traffic and image-build steps can follow different paths. Decide whether your goal is only to fix docker pull on the host or also to capture build-time package downloads and running-container traffic.

Configure DNS and proxy groups without hiding the failure

DNS is one of the most common reasons a TUN configuration appears inconsistent. If the host resolves Docker endpoints with a local resolver while Clash routes the resulting connection through a proxy, the selected address may be unreachable from that exit. Conversely, a fake-IP response can confuse software that expects a normal address or performs its own hostname validation. The correct mode depends on your Clash core, operating system, and application behavior.

For an initial Docker diagnosis, use a predictable resolver strategy and make sure DNS requests are handled by the same policy engine as the HTTPS connections. A simplified Mihomo-style example might look like this:

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.cloudflare.com/dns-query
    - https://dns.google/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fallback-filter:
    geoip: true
    ipcidr:
      - 240.0.0.0/4

This is a diagnostic baseline, not a universal production profile. If your Docker version, firewall, or local resolver does not cooperate with fake-IP, temporarily test enhanced-mode: redir-host. If redir-host works while fake-IP fails, the issue is probably DNS integration or an application incompatibility rather than the upstream node itself. Keep one variable changed at a time so the result remains meaningful.

Create a dedicated proxy group for registry traffic instead of burying Docker Hub inside an enormous general-purpose selector. A manual group is useful during troubleshooting because it prevents automatic health checks from changing the route halfway through a test.

proxy-groups:
  - name: Docker-Registry
    type: select
    proxies:
      - Proxy-A
      - Proxy-B
      - DIRECT

The presence of DIRECT can be helpful as a control experiment, but it should not be mistaken for a fix. If direct access is blocked, it will fail consistently; if direct access works, you have learned that the proxy path or rule selection needs investigation.

Write explicit Docker Hub rules and validate provider order

Rule order matters. A broad GEOIP, GEOSITE, or final fallback rule can capture traffic before a specific Docker rule is evaluated. Put the registry and authentication domains above broad geographic shortcuts. Use domain suffix matching where appropriate, but do not create an overly broad rule such as DOMAIN-SUFFIX,docker.io without understanding whether it also catches services you intended to keep direct.

rules:
  - DOMAIN,auth.docker.io,Docker-Registry
  - DOMAIN,registry-1.docker.io,Docker-Registry
  - DOMAIN,index.docker.io,Docker-Registry
  - DOMAIN-SUFFIX,docker.io,Docker-Registry
  - MATCH,DIRECT

Rule providers are valuable when you maintain a larger policy, but they add another dependency: the provider itself must download successfully, parse correctly, and be refreshed on a schedule. During diagnosis, temporarily reduce the configuration to explicit local rules. Once the pull works, reintroduce providers and confirm that the provider rule appears after the Docker-specific entries or that its behavior is intentionally designed.

If layer downloads use hostnames not covered by the first test, inspect the Clash connection list while pulling a medium-sized public image. Add only the observed domains that are genuinely part of the registry flow. Avoid copying random CDN IP addresses into permanent rules because signed download URLs and edge addresses change over time.

Useful practice: Keep a temporary “Docker diagnostic” profile with explicit domain rules, a manually selected proxy, verbose logs, and no automatic fallback. It gives you a stable reference profile when the production rule-provider set becomes difficult to reason about.

Test the packet path with command-line probes

Do not start with a full image pull. First test name resolution, TCP reachability, TLS negotiation, HTTP response behavior, and Docker’s own daemon path as separate layers. Each test answers a different question, and a successful earlier test does not guarantee that the next layer will succeed.

  1. Confirm which daemon and client you are using with docker version. This separates a local CLI problem from a server-side daemon problem and shows whether the client is talking to a remote Docker context.
  2. Check DNS through the host path with getent hosts registry-1.docker.io or resolvectl query registry-1.docker.io. Record the returned addresses and compare them with the DNS behavior shown by Clash.
  3. Probe TLS and HTTP headers using curl -v https://registry-1.docker.io/v2/. A normal registry often returns 401 Unauthorized; that response is useful because it proves that DNS, TCP, TLS, and the HTTP server all responded.
  4. Repeat the request through the local Clash mixed port when your environment exposes one, for example curl -v --proxy http://127.0.0.1:7890 https://registry-1.docker.io/v2/. This tests the proxy path without depending on TUN capture.
  5. Run docker logout followed by docker login only when authentication is genuinely suspect. Do not rotate credentials as a substitute for diagnosing a timeout; a timeout is normally a transport or name-resolution symptom.
  6. Attempt a small, familiar image with docker pull hello-world, then compare the exact timestamp with Clash logs. After the control image succeeds, test the original image and identify whether a particular blob or hostname introduces the failure.

Use journalctl -u docker -f on systemd-based hosts to watch the daemon while the pull runs. At the same time, keep the Clash connection panel or API log open. You want to answer three concrete questions: did the daemon create a connection, did Clash match the expected rule, and did the selected proxy complete the upstream TLS exchange?

A 401 from /v2/ is generally a connectivity success, not an error in this test. A DNS failure points toward resolver configuration. A TCP timeout before TLS points toward routing, firewall policy, or an unreachable proxy exit. A certificate error points toward interception, an incorrect system clock, or a trust-store problem. A response that works with curl but not Docker suggests daemon environment, credential helper, proxy variables, or Docker-specific networking behavior.

Diagnose common Docker Hub and Clash failure signatures

DNS failure or inconsistent addresses

If getent returns nothing while a browser works, the daemon host may be using a broken resolver or a stale systemd-resolved state. If the answer changes between direct DNS and Clash DNS, compare the returned address family and test IPv4 and IPv6 separately. An IPv6 route that exists on the host but is unusable through the selected proxy can create long delays before the client falls back to IPv4.

TLS handshake timeout

A TLS timeout usually means that the TCP connection was created but the handshake did not complete. Check whether the matching Clash connection shows a proxy node, whether the node is overloaded, and whether the system clock is accurate. Do not disable certificate verification as a first response. That hides a trust problem and weakens the security of registry authentication.

Manifest succeeds but a blob stalls

This pattern strongly suggests that the layer-delivery hostname follows a different route or that the selected exit cannot sustain the required throughput. Observe the hostname at the moment the layer stalls. If the data host is not covered by the intended rule, add a narrowly scoped rule after verifying that it belongs to the registry workflow. Also test another node manually; a route can be logically correct while the upstream path is congested.

Authentication or rate-limit response

HTTP status codes such as 401, 403, or a Docker Hub pull-rate message are not equivalent to a network timeout. Confirm the account, token, repository visibility, and organization policy. A proxy may also make several users appear to share one public address, which can affect rate limits. Routing changes cannot repair an invalid token or an exhausted quota.

Harden the working setup for daily operation

Once the test profile succeeds, remove unnecessary debug verbosity and document the final packet path. Record the Clash core version, TUN stack, DNS mode, proxy group, explicit Docker domains, rule-provider versions, and any host routes or firewall exceptions. This small change log makes future incidents much faster to isolate than a memory-based list of “nodes that seemed good.”

Use a stable proxy group for the Docker daemon rather than a latency-only auto selector that changes during a multi-gigabyte pull. Health checks should measure an endpoint relevant to registry work, and their interval should not be so aggressive that they create needless traffic. If you operate CI runners, give them a dedicated policy and consider a local registry mirror or pull-through cache. A cache reduces repeated external downloads and makes builds less dependent on transient WAN conditions.

Keep Docker’s own proxy configuration separate from Clash TUN unless you have a reason to use both. Explicit daemon proxy variables can be appropriate in a controlled environment, but combining them with transparent capture may create double proxying or confusing bypass behavior. Choose one primary path, test it, and leave a clear rollback procedure.

Finally, monitor disk space and concurrent downloads. A registry request can appear to hang when the host is waiting on storage, unpacking layers, or throttling parallel work. Check df -h, Docker daemon logs, CPU usage, and available file descriptors alongside Clash telemetry. Good troubleshooting compares the network hypothesis with the host’s actual resource state.

Docker Hub Clash TUN FAQ

Why does Docker Hub work in my browser but not with docker pull?

The browser may honor an HTTP system proxy while the Docker daemon does not. Docker can also use a different DNS resolver, run under a different service environment, or contact authentication and blob-delivery hosts that your browser did not request. Test the daemon’s path with journalctl, Clash connection logs, and a direct curl comparison instead of treating browser access as proof that Docker is configured.

Should I always use fake-IP DNS with Docker and Clash TUN?

No. Fake-IP can provide consistent domain-based routing, but compatibility depends on the core, host resolver, firewall, and application behavior. Use it when your transparent proxy design expects it; if Docker behaves strangely, compare it with redir-host in a controlled test. The useful result is not a particular mode but a DNS path that is observable and consistent with the selected routing method.

Can I add DOMAIN-SUFFIX,docker.io,DIRECT to fix timeouts?

Only if direct access to Docker Hub is known to work on that network. A direct rule is a diagnostic control, not a universal solution. It can also leave authentication or layer traffic on an unsuitable path. Test explicit registry rules with a manually selected group first, then decide whether some Docker domains should be direct based on measured connectivity and policy.

Will these rules automatically fix a private registry?

No. A private registry may use a completely different hostname, identity provider, certificate chain, and storage backend. Observe its actual requests, create dedicated rules, and confirm that your organization permits transparent proxying of those connections. Keep credentials and certificate validation intact while testing.

Compared with some all-in-one VPN clients, which often expose only a single connect button and provide little visibility into daemon traffic, or older proxy setups that require scattered environment variables and fragile service restarts, a Docker-specific troubleshooting path can otherwise become unnecessarily opaque. Clash TUN offers a more inspectable alternative: explicit domain rules, controllable DNS behavior, selectable registry egress, connection logs, and command-line probes that distinguish routing, TLS, authentication, and host-resource failures. That clarity is useful for a workstation, a home server, or a CI runner, provided the configuration is tested rather than copied blindly. If you are ready to build this packet path with a supported Clash client, visit the download page to choose the appropriate platform package, then verify your TUN and registry rules with the staged tests above.

→ Download Clash for free and enjoy a better internet experience

Go to Download Page