How to Use ODS in Offline or Air-Gapped Mode

ODS supports complete air-gapped operation via the --offline installation flag, which triggers an automated setup phase that disables cloud dependencies, enables local RAG, and pre-downloads required model artifacts for zero-connectivity environments.

The Osmantic/ODS repository provides a dedicated offline installation workflow for environments with strict data sovereignty or security requirements. When installed with the offline flag, ODS runs entirely within your local infrastructure using containerized LLM inference and local vector storage, requiring no external API calls or internet access after initial setup.

Triggering Offline Mode During Installation

To activate air-gapped mode, invoke the top-level installer with the --offline flag. This parameter signals install-core.sh to execute a specialized configuration phase designed for isolated networks.

The --offline Flag Implementation

In install-core.sh, the argument parser detects --offline at line 266 and sets OFFLINE_MODE=true. The installer then invokes phase 09 by executing installers/phases/09-offline.sh. This phase handles all modifications necessary to decouple ODS from external services.

# Install ODS fully offline with all services

./install.sh --offline --all

# Install with specific tier and voice support

./install.sh --offline --tier 2 --voice --rag

Configuration Changes for Air-Gapped Environments

The offline phase rewrites your environment configuration to ensure no external network traffic occurs during operation. All changes are handled automatically within installers/phases/09-offline.sh.

Marker File and Environment Isolation

At line 26 of phase 09, the installer creates a persistent marker file:

"$INSTALL_DIR/.offline-mode"

This file indicates to subsequent ODS commands that the instance operates without internet access. The installer then modifies .env between lines 28 and 48 to:

• Clear cloud API keys (lines 28-32), removing references to external LLM providers
• Disable telemetry and update checks, preventing automatic ping-backs to external servers
• Set WEB_SEARCH_ENABLED=false to block web-search capabilities
• Enable LOCAL_RAG_ENABLED=true to force retrieval-augmented generation against local vector stores only

OpenClaw Integration (Optional)

If you include the --openclaw flag during installation, phase 09 generates an offline-specific configuration at config/openclaw/openclaw-m1.yaml (lines 50-71). This file routes all tool execution through local-only endpoints, ensuring no data leaves the air-gapped perimeter.

Model and Embedding Preparation

Offline mode requires pre-downloading artifacts that are normally fetched on-demand. Phase 09 handles the essential embeddings and warns about optional components.

Local Embeddings Download

Between lines 75 and 88, the installer automatically pulls the required embedding model for memory search:

# Pre-downloaded to this location during phase 09

models/embeddings/nomic-embed-text-v1.5.Q4_K_M.gguf

This GGUF file enables the llama-server container to perform local vectorization without connecting to Hugging Face or other model repositories.

Speech-to-Text Considerations

The installer emits a warning at lines 96-102 regarding the Whisper STT model, which is too large to bundle by default. Before disconnecting from the network, run:

# Option 1: Using the ODS CLI

ods stt download

# Option 2: Using the pre-download script

scripts/pre-download.sh --with-voice

This ensures the Whisper model artifacts are cached locally in the models/ directory before entering the air-gapped environment.

Verification and Local Operation

After installation completes, verify that ODS is running in offline mode without external dependencies.

Checking Offline Status

Confirm the marker file exists and services are healthy:

# Verify offline marker

[[ -f .offline-mode ]] && echo "Offline mode enabled"

# Check local service status (no internet required)

ods status

Testing Local Inference

With ODS running offline, the LLM endpoint operates entirely within the llama-server container, and RAG queries resolve against your local Qdrant instance:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"local","messages":[{"role":"user","content":"Hello"}]}'

This endpoint functions without any external network traffic, routing all inference through the locally-hosted model.

Pre-Installation Validation

Use the validation script to confirm all required models are present before going air-gapped:

scripts/check-offline-models.sh

This script verifies that embeddings and optional voice models exist in the expected models/ subdirectories.

Documentation and Key Files

According to the ODS source code, the following files govern offline behavior:

• install-core.sh – Parses --offline and sets OFFLINE_MODE=true at line 266
• installers/phases/09-offline.sh – Implements marker creation, .env modifications, and embedding downloads
• docs/M1-OFFLINE-MODE.md – Comprehensive user guide for offline installation and troubleshooting
• scripts/pre-download.sh – Pre-pulls containers and models for slow or metered networks
• scripts/check-offline-models.sh – Validates model artifacts before air-gapping
• config/openclaw/openclaw-m1.yaml – Offline-only configuration for OpenClaw tool execution

Summary

• Use ./install.sh --offline to trigger air-gapped installation and execute phase 09 automatically
• Phase 09 creates .offline-mode marker and rewrites .env to disable cloud APIs, telemetry, and web search while enabling local RAG
• Embeddings are auto-downloaded to models/embeddings/nomic-embed-text-v1.5.Q4_K_M.gguf, but Whisper STT requires manual pre-download via ods stt download
• All inference stays local through the llama-server container and Qdrant vector store, satisfying strict compliance requirements
• Validate with scripts/check-offline-models.sh before disconnecting from the network to ensure all artifacts are present

Frequently Asked Questions

Does ODS require internet for the initial installation?

No. When using ./install.sh --offline, the installer expects all container images and model files to be present or pre-downloaded. Run scripts/pre-download.sh on a connected machine first, then transfer the entire ODS directory to your air-gapped environment. The phase 09 script handles all configuration changes without reaching out to external repositories.

What specific models are included in the offline installation?

The offline installer automatically fetches nomic-embed-text-v1.5.Q4_K_M.gguf for local embeddings (lines 75-88 of phase 09). However, the Whisper STT model used for voice transcription is excluded due to size constraints. You must manually download it using ods stt download or scripts/pre-download.sh --with-voice before entering offline mode.

Can I switch between offline and online modes after installation?

Technically yes, but it requires manual configuration changes. Remove the .offline-mode marker file and edit .env to re-enable WEB_SEARCH_ENABLED and cloud API keys. However, the ODS installer is designed for deterministic operation; switching modes is not officially supported without re-running the installation script with the appropriate flags.

How do I update ODS in an air-gapped environment?

Updates require temporarily connecting to the internet or using a "sneakernet" transfer. Download the new ODS release and updated container images on a connected machine, then transfer the artifacts to your air-gapped system. Run scripts/check-offline-models.sh after updating to verify all local model dependencies remain satisfied before resuming offline operation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}