# How to Use ODS in Offline or Air-Gapped Mode > Learn how to use ODS in offline or air-gapped mode with the --offline flag. Enable local RAG and pre-download models for zero-connectivity environments. Get started with secure, offline operation today. - Repository: [Osmantic/ODS](https://github.com/Osmantic/ODS) - Tags: how-to-guide - Published: 2026-08-30 --- **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`](https://github.com/Osmantic/ODS/blob/main/install-core.sh) to execute a specialized configuration phase designed for isolated networks. ### The `--offline` Flag Implementation In [`install-core.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/installers/phases/09-offline.sh). This phase handles all modifications necessary to decouple ODS from external services. ```bash # 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`](https://github.com/Osmantic/ODS/blob/main/installers/phases/09-offline.sh). ### Marker File and Environment Isolation At line 26 of phase 09, the installer creates a persistent marker file: ```bash "$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`](https://github.com/Osmantic/ODS/blob/main/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: ```bash # 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: ```bash # 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: ```bash # 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: ```bash 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: ```bash 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`](https://github.com/Osmantic/ODS/blob/main/install-core.sh)** – Parses `--offline` and sets `OFFLINE_MODE=true` at line 266 - **[`installers/phases/09-offline.sh`](https://github.com/Osmantic/ODS/blob/main/installers/phases/09-offline.sh)** – Implements marker creation, `.env` modifications, and embedding downloads - **[`docs/M1-OFFLINE-MODE.md`](https://github.com/Osmantic/ODS/blob/main/docs/M1-OFFLINE-MODE.md)** – Comprehensive user guide for offline installation and troubleshooting - **[`scripts/pre-download.sh`](https://github.com/Osmantic/ODS/blob/main/scripts/pre-download.sh)** – Pre-pulls containers and models for slow or metered networks - **[`scripts/check-offline-models.sh`](https://github.com/Osmantic/ODS/blob/main/scripts/check-offline-models.sh)** – Validates model artifacts before air-gapping - **[`config/openclaw/openclaw-m1.yaml`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/scripts/check-offline-models.sh) after updating to verify all local model dependencies remain satisfied before resuming offline operation.