, ,

Hugging Face Air-Gapped: Enterprise Hub, Offline Mirroring, and the On-Prem Build (Hugging Face Series, Part 16)

How to run Hugging Face models on a segmented or air-gapped network: mirror the artifacts to local storage, force offline mode at runtime, and use the Enterprise Hub for identity, governance, and the rate limits a proxy needs.

Hugging Face Series · Part 16 of 17
TL;DR: Air-gapping Hugging Face is two jobs you already know how to do. Mirror the artifacts across the boundary, then stop the runtime from phoning home. hf download pulls an exact revision to disk; HF_HUB_OFFLINE=1 keeps the serving node from reaching huggingface.co at load time. Above a handful of users, the Enterprise Hub buys you SSO, SCIM, token approval, audit logs and the rate limits a shared proxy needs. After that the model hands off to your GPUs the same way every other artifact in your estate already does.
Who this is for: The infrastructure admin or platform engineer who runs registries, RBAC, secrets and segmented networks, and has now been handed the job of hosting models on-prem. You do not need to be a data scientist. You need to know what crosses the gap, what runs offline, and which controls belong to which layer. This is the series finale, so it also stitches the previous fifteen parts into one build you would own and operate.
Tested on: Python 3.11+, huggingface_hub 1.21. These are the versions this walkthrough was checked against in mid-2026. The Hugging Face stack moves quickly, so pin the version you install rather than pulling latest, and expect a major release to shift some defaults.

The first thing that breaks behind the firewall

Type this on a fresh node inside a segmented network and watch it hang:

python -c "from transformers import AutoModelForCausalLM; 
AutoModelForCausalLM.from_pretrained('meta-llama/Llama-3.1-8B-Instruct')"

# Hangs, then: a connection error reaching huggingface.co

The call is not broken. The box has no route to huggingface.co, and the library’s default behavior is to contact the Hub to check for a newer revision before it loads anything. In a connected lab you never notice the round trip. Behind an air gap it is the first wall you hit, and it is the right place to start, because every enterprise concern in this finale is a variation on one fact: the Hub is a remote artifact registry, and you are about to run without it.

If you have ever stood up an internal mirror for OS packages, or pointed a build farm at a pull-through Docker cache instead of Docker Hub, you already hold the mental model. A model repo is an artifact with a name, a revision, and a set of files. Getting it on-prem is a mirroring problem. Keeping the runtime from leaking out to the internet is a configuration problem. Neither is a machine-learning problem, and that is the good news for the person reading this.

Two patterns for getting a model across the gap

There are exactly two things to get right. First, pull the artifact onto a host that can reach the Hub, verify it, and move it across the boundary into internal storage. Second, configure every node on the dark side so the runtime serves from that local copy and never tries to call out. Keep those two jobs separate and the rest is plumbing you have built a dozen times.

Crossing the gap: pull, verify, mirror, servePublic Hubhuggingface.coStaging hosthf download+ verify / scanAIR GAPInternal mirrorregistry +RBACOffline GPUnodeHF_HUB_OFFLINECONNECTED ZONEOFFLINE ZONE
The whole pattern in one line: nothing on the offline side ever talks to huggingface.co. The staging host is the only thing that does.

Pull and pin on the connected staging host

Use the official CLI. Note that huggingface-cli is deprecated in favor of hf; old scripts that call huggingface-cli download still work, but write new automation against hf. Pull to a flat local directory so you can package and move it. Pin a revision. In a connected lab nobody pins, and that is fine until two nodes quietly load two different commits of the same name and you spend an afternoon proving it.

# On the connected staging host
pip install -U "huggingface_hub[cli]"

hf download meta-llama/Llama-3.1-8B-Instruct 
  --revision main 
  --local-dir /srv/models/llama-3.1-8b-instruct

# Expected: config.json, tokenizer files and *.safetensors land in the folder
# Failure mode: 401/403 means the model is gated and your token has not
#   accepted its license; 429 means the identity is rate-limited (see below)

For reproducibility, replace main with the actual commit hash from the model’s revision history once you have chosen one. That hash is your immutable tag. It is the difference between can you redeploy exactly what passed review and roughly the same model, probably. Before anything leaves this host, scan it and confirm the weights are safetensors rather than pickle. That check is the topic of Part 7, and the registry-side controls are Part 15. The gap is exactly where you enforce both, because it is the one chokepoint every model must pass through.

Flip the cluster to offline

On the dark side, the contract is simple: never let the library reach out. Set HF_HUB_OFFLINE=1 and load from the local path. This both removes the dependency on a route you do not have and skips the revision-check round trip, which means faster cold starts as a side benefit.

# On the offline GPU node
export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1
export HF_HOME=/srv/hf-cache

