Plan the transfer first, then the architecture: the lessons no one warns you about in air-gapped deployments

A developer named Uzair Afridi shared a lesson about air-gapped deployments on X (formerly Twitter). He says no one warns you about these things in advance.

The term air-gapped, simply put, means physically disconnected from the network. The target environment is not connected to the internet, or even to any external network. Classified internal networks, core production systems, and some industrial control areas all have this requirement. Something that a single pip install on a development machine can solve may need to be broken down into more than a dozen manual steps in an isolated environment.

He lists three things that used to be taken for granted but now all fail:

1. You can't pip install anything. The dependency tree runs fine in the development environment, but on the target machine it's missing one thing after another. Wheel files have to be prepared one by one and installed in dependency order; miss one and you get stuck.
2. You can't pull models from HuggingFace. HuggingFace is a commonly used model hosting platform in the AI world, and the pretrained weights on it are often several GB. You can only download them in advance somewhere with internet access and then figure out how to get them in. Missing files, wrong versions, or a forgotten tokenizer can all turn into incidents at the deployment site.
3. You can't search for errors. In the past, when you hit an error, you copied and pasted it into a search engine, and the answer appeared. In an isolated environment, you can only stare at that error message in the terminal and guess from context.

So every wheel, every weight file, and every container image needed on that machine has to be brought in first. USB drives, external hard drives, optical discs, and even dedicated data transfer devices may all be transport tools. How large the files are, whether they're damaged, and whether the versions match are all problems you have to solve in advance.

Uzair's advice is: plan the transfer before you plan the architecture.

That sentence is worth thinking about carefully. Usually a project starts with the architecture: how many services, how many resources, how to deploy. But with air-gapped deployments, the order is reversed. The transfer method determines what you can bring in, and what you can bring in determines the boundaries of the architecture. Model size limits hardware choices, hardware choices limit rack space, and rack space limits the transport plan. No matter how beautifully the architecture is drawn, if you can't get things in, it amounts to zero.

There are also some easily overlooked steps in this kind of deployment: if dependency versions aren't locked, you only discover resolution conflicts during offline installation; you copy files in only to find checksums don't match and have to go back and forth; container images fail to import because of platform differences, so you have to export them again.

For people building AI applications, air-gapped deployment isn't the most common situation, but encountering it once is enough to make you suffer. Simulating an offline installation in advance in the development environment, locking dependency versions, and packaging and verifying all model files and images costs far less than fixing things at the target site.

Write the transfer plan clearly first, then discuss architecture design—this is the cheapest insurance.