What Is Bootstrap Mode in ODS Installation? Complete Technical Guide

Bootstrap mode is a fast-start deployment pattern in the Osmantic Data Stack (ODS) that immediately downloads and serves a lightweight ~1.2 GiB Qwen 3.5 2B model, allowing users to begin chatting while the full-tier model downloads in the background.

The Osmantic/ODS installer implements bootstrap mode to eliminate first-run latency when deploying large language models. Instead of waiting for a multi-gigabyte download to complete before starting services, the installer fetches a compact "bootstrap" model first and upgrades to the full model asynchronously. This guide examines the source code implementation, decision logic, and lifecycle management of bootstrap mode according to the Osmantic/ODS repository.

How the Installer Decides to Enable Bootstrap Mode

The decision to enter bootstrap mode centers on the bootstrap_needed() function defined in [ods/installers/lib/bootstrap-model.sh](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/bootstrap-model.sh). This function returns exit code 0 (success) only when all eligibility conditions are met, triggering the fast-start workflow.

The function validates six specific conditions:

• Tier eligibility: The selected tier rank must be greater than zero ([[ "$tier_rank" -le 0 ]]), ensuring the full model is actually larger than the bootstrap alternative.
• File absence: The target full model file must not already exist at ${INSTALL_DIR}/data/models/${GGUF_FILE}.
• No override flags: The user must not have passed --no-bootstrap ([[ "${NO_BOOTSTRAP:-false}" == "true" ]]).
• Online installation: The installer cannot be in offline mode ([[ "${OFFLINE_MODE:-false}" == "true" ]]).
• Local deployment: The system cannot be in cloud mode ([[ "${ODS_MODE:-local}" == "cloud" ]]).
• No external backend: The Lemonade service must not be configured to use an external model ([[ "${LEMONADE_EXTERNAL:-false}" == "true" ]]).

If any condition fails, the function returns 1 and the installer skips directly to the full model download.

Bootstrap Model Specifications and Configuration

When activated, the installer references constants defined in [bootstrap-model.sh](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/bootstrap-model.sh) to configure the lightweight model. The bootstrap model uses the Qwen 3.5 2B GGUF weighing approximately 1.2–1.5 GB, significantly smaller than production-tier models.

The installer patches the .env configuration file with bootstrap-specific parameters:

# Context window reduced for the lightweight model

BOOTSTRAP_CONTEXT_SIZE="65536"  # 64KiB instead of full-tier defaults

# GGUF filename constant

BOOTSTRAP_GGUF_FILE="qwen3.5-2b-instruct-q4_k_m.gguf"

