Access Hugging Face in 2026: Clash Split Rules for Hub, Spaces, and API (Tested Steps)

Why Hugging Face breaks “one AI domain” mental models

Guides that assume “AI equals one vendor hostname” work well for closed chat products. Hugging Face mixes authenticated browsing, Git operations, LFS transfers, Spaces iframes, and serverless inference calls. A rule that only matches huggingface.co may still miss a CDN hostname used for shards, a short link on hf.co, or a Space edge that does not share the apex suffix. If your split rules route the main site but miss a sibling used for weights or runtime APIs, you get the familiar half-broken pattern: the UI paints while downloads spin, or the web demo works while the CLI cannot complete TLS because it resolves names differently.

Clash applies rules to connections the core actually observes. That works when Server Name Indication (SNI) matches your DOMAIN lines; it fails when encrypted DNS, privacy modes, or split stacks hide the hostname you thought you were matching. The repeatable fix is observe, match, align DNS, verify—not a longer paste from an unreviewed ruleset. If YAML policy basics are new, read the site’s Clash tutorial first, then return here for a Hugging Face–shaped overlay.

How this guide sits next to our ChatGPT, Claude, Gemini, and Notion AI articles

We already published vendor pages that share a skeleton: compact domain rules, explicit DNS notes, TUN versus system proxy trade-offs, and sniffing caveats on Meta-class cores. Those articles fit single-vendor chat or productivity suites. This page targets Hugging Face as a model hosting and demo stack: you care about Hub browsing, git push, Spaces interactivity, and Inference API calls—often in the same afternoon. Keep that distinction when you borrow YAML: copying OpenAI host lists does not route HF traffic, and routing HF alone does not fix unrelated browser tabs.

For a parallel “web plus API” story with a clearly separated inference stack, compare our ChatGPT and OpenAI API guide. For another productivity product with sync-heavy behavior, see our Notion AI rules and DNS article. Developers who split Cursor and GitHub traffic may also want our Cursor and GitHub routing guide beside this one. Here we emphasize Hugging Face’s own namespace and the way large artifacts amplify DNS and capture issues that a short API call might mask.

What you are really routing: Hub, LFS, Spaces, and Inference API

Treat the following as a baseline to confirm in your own logs after product or infrastructure updates—vendors add hosts.

• Hub web and authentication: huggingface.co and www.huggingface.co for the signed-in application, model cards, and organization pages.
• Short links and Git HTTPS: hf.co appears in share links and some Git remote URLs; routing only the apex huggingface.co can miss these flows.
• Large file storage and downloads: cdn-lfs.huggingface.co and related LFS infrastructure carry model shards and dataset blobs; partial routing here produces “page loads, download stuck” reports.
• Spaces demos: interactive apps often load from huggingface.co/spaces/... while runtime traffic may hit *.hf.space (and related edges) depending on deployment and caching.
• Inference API (serverless): documented calls commonly target api-inference.huggingface.co; token headers and rate limits apply at that layer.
• CLI and libraries: huggingface-cli, transformers, and training stacks resolve the same names as browsers but may ignore OS proxy unless you export variables or use TUN.

Do not import giant community “ML rulesets” blindly: stale REJECT lines for analytics can break telemetry your client now requires. If you maintain rules through remote providers, see our custom rules tutorial for merge order and how subscription refreshes can erase personal tweaks.

Spaces, Gradio, and assets that do not look like “HF”

When a Space embeds widgets, the browser may fetch auxiliary scripts from first-party Hugging Face hosts or from third-party CDNs used by the demo framework. If only part of that graph crosses your proxy, you see partial UI: controls render while WebSocket or long-poll channels fail. Start by confirming the Space works on a clean network without Clash. If it only fails behind your stack, continue with routing and DNS. If it fails everywhere, fix upstream Space configuration before you edit YAML for a week.

IPv6 and dual-stack gotchas

On networks that advertise IPv6, your OS may prefer AAAA records. If your proxy path handles IPv4 and IPv6 asymmetrically, you can see intermittent failures that correlate with switching between Wi-Fi and tethering rather than with Hugging Face itself. When debugging, note whether log lines show v4 or v6 destinations and whether you need explicit IP-CIDR6 DIRECT lines for local ranges, mirroring what you already do for RFC1918 IPv4 space.

