Update an air-gapped AI stack
Plan offline AI updates with versioned model bundles, provenance checks, dependency closure, isolated validation and a practical rollback record.
Last updated
In short
- An offline application setting is not a network isolation boundary.
- Transfer model, tokenizer, runtime and licence dependencies together.
- Keep a complete prior bundle and matching state for rollback.
On this page (6)
Architectures · Part of Air-gapped
Editable manifest for provenance, dependencies, approval and rollback evidence.
Download the update-bundle manifestMake updates a controlled import process
An air-gapped AI environment cannot depend on downloading a missing tokenizer, checking an online licence or fetching a package at first use. Updates must arrive as a complete, reviewed bundle that can be installed and validated without an external connection. The bundle includes more than model weights.
This is a reference update architecture and an editable manifest, not a claim that an isolated installation has been demonstrated. The actual isolation mechanism, transfer media, approval roles and support process must be agreed for the environment described on the air-gapped platform page.
Use three distinct zones
| Zone | Permitted work | Boundary evidence |
|---|---|---|
| Connected preparation | Download approved upstream releases and dependencies | Source URLs, revisions, hashes and licence records |
| Inspection and staging | Scan, verify provenance and assemble the bundle | Review record and reproducible manifest |
| Isolated production | Import approved bundle and run local validation | Transfer log, installation record and denied-egress evidence |
The transfer mechanism should not become an unnoticed bridge between connected and isolated networks. Define who can prepare, approve and import a bundle. Preserve a record of the physical or logical transfer and verify the bundle’s identity again after import.
A checksum establishes that two files match; it does not prove that the original publisher was trustworthy. Where upstream signatures or attestations are available, verify their identity and provenance under the organization’s trust policy. Keep the evidence alongside the manifest.
Define dependency closure
| Bundle item | Required identifier | Common missing dependency |
|---|---|---|
| Model weights | Repository and immutable revision | Additional weight shards |
| Tokenizer and configuration | Same approved model revision | Vocabulary or custom configuration file |
| Embedding and reranking models | Separate pinned revisions | First-use automatic download |
| Runtime image | Image digest and platform | GPU runtime or shared library |
| Host prerequisites | OS and driver versions | Compatible accelerator driver |
| Application extensions | Reviewed source and dependency lock | Packages installed dynamically at startup |
| Licence material | Applicable terms and offline entitlement | Activation or renewal requiring connectivity |
| Evaluation fixtures | Versioned synthetic prompts and documents | Expected source references |
Hugging Face documents downloads by revision and repository snapshots. Prefer immutable revisions over a moving branch when building a release bundle. Record whether the selected model requires executing repository-supplied code; that is an additional code-review decision, not merely a model-file download.
The application, runtime and model can each have different licences. Verify permission to transfer and use the artifacts in the intended environment, including any commercial support or offline activation arrangements. Do not infer those rights from public download availability.
Do not confuse offline mode with an air gap
Open WebUI’s configuration reference explains that offline mode suppresses selected automatic downloads and update checks. It also states that external model APIs, OAuth providers and external search paths can remain functional. Therefore an application flag cannot establish network isolation.
Enforce the intended boundary at the network and operating-system layers. Review configured model providers, tools, plugins, telemetry destinations, package managers, time synchronization and identity dependencies. A local model server also needs access control: the vLLM security guide warns against relying only on its API-key option as the complete protection model.
Validate the bundle before importing real data
Start the candidate stack in an isolated staging environment with external egress denied. Confirm that it starts from a cold state with only the imported artifacts. Then exercise document upload, embedding, retrieval, inference, authentication and any approved tool invocation. A container reaching a healthy state does not prove that its first substantive request has all dependencies available.
Use a fixed synthetic evaluation set with expected source documents and clearly defined unacceptable outcomes. Record latency and resource use on the actual hardware, but treat them as pilot measurements rather than general model claims. Include an intentionally missing artifact to confirm that failure is explicit and does not trigger an outside download attempt.
Inspect network-denial logs, application logs and disk growth during the exercise. Avoid retaining sensitive prompts in operational records. For a fully isolated identity service, test authentication after a restart without access to an external directory.
Make rollback a complete release operation
Keep the prior approved bundle, its configuration and the compatible application data backup. An application update may migrate its database; a runtime update may change model-cache formats; a new embedding model may require a new index. Returning only to an old container image can leave those states incompatible.
Define the rollback trigger before the change: failed acceptance cases, unacceptable resource use, broken authentication or unexplained external connection attempts. Pause new work, preserve diagnostic records and restore the coordinated prior state. If users created new conversations or documents after the update, decide how that data is exported or reconciled before restoring older storage.
An update is accepted when the imported manifest matches, cold-start dependency checks pass, the evaluation set meets its criteria and recovery has a credible recorded procedure. Schedule a separate review for urgent security fixes so isolation does not become an excuse for indefinitely unpatched software.
Sources and further reading
Use the linked documentation to confirm the version, edition and contract that apply to your project.
