# What Is Bootstrap Mode in ODS Installation? Complete Technical Guide

> Understand Bootstrap mode for ODS installation. Get ODS running quickly with a lightweight model while the full version downloads in the background. Start chatting instantly.

- Repository: [Osmantic/ODS](https://github.com/Osmantic/ODS)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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)](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/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:

```bash

# 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/install-macos.sh)](https://github.com/Osmantic/ODS/blob/main/ods/installers/macos/install-macos.sh)) and Windows installer ([`install-windows.ps1`](https://github.com/Osmantic/ODS/blob/main/ods/installers/windows/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)](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:

```bash
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)](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:

```bash
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)](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:

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

```

## Implementation Examples

**Checking bootstrap eligibility programmatically:**

```bash

# 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:**

```bash

# 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:**

```bash

# 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()`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/bootstrap-model.sh) 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/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/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()`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/bootstrap-model.sh) 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()`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/bootstrap-model.sh) 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)](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.