python -c "from transformers import AutoModelForCausalLM as M; 
m = M.from_pretrained('/srv/models/llama-3.1-8b-instruct'); 
print('loaded', m.config.model_type)"

# Expected: loaded llama   (zero network calls)
# Failure mode without the flag: from_pretrained tries to reach the Hub to
#   check for a newer revision, hangs on the dead route, then errors

If you run a pull-through proxy on the connected edge instead of sneaker-netting folders, point clients at it with HF_ENDPOINT rather than going fully offline. Same idea as an internal package mirror. The trade-off table below covers the variables that matter in production.

VariableWhat it doesWhere you set it
HF_HUB_OFFLINE=1Blocks all HTTP to the Hub; serves only from local cache or pathEvery offline serving and training node
TRANSFORMERS_OFFLINE=1Same intent on the transformers loader pathAlongside HF_HUB_OFFLINE
HF_ENDPOINTPoints the client at an internal mirror or proxy instead of huggingface.coConnected nodes resolving through a proxy
HF_HOMERelocates the cache to managed, backed-up storageWhen the default home is small or volatile
HF_HUB_DISABLE_XET=1Forces the standard LFS download pathWhen a proxy double-stores Xet content (see below)
What this means if you run the platform: Treat the model cache as managed storage, not scratch. Put HF_HOME on a volume you size, back up and quota. A 70B model in safetensors can run well over 130 GB, and shards land all at once. If twenty pods cold-start against an unprimed cache on a shared mount, you have an IO stampede, not a model problem. Pre-warm the cache, then mount it read-only on the serving fleet.

The Enterprise Hub: identity, governance, and rate limits

For one engineer with a personal token, the free tier is fine. The moment a shared proxy, a CI fleet or a hundred developers sit behind one Hub identity, two things go wrong that you will recognize instantly. You hit rate limits, and you have no audit trail. Both are identity problems, and both are what the paid tiers exist to solve.

The Hub enforces limits over rolling windows, tied to the authenticated identity making the request. A human is bursty and small. A proxy where every training run, every Kubernetes pod cold-start and every cache revalidation funnels through one token looks, from the Hub’s side, like one account making thousands of requests. The bucket fills and resolve calls start returning HTTP 429. Per-developer upgrades do nothing, because only the proxy identity’s tier counts. The fix is to issue that token from an organization on a paid plan, and on Enterprise Plus to add IP allowlisting for the highest limits.

Picking the tier that survives a shared proxyFree / PROLowest rate limitsPersonal tokens onlyNo SSONo audit trailPer-user gated acceptSingle point of failureTeam / EnterpriseHigher rate limitsSSO (SAML / OIDC)Token approval policyAudit logsResource groupsOrg-issued tokensEnterprise PlusHighest limits + IP allowlistManaged SSO + SCIMStorage regions (EU)Network access controlModel Gateway (preview)Org-level gated accept
Tiers and exact feature names change. Confirm against the Enterprise docs before you commit a number to a procurement deck.

Beyond limits, the Enterprise Hub replaces the personal-token failure mode with identity an enterprise can manage. SSO over SAML or OIDC, with Managed SSO on Enterprise Plus making your IdP the only path in. SCIM provisioning so access disappears when someone leaves. Token approval policies so a new fine-grained token cannot be used against the org until an admin signs off. Audit logs that attribute every membership change, repo action and token approval. Resource groups for per-team scoping, and storage regions for EU data residency. If you have run an internal registry with RBAC, none of this is new vocabulary. It is the same control plane, applied to models instead of images, which is the through-line of the Harbor series.

Worked example

Gated models like Llama, Gemma and Mistral require each user to accept a license before downloading. With fifty engineers, that is fifty individual click-throughs and fifty support tickets when someone is blocked. On the org tier, you accept once at the organization level and the model becomes available to every member through the internal path. One acceptance, one audit record, fifty unblocked engineers. That is the difference between governance you administer and governance that administers you.

Proxy or native: the June 2026 wrinkle

Many shops do not want a bespoke model mirror. They already run JFrog Artifactory for Docker, PyPI, npm and Maven, and they want models on the same plane. Artifactory can proxy the Hub, cache models, scan them with Xray and bundle them into release artifacts. For modest usage that is a clean fit, and you point clients at it with the same HF_ENDPOINT mechanism shown above.

Two things to plan for. First, there is a forced migration: legacy Hugging Face repositories in Artifactory must move to the newer Machine Learning repository layout, and the cutover is one-way for practical purposes, with federated topologies needing a coordinated window. If you run this, inventory your repos and schedule it deliberately. Second, watch storage. Artifactory’s implementation of the Xet content-addressed protocol mimics the API surface but does not deliver real global deduplication, so each model can be cached both as a flat file and as byte-range slices, roughly doubling the footprint.

