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 manifest

Make 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.

Scope our isolated AI environment

Bring the isolation mechanism, approved transfer process, hardware inventory and required offline support arrangements.