Design outbound groups: one bucket or several for Hugging Face?

Before editing rules, define proxy-groups entries you can aim at. A single group named HuggingFace is enough when the same exit satisfies Hub browsing, LFS pulls, Spaces, and Inference API. Two groups—HF-Hub and HF-API—help when you want different regions for interactive browsing versus programmatic inference, or when automation must stay on a stable egress while you experiment with browser nodes.

Prefer select when you want manual control, url-test or fallback when you want automatic rotation. The nodes must actually complete TLS to Hugging Face endpoints without broken certificate inspection or half-configured IPv6. For scheduling mechanics inside YAML, our proxy groups guide explains selectors, health checks, and nesting without tying the story to a single vendor.

Keep these groups separate from a generic Proxy catch-all so your logs answer a simple question: when a download failed, did traffic hit the intended policy name? If the answer is no, fix capture or rule order before you chase the fifth node in a list.

Domain rules: conservative matchers and precedence

Clash evaluates rules top to bottom; first match wins. Place LAN exclusions, private ranges, and other high-confidence DIRECT lines before vendor-specific matchers. Then add Hugging Face–related names with DOMAIN for exact hosts and DOMAIN-SUFFIX when you understand the blast radius—DOMAIN-SUFFIX,huggingface.co,HuggingFace is simple and broad; it may also route subdomains you did not intend if the vendor later introduces services you wanted on DIRECT.

Developers who run scripts on servers without a browser still benefit from the same idea: your HTTP client resolves api-inference.huggingface.co; if resolution is poisoned or split-horizon, the TLS handshake never reaches the policy you wrote. That is DNS-first debugging, not “try another exit in the same city.”

YAML skeleton: LAN first, then Hub, LFS, Inference API, and Spaces

Assume your profile already defines proxies and a group named HuggingFace. The fragment below is illustrative: adapt names, merge with your provider template, and verify hostnames against your own capture and Hugging Face’s current documentation.

# Local and loopback first (adjust to your network)
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR,172.16.0.0/12,DIRECT
IP-CIDR,127.0.0.0/8,DIRECT

# Hugging Face — verify in YOUR logs after vendor updates
DOMAIN,api-inference.huggingface.co,HuggingFace
DOMAIN,cdn-lfs.huggingface.co,HuggingFace
DOMAIN,huggingface.co,HuggingFace
DOMAIN,www.huggingface.co,HuggingFace
DOMAIN-SUFFIX,huggingface.co,HuggingFace
DOMAIN-SUFFIX,hf.co,HuggingFace
DOMAIN-SUFFIX,hf.space,HuggingFace

# Remaining traffic follows your profile (GEOIP, MATCH, etc.)
# MATCH,Auto

If you split Hub and API across two groups, duplicate the DOMAIN lines with different targets—HF-Hub for web, LFS, and Spaces suffixes, HF-API for api-inference.huggingface.co—and keep the order consistent with your operational intent. The YAML is not magic; it is a deterministic decision list applied to each connection Clash sees.

RULE-SET workflows for teams

Individuals can maintain a short inline block. Teams often prefer a RULE-SET remote file or internal Git snippet so reviewers can diff changes. Meta-class cores support rule providers; the maintenance challenge is the same as inline YAML—document ownership, pin update intervals thoughtfully, and ensure your personal overrides survive subscription merges. When a provider refresh reorders rules, rerun your short log check instead of assuming “Hugging Face broke.”

Keep machine-readable comments in a separate changelog if your provider strips comments. Humans forget why an edge hostname was added; future you will not remember unless you wrote it down outside the auto-generated blob.

Where hand-written rules beat giant community lists

Community-maintained “AI rulesets” can save time, but they also age unevenly: one contributor’s REJECT line for analytics might block a telemetry hostname your client now requires, or a stale IP-CIDR entry might send traffic to the wrong continent after the vendor renumbers. For Hugging Face, logging first and adding lines beats importing ten thousand lines you cannot explain.

DNS: the hidden half of correct domain rules

Misconfigured DNS makes split routing look “random.” In fake-ip modes, Clash maps domain queries to synthetic addresses internally; that is elegant until a browser uses a different encrypted resolver and caches divergent answers. Symptoms include intermittent TLS failures, endless loading spinners on LFS transfers, and “worked until reboot” behavior—exactly the class of issues people describe as download problems when the Hub page renders but weights never arrive.

