LayerSmith: A Self-Hosted Container Image Build Tool for Air-Gapped Environments

Building and distributing container images in connected environments is a well-established workflow. But once you step into a physically isolated (air-gapped) network, the entire pipeline becomes fragile — no external registry to pull base images from, dependency version drift, and no traceability in deliverables. The open-source project LayerSmith targets exactly this pain point, offering a self-hostable Web UI that makes image builds and cross-environment migrations far more controllable.

What Problem It Solves

LayerSmith, initiated by developer r0lfi, is essentially a frontend for building container images using Docker or Podman. Users start by selecting a Linux distribution, then specify the image's purpose — development environment, Linux ops, network tools, Ansible, Kubernetes, OpenShift, or a fully custom configuration. The tool automatically handles package differences across distributions and presents the generated Containerfile before the actual build begins.

This "preview before build" design is pragmatic. Rather than making the build process a black box, LayerSmith puts the generated Containerfile right in front of you: you can manually edit it, import an existing Dockerfile, or append your own packages, files, and scripts. For engineers comfortable on the command line, the GUI is an accelerator, not a constraint — the final artifact remains a transparent, auditable, standard Containerfile.

Air-Gap Migration Is the Real Focus

The project author repeatedly emphasizes that making images easier to bring into isolated networks is LayerSmith's core objective. This manifests in several concrete mechanisms:

• Pinned base images: Prevents reproducibility issues caused by upstream tag changes;
• Build detail recording: Every build leaves traceable metadata;
• Export bundles: Packaged contents include the image itself, checksums, and installation instructions.

This combination directly addresses the two biggest headaches in air-gapped environments: reproducibility and trusted delivery. Without external network access, you can't pull a missing dependency on the fly, nor verify image integrity online. Bundling checksums and installation documentation together means recipients can complete verification and deployment in a fully offline environment, reducing the risk of "it doesn't work when we get on-site."

Pinned base images deserve a closer look. When we write FROM ubuntu:22.04, the actual content pulled at different times may not be identical — upstream maintainers continuously push security patches that overwrite the same tag. True pinning means locking to an image digest, like FROM ubuntu@sha256:abc123..., ensuring you get exactly the same binary layers no matter when or where you pull. In air-gapped environments, the "offline snapshot" is itself a de facto pin — but if you didn't record the digest when building on the connected side, you lose precise traceability of exactly which version was brought in. LayerSmith's pinning mechanism intervenes at this stage, capturing digest information at build time rather than relying on manual documentation after the fact.

New LLM Training and Fine-Tuning Configurations

LayerSmith recently added a set of image configurations targeting large model training and fine-tuning, covering LoRA/QLoRA, advanced PyTorch training, and LLaMA-Factory. These directions broadly cover the mainstream parameter-efficient fine-tuning (PEFT) workflows in use today.

Notably, the approach to offline reliability is worth highlighting. These configurations use hash-locked dependencies and run offline checks after the build completes, including a small CPU training test — essentially a "smoke test" run before delivery to confirm that the training stack in the image can actually start up. Model weights and datasets are carried separately rather than bundled into the image, which aligns with common practices for distributing large files in air-gapped environments and prevents image size from spiraling out of control.

For teams that need to fine-tune models in confidential or strictly regulated offline environments, these pre-built configurations can save considerable effort in manually assembling CUDA/PyTorch dependency stacks.

LoRA (Low-Rank Adaptation) and QLoRA are currently the most mainstream parameter-efficient fine-tuning methods. Traditional full fine-tuning requires updating all model parameters, placing extreme demands on GPU memory and compute. LoRA's approach is to freeze the pre-trained weights and insert only low-rank matrices as bypasses at each layer — reducing trainable parameters to as little as 0.1%–1% of the original, dramatically lowering hardware requirements. QLoRA goes further by quantizing the base model to 4-bit, compressing the memory needed to fine-tune a 65B parameter model down to what a single consumer GPU can handle. LLaMA-Factory is a training framework that integrates multiple PEFT methods, supporting a complete workflow from data preprocessing to export, with extensive compatibility for popular open-source models. The biggest challenge in using these tools in air-gapped environments is that the related dependencies (CUDA, cuDNN, Transformers, PEFT libraries) are tightly version-coupled — any mismatch can prevent the training stack from starting. This is precisely the risk that hash-locked dependencies and offline smoke tests are designed to mitigate.

Who It's For, and What Remains Unsolved

LayerSmith's positioning is clear: it serves ops and infrastructure teams that can't freely access the internet but need to frequently build and maintain images — defense, finance, government, and industrial control are all typical use cases. It integrates Docker/Podman build capabilities, Containerfile transparency, and the traceability required for isolated delivery into a single self-hosted interface.

The author also candidly posed an open question at launch: how are people currently building and maintaining images for air-gapped environments, and which parts of that workflow are still painful? This actually highlights the state of the field — despite mechanisms like bundling, checksums, and version pinning, image lifecycle management in air-gapped environments (updates, vulnerability patching, dependency rolling) still lacks mature, standardized approaches. LayerSmith provides a solid starting point, but it reads more like an invitation for the community to help fill in the remaining gaps.

The project is open source on GitHub. Interested readers can find more at the r0lfi/layersmith repository.