Gotcha: If your Artifactory model cache is growing faster than your model count explains, set HF_HUB_DISABLE_XET=1 on the clients. That forces the standard LFS download path, which the proxy caches as a single flat file, and roughly halves the footprint. You give up nothing meaningful, because the proxy’s Xet path was not delivering deduplication anyway. True content-addressed dedup across your fleet needs a Hub-native layer, not a thin proxy.

My take: a universal artifact manager and a Hub-native organization are complements, not rivals. Let Artifactory be the perimeter that scans and bundles every artifact your company ingests. Let an Enterprise organization own identity, rate limits and gated-model access on the Hub side. Use the proxy for what it is good at, and do not expect it to be Hugging Face.

The handoff: from Hub artifact to your GPUs

Mirroring gets the weights on-prem. Serving turns them into a running endpoint, and here the series converges. Once a safetensors model sits in internal storage, you have two production paths, and the choice is an infrastructure decision, not a research one.

From mirrored artifact to a running endpointMirrored modelsafetensors,pinned revisionServe as-is:TGI containerConvert:NIM / TensorRT-LLMYour GPUson VCF
Same weights, two roads to the same GPUs. The Hub-native road and the NVIDIA road meet on the hardware you own.

The Hub-native road is Text Generation Inference. It is a container you pull, point at the local model directory, and run; it is the fastest way from a mirrored model to a stable endpoint, and it stays inside the toolchain this series has used throughout. The production walk-through is Part 12, and the build-versus-buy decision among hosted inference and self-hosting is Part 11.

The NVIDIA road converts the same weights into an engine tuned for your specific GPUs, through TensorRT-LLM and the NIM packaging. You trade a build step and some flexibility for throughput on the cards you have. When the GPU stack is the center of gravity, follow the NVIDIA AI series. When the question is running all of this on VMware Cloud Foundation with proper isolation and scheduling, that is the Private AI series. The concepts underneath, quantization and fine-tuning and RAG as ideas, live in the GenAI series.

My recommendation, with the three-part honesty this series promises: default to TGI, because it gets you to a running, observable endpoint with the least moving parts and keeps you on one toolchain. Do not reach for the TensorRT-LLM conversion path when your traffic is light or your model mix changes weekly, because the build step and engine rebuilds cost you more than they return at low volume. Validate first that your GPUs and driver stack match the engine you intend to build, and that quantization (covered in Part 13) fits the model on the cards before you commit a serving design around it.

Disclaimer: Going offline, migrating a proxy layout, or putting a model in front of users are production-changing and security-sensitive steps. Stage them, scan every artifact at the gap, pin revisions, and confirm your token scopes and audit logging are live before anything serves real traffic. Re-verify current tier names, limits and CLI flags against the official docs; specifics shift, and a stale flag in a runbook fails at the worst time.

The bottom line for the platform team

Sixteen parts in, here is the build I would own. A connected staging host with an org-issued, approved token that pulls and pins models. A scan-and-verify gate at the boundary that rejects pickle and unsigned artifacts. Managed internal storage holding the mirror, mounted read-only on the fleet. Serving nodes running with HF_HUB_OFFLINE=1, fronted by TGI for most models and a converted engine only where throughput justifies it. Identity, audit and gated-access on the Hub side through an Enterprise organization, and a universal artifact manager as the perimeter if you already run one. Every box in that diagram is a thing you have built before for some other artifact type. Models are just the newest artifact to cross your gap.

That is the real conclusion of this whole series. The Hugging Face stack is not a foreign country to the infrastructure engineer. It is a registry, a set of clients, a serving layer and a governance plane, mapped onto skills you already have. You were never behind. You were early.

Your move: take the one model your team most wants on-prem, run the hf download and offline-load pair from this post on a test node, and time the cold start. That single loop, pull then serve offline, is the whole platform in miniature.

Hugging Face Series · Part 16 of 17
« Previous: Part 15  |  Hugging Face Guide  |  Next: Part 17

References

About The Author


Discover more from Journal of Intelligent Infrastructure – By Dr Pranay Jha

Subscribe to get the latest posts sent to your email.

Leave a Reply

Your email address will not be published. Required fields are marked *

Architect’s Toolkit

About the Author

Dr. Pranay Jha is a Cloud and AI Consultant with 18+ years of experience in hybrid cloud, virtualization, and enterprise infrastructure transformation. He specializes in VMware technologies, multi-cloud strategy, and Generative AI solutions. He holds a PhD in Computer Applications with research focused on Cloud and AI, has published multiple research papers, and has been a VMware vExpert since 2016 and a VMUG Community Leader.

Discover more from Journal of Intelligent Infrastructure - By Dr Pranay Jha

Subscribe now to keep reading and get access to the full archive.

Continue reading