Align deliberately. If applications use DNS over HTTPS directly, those queries may bypass assumptions your DOMAIN rules rely on, because the core observes an IP connection without the domain context you expected. Mitigations are practical, not ideological: route known DoH provider hostnames through the same policy as the app, steer DoH to a resolver you control, or accept IP-based classification and document the trade-off. The objective is consistent name-to-policy mapping across the processes you care about.

When the web UI loads but API calls from a terminal fail (or the reverse), compare which resolver each tool uses. IDEs and language runtimes frequently ignore OS proxy settings unless configured; they may still honor HTTP proxies when set, but DNS might be OS-level or library-level. Uniform debugging beats swapping exits blindly.

Poisoned answers, captive portals, and restrictive networks

Not every strange DNS response is malware. Hotels and coffee shops return synthetic answers until you authenticate. Some enterprise filters categorize ML platforms inconsistently. If Hugging Face fails only on one physical network, test a phone hotspot before you rewrite YAML. Correlation saves time.

Split DNS versus “one resolver to rule them all”

Power users sometimes configure different upstreams for domestic versus foreign names. That can work well when documented, but it increases cognitive load for shared machines. Pick a strategy that matches who operates the computer: a disciplined single-path resolver behind Clash is often easier to support than three parallel experiments fighting each other.

Another subtle failure mode is negative caching: a transient NXDOMAIN or SERVFAIL during a flaky network moment gets cached by an intermediate layer, and every subsequent attempt “proves” the hostname does not exist until a TTL expires. When Hugging Face intermittently fails with name-resolution errors in one application but not another, flush caches methodically—browser, OS stub resolver, and any security product that implements its own mini-DNS—and retest on a clean network before editing Clash.

TLS SNI, ESNI/ECH, and “why my DOMAIN rule did not match”

Most user guides implicitly assume visible SNI hostnames. Encrypted Client Hello and related privacy features change how much a local proxy core can infer without additional configuration. If your client stack enables aggressive privacy modes, you may see more IP-only flows hitting GEOIP or final MATCH lines than you expect. When that happens, either accept broader IP-based policies with documented risk, adjust client settings for controlled debugging, or route known CDN IP ranges with explicit caution. Domain rules express intent about names; if names disappear from the wire, policy must adapt.

When TLS or half-loaded pages point to Mihomo sniffing mis-inference, our Clash Meta sniffing disable and exceptions guide walks through A/B tests and carve-outs without abandoning split routing entirely.

System proxy versus TUN for browsers, CLI tools, and training jobs

System proxy mode is usually the gentlest first step on desktops: browsers pick it up, and many GUI clients integrate cleanly. Yet the Hugging Face CLI may not honor the same environment as Chromium, and terminals running transformers or accelerate may not use the same environment variables. TUN mode raises capture rates at the cost of occasional conflicts with other VPN products or corporate agents.

A practical sequence is: confirm Clash loads the profile you think it does; reproduce a minimal Hub action with logs open; if connections never hit the core, escalate capture rather than adding more domain lines. Disable competing full-tunnel VPNs during tests—two layers arguing over routes produces “half the internet works” reports that waste weekends.

Why LFS and large downloads love this class of bugs

Git LFS and multi-gigabyte pulls are the user-visible surface of long HTTPS sessions, resumable chunks, and optimistic progress bars. If only part of that graph crosses your proxy, you see partial state: metadata arrives while bytes stall, or one mirror works while another does not. Fixing capture often resolves what looked like “Hugging Face is slow” when the bottleneck was a parallel hostname still going DIRECT into a filtered path.

GEOIP CN, bypass rules, and accidental domestic steering

If you use broad GEOIP CN or “bypass mainland” stacks, confirm Hugging Face–related flows are not swallowed by an early DIRECT line that sends TLS to an ISP path your workspace cannot complete. Conversely, if you force too much through proxy, domestic identity or payment flows may break. When domestic sites feel slow after enabling Clash, audit bypass order with our GEOIP CN and bypass checklist—it is written for China-path tuning but the rule-order debugging mindset applies anywhere your profile mixes regional policies.

Verification workflow you can repeat in about a minute

First, confirm the active profile and that local overrides survived any subscription refresh. Second, open logs and run a minimal web test: load huggingface.co, open a small model card, and trigger a trivial file listing. Third, if you use Spaces, open a lightweight demo and watch whether runtime hostnames appear in logs. Fourth, run a minimal Inference API test from the same machine—curl or a tiny script—to api-inference.huggingface.co with a token in a private environment. Fifth, run huggingface-cli whoami or a small download to exercise LFS paths. Sixth, note which rule matched and which outbound group handled each flow. Seventh, only then rotate nodes inside HuggingFace if throughput or loss remains suspect.

When authentication misbehaves, widen the window: OAuth-related hosts might still hit DIRECT because an earlier rule swallowed traffic. When Spaces stall, check WebSocket or long-poll paths and MTU before you assume model saturation.

What to record when something regresses

Capture the profile version, core flavor, capture mode, three example destination hostnames from the failure window, and the network type. Browser updates and OS “secure DNS” toggles are frequent silent variables. A short, structured note turns “it broke again” into a solvable diff.

Symptom cookbook: likely causes before you blame Hugging Face

• 401/403 on Inference API while the Hub works: tokens, rate limits, or organization policy are primary suspects—verify credentials independent of Clash. If only CLI fails, check whether the terminal uses a different proxy or DNS path than the browser.
• Model card loads but download never starts: inspect whether LFS or CDN hosts are blocked by a premature REJECT or an upstream that strips long-lived connections; compare with a minimal curl range request.
• Spaces UI partial with console websocket errors: treat as both routing and framework assets—confirm the Space works off-proxy, then verify auxiliary hostnames in logs.
• Timeouts only on one network: correlate with captive portals, IPv6 preference, or carrier-grade NAT; compare hotspot versus office Ethernet.
• Everything fails after a subscription update: diff merge order—provider templates sometimes insert broad GEOIP or early MATCH lines that bypass your Hugging Face block.
• “Works in incognito, fails in normal profile”: suspect extensions that rewrite headers, force alternate resolvers, or inject corporate inspection certificates differently per profile.
• Intermittent TLS handshake errors on git: check system clock skew, custom root stores on security appliances, and whether a different exit presents a captive portal HTML page instead of a certificate chain.

Use the list as orientation, not scripture. Logs remain authoritative; cookbooks reduce the search space so you do not spiral through unrelated forum threads late at night.

Making overrides survive subscription churn

Most people import remote profiles. Auto-updates can replace rules wholesale. Prefer client features that prepend or append user snippets, or maintain a local merge file you control. After every refresh, rerun the short verification sequence. Treat it like a smoke test for infrastructure you rely on daily.

Performance tuning without fooling yourself

Latency to Hugging Face edges is only one variable. Thermal throttling, aggressive browser extensions, and huge concurrent downloads can mimic network stalls. Before you add a sixth domain guess, close heavy tabs, disable a suspect extension briefly, and retest. Separate application slowness from path slowness; Clash only addresses the latter directly.

Privacy, terms, and realistic expectations

Routing changes path selection; it does not replace compliance with service terms, workplace policies, or regional regulations. Corporate devices may forbid split tunneling. This article assumes you configure a machine you own or legitimately administer.

Open-source transparency matters: upstream repositories are useful for issues and source review. For day-to-day stable access to Hugging Face and similar tools with a maintained Clash Meta-class client, prefer the site’s download page for installers; treat GitHub as a separate lane from the primary install path, consistent with how we document other ML and AI guides on this blog.

Putting it together

Reliable Hugging Face Hub, Spaces, and Inference API use with Clash in 2026 are less about secret host lists and more about a tight loop: observe names in logs, encode them into focused domain rules aimed at dedicated groups, align DNS with capture mode and DoH reality, and prove matches before swapping nodes. Compared with global proxy toggles, that approach keeps unrelated traffic on sensible paths, makes LFS and API failures easier to separate, and survives vendor infrastructure churn if you treat lists as living documents—next to our ChatGPT, Claude, and Notion AI articles, not instead of them.

When you are ready to install or standardize a maintained client, walk through our Clash tutorial and use our download page as the primary path—Download Clash for free and experience the difference.