feat: Support fully air-gapped installation and first run #95

Feature request: Support fully air-gapped installation and first run

Summary

Please add first-class support for running Open WebUI Computer (cptr) in fully air-gapped environments.

Currently, cptr can be used offline only after it has already been installed, built, or started once in an internet-connected environment. For secure, regulated, enterprise, government, lab, and isolated development environments, this is a major deployment blocker.

The expected behavior is that an operator can download release artifacts in a connected environment, transfer them into an offline environment, and install/start cptr without any network access, dependency resolution, package-manager downloads, registry access, or update checks.

Why this matters

Air-gapped users cannot rely on:

• PyPI being reachable during installation
• npm registry access during frontend build
• apt repositories during image build
• uvx resolving packages on first run
• npm/pip/uv caches already existing
• optional dependencies being installed interactively later
• remote update checks or provider/model discovery during startup

For these environments, the base product must be installable and startable with zero outbound network access.

Current situation

The documented install paths currently rely on online package resolution:

pip install cptr
cptr run

Optional features require additional installs:

pip install 'cptr[mcp]'
pip install 'cptr[all]'

The README also documents:

uvx cptr@latest run

This is convenient for normal users, but it is not suitable for air-gapped deployments because the first invocation may resolve/download packages.

The Docker build path also depends on external package sources during build:

• npm ci for frontend dependencies
• uv build
• apt-get install
• uv pip install "$wheel[all]"

This makes the image build itself unsuitable inside an offline environment unless all upstream package sources have already been mirrored or cached.

Requested behavior

Please provide an officially supported air-gapped deployment path.

At minimum, users should be able to do the following:

1. In an internet-connected environment:

   • Download a versioned cptr release bundle.
   • Download all required Python wheels.
   • Download the prebuilt frontend assets.
   • Download or export a prebuilt OCI/Docker image.
   • Verify checksums/signatures.

2. Transfer the artifacts into an offline environment.

3. In the offline environment:

   • Install cptr without contacting PyPI.
   • Start cptr without contacting PyPI, npm, apt, GitHub, or any other public endpoint.
   • Run the web UI, file browser, editor, terminal, git integration, workspaces, local config, and local model/provider endpoints.
   • Use local providers such as Ollama or OpenAI-compatible local endpoints.
   • Disable or gracefully fail optional online-only features.

Proposed artifacts

It would be very helpful if each release included:

1. Offline Python bundle

A platform-specific wheelhouse, for example:

cptr-<version>-wheelhouse-linux-amd64.tar.gz
cptr-<version>-wheelhouse-linux-arm64.tar.gz
cptr-<version>-wheelhouse-macos-arm64.tar.gz
cptr-<version>-wheelhouse-windows-amd64.zip

The offline installation should work with something like:

python -m venv .venv
. .venv/bin/activate
pip install --no-index --find-links ./wheelhouse 'cptr[all]'
cptr run --host 0.0.0.0

No package should be downloaded during that process.

2. Offline OCI image artifact

Publish or attach a prebuilt image archive that can be transferred directly:

docker load < cptr-<version>-linux-amd64.oci.tar
docker run --rm -it \
  --network=none \
  -p 8000:8000 \
  -v cptr-data:/data \
  -v "$PWD:/workspace" \
  -w /workspace \
  ghcr.io/open-webui/computer:<version>

This should start successfully without any outbound network access.

3. Checksums and SBOM

Please provide:

SHA256SUMS
SHA256SUMS.sig
SBOM

This is important for controlled environments where artifacts need to be reviewed before import.

Offline mode

A dedicated offline mode would make this much safer and more predictable:

CPTR_OFFLINE=1 cptr run

or:

cptr run --offline

In offline mode, cptr should not attempt:

• GitHub release/update checks
• remote web search fallback
• DuckDuckGo fallback
• remote OpenAPI discovery unless explicitly configured for an internal endpoint
• external provider model discovery unless explicitly triggered
• remote agent/model probes that require internet
• any automatic package-manager install
• any npm/pip/uv/apt invocation

Optional online features should remain available when explicitly configured, but the default air-gapped startup path should be quiet and deterministic.

Optional dependencies

For true air-gapped usage, optional features need a clear policy:

• Either include all dependencies advertised by cptr[all].
• Or document which features are intentionally excluded from the offline bundle.
• Avoid runtime messages that simply say pip install ... without also explaining the offline installation path.

For example, document extraction currently has lazy optional imports for additional file types. In an air-gapped environment, users cannot resolve those interactively after startup. Those dependencies should either be included in the full offline bundle or clearly documented as unavailable unless pre-bundled.

Acceptance criteria

• A fresh offline environment can install cptr from release artifacts using pip --no-index.
• A fresh offline environment can run the official Docker/OCI artifact with --network=none.
• First startup succeeds without PyPI, npm, apt, GitHub, or registry access.
• The frontend loads completely from local/static assets.
• /api/health works offline.
• Initial setup/auth works offline.
• File browser, editor, terminal, git UI, and workspaces work offline.
• Local model providers such as Ollama or local OpenAI-compatible endpoints can be configured offline.
• Online-only features fail gracefully or are disabled in offline mode.
• CI includes at least one network-disabled smoke test.
• Documentation includes a complete “Air-gapped installation” section.

Suggested CI test

Add a release smoke test similar to:

docker run --rm --network=none \
  -p 8000:8000 \
  -v cptr-data:/data \
  -v "$PWD:/workspace" \
  -w /workspace \
  ghcr.io/open-webui/computer:<version>

Then verify:

curl http://localhost:8000/api/health
curl http://localhost:8000/

For Python artifacts, test:

python -m venv .venv
. .venv/bin/activate
pip install --no-index --find-links ./wheelhouse 'cptr[all]'
CPTR_OFFLINE=1 cptr run --headless

No network access should be required at any step after artifacts have been transferred.

Expected result

Open WebUI Computer should be deployable in a fully disconnected environment as a self-contained workstation UI. Internet-dependent features can remain optional, but installation, startup, core UI, local filesystem access, terminal, editor, git, workspaces, and local model/provider usage should not require an internet-connected first run.