Both the macOS installer ([install-macos.sh](https://github.com/Osmantic/ODS/blob/main/ods/installers/macos/install-macos.sh)) and Windows installer (install-windows.ps1) emit "Fast-start mode" messages when applying these patches, alerting users that immediate chat capability is available while the larger model downloads.

The Bootstrap Mode Lifecycle

Phase 1: Service Initialization

During phase 11 of installation, [ods/installers/phases/11-services.sh](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/11-services.sh) starts the bootstrap server before initiating the background download. The phase emits informational messages such as:

ai "Fast-start mode: downloading bootstrap model (~1.5GB) for instant chat."
ai_ok "Bootstrap server started on port ${LEMONADE_PORT}"

This allows the API to accept requests while the full model streams in the background.

Phase 2: Background Download and Verification

The [ods/scripts/bootstrap-upgrade.sh](https://github.com/Osmantic/ODS/blob/main/ods/scripts/bootstrap-upgrade.sh) script manages the asynchronous acquisition of the full-tier model. It monitors download progress, verifies SHA-256 checksums, and validates model integrity before promoting it to production.

Phase 3: Model Switchover and Cleanup

Once the full model passes verification, Phase 5b of the upgrade script removes the bootstrap artifact:

log "Removing bootstrap model after verified full-model serving: $BOOTSTRAP_GGUF"
rm -f "${INSTALL_DIR}/data/models/${BOOTSTRAP_GGUF_FILE}"

The system then transitions to the full model without requiring a service restart.

Phase 4: User Status Notification

The installation summary phase ([ods/installers/phases/13-summary.sh](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/13-summary.sh)) displays the current model status, distinguishing between active bootstrap and full models:

echo "Using bootstrap model (${BOOTSTRAP_GGUF_FILE}); Full model (${GGUF_FILE}) downloading..."

Implementation Examples

Checking bootstrap eligibility programmatically:

# Source the bootstrap library

source ods/installers/lib/bootstrap-model.sh

if bootstrap_needed; then
    echo "✅ Bootstrap mode enabled – downloading ${BOOTSTRAP_GGUF_FILE} first"
    export USE_BOOTSTRAP=true
else
    echo "❌ Bootstrap mode skipped – using full model directly"
    export USE_BOOTSTRAP=false
fi

Patching environment configuration for bootstrap:

# Fragment from macOS installer

if [[ "${USE_BOOTSTRAP}" == "true" ]]; then
    sed -i '' "s/^MODEL_FILE=.*/MODEL_FILE=${BOOTSTRAP_GGUF_FILE}/" .env
    sed -i '' "s/^CONTEXT_SIZE=.*/CONTEXT_SIZE=${BOOTSTRAP_CONTEXT_SIZE}/" .env
    ai_ok "Patched .env for bootstrap model (${BOOTSTRAP_GGUF_FILE})"
fi

Post-upgrade cleanup:

# From bootstrap-upgrade.sh Phase 5b

if [[ -f "${INSTALL_DIR}/data/models/${FULL_GGUF_FILE}" ]]; then
    log "Verified full model present, cleaning up bootstrap artifact"
    rm -f "${INSTALL_DIR}/data/models/${BOOTSTRAP_GGUF_FILE}"
fi

Summary

• Bootstrap mode provides immediate LLM functionality via a ~1.2 GiB Qwen 3.5 2B model while larger models download asynchronously.
• The bootstrap_needed() function enforces six strict conditions before activation, including tier rank, file existence, and runtime flags.
• Installation phases in [11-services.sh](https://github.com/Osmantic/ODS/blob/main/ods/installers/phases/11-services.sh) start the bootstrap server immediately, while [bootstrap-upgrade.sh](https://github.com/Osmantic/ODS/blob/main/ods/scripts/bootstrap-upgrade.sh) manages background retrieval and cleanup.
• The installer automatically removes the bootstrap model after verifying the full-tier model is operational, ensuring zero manual intervention during the upgrade cycle.

Frequently Asked Questions

What triggers bootstrap mode in ODS installation?

Bootstrap mode triggers when the bootstrap_needed() function detects a tier rank greater than zero, confirms the full model file is absent from disk, and verifies the user has not disabled the feature via --no-bootstrap or offline mode flags. The installer then prioritizes the lightweight model to eliminate cold-start delays.

How large is the bootstrap model compared to full ODS models?

The bootstrap model is a Qwen 3.5 2B GGUF weighing approximately 1.2–1.5 GB, whereas full-tier models can exceed 4–70 GB depending on the selected tier. This size differential allows the bootstrap model to download and load in under a minute on most connections, while the full model may require significantly longer transfer times.

Can I disable bootstrap mode during installation?

Yes. Pass the --no-bootstrap flag or set the environment variable NO_BOOTSTRAP=true before running the installer. When this flag is detected, the bootstrap_needed() function returns false, forcing the installer to wait for the complete full-tier model download before starting services.

When does the installer remove the bootstrap model?

The installer removes the bootstrap model during Phase 5b of the upgrade process, implemented in [ods/scripts/bootstrap-upgrade.sh](https://github.com/Osmantic/ODS/blob/main/ods/scripts/bootstrap-upgrade.sh). This cleanup occurs only after the script verifies the full model file exists, passes SHA-256 checksum validation, and successfully responds to health checks, ensuring zero service interruption during the transition.

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