Wigolo Warmup Process: How to Download Browser Binaries, Embeddings, and Reranker Models

The wigolo warmup command orchestrates the pre-installation and verification of all optional runtime dependencies—including Playwright browsers, Fastembed embedding models, and cross-encoder rerankers—ensuring your wigolo installation operates offline after initial setup.

The warmup system in the KnockOutEZ/wigolo repository eliminates cold-start delays by downloading machine learning models and browser binaries before they are needed at runtime. Located in src/cli/warmup.ts, the runWarmup function executes a sequential validation flow that guarantees every component from Chromium engines to SearxNG sidecars is present and functional.

How the Wigolo Warmup Process Works

When you execute npx wigolo warmup, the CLI runs a single orchestrated flow defined in src/cli/warmup.ts. The runWarmup function coordinates eight distinct phases that prepare your environment for semantic search operations.

Initialization and Flag Parsing

The process begins by parsing CLI flags and configuring output formats. If you pass --force, the system calls wipeSearxngState to clear existing SearxNG bootstrap data before reinstallation. The reporter initializes in either TUI or plain text mode based on the --plain flag.

Browser Engine Acquisition

The installPlaywright function triggers installBrowser('chromium') to download Playwright's bundled Chromium binary. On Linux systems, this also installs required OS libraries before launching a smoke test to verify the engine launches correctly. Optional flags --firefox or --webkit invoke additional calls to installBrowser('firefox') or installBrowser('webkit') respectively.

ML Model Downloads

For semantic search capabilities, installEmbeddings dynamically imports the Fastembed provider from src/embedding/fastembed-provider.ts and executes a test embedding via embed(['warmup']). Similarly, installReranker loads the cross-encoder provider via getRerankProvider from src/providers/rerank-provider.ts and performs a one-shot rerank operation to certify the model functions correctly.

SearxNG Sidecar Bootstrap

When --searxng or --all is specified, runSearxngPhase checks for Python and virtual environment dependencies before invoking bootstrapNativeSearxng from src/searxng/bootstrap.ts. This prepares the native search engine sidecar that wigolo uses for web retrieval.

Verification and Reporting

Unless --skip-verify is set, runVerify from src/tui/verify.ts executes a final "doctor" check that reloads all components to confirm end-to-end functionality. Results aggregate into a WarmupResult object printed to stdout, with optional JSON output via --json for CI pipeline integration.

Manually Triggering Downloads in Wigolo

You can selectively execute specific warmup phases using targeted CLI flags. This allows you to download only the components required for your use case without waiting for unnecessary installations.

Download Browser Binaries Only

To install only the default Chromium engine without ML models or sidecars:

npx wigolo warmup --browser

This executes installBrowser('chromium') from src/fetch/browser-acquire.ts and runs a launch test to verify the binary works on your system.

Download Embedding Models

For semantic search functionality, trigger the Fastembed model download:

npx wigolo warmup --embeddings

The command imports src/embedding/fastembed-provider.ts, downloads the ONNX model, and validates it by generating a test vector.

Download the Reranker Model

To prepare the cross-encoder for relevance scoring:

npx wigolo warmup --reranker

This loads the provider from src/providers/rerank-provider.ts, pulls the model weights, and performs a certification rerank to ensure the scoring pipeline operates correctly.

Complete Installation

For fresh machines or CI environments, run the full warmup sequence:

npx wigolo warmup --all --verify

The --all flag executes every optional step including Chromium, Firefox, WebKit, embeddings, reranker, and SearxNG bootstrap. The --verify flag adds a final validation pass that proves all components load successfully.

Key Source Files in the Wigolo Warmup System

Understanding the architecture helps when debugging warmup failures or extending functionality:

• src/cli/warmup.ts – Core orchestrator containing runWarmup, flag parsing logic, and result aggregation.
• src/fetch/browser-acquire.ts – Low-level Playwright integration with installBrowser and probeBrowser utilities.
• src/embedding/fastembed-provider.ts – Fastembed implementation that handles ONNX model downloads and warmup tests.
• src/providers/rerank-provider.ts – Factory for cross-encoder reranker instances used during model certification.
• src/searxng/bootstrap.ts – Native SearxNG sidecar preparation and Python environment validation.
• src/tui/verify.ts – Post-installation verification suite that reloads components to confirm operational status.

Summary

• The wigolo warmup command in src/cli/warmup.ts orchestrates pre-installation of all optional runtime dependencies through the runWarmup function.
• Browser binaries are managed via installBrowser calls in src/fetch/browser-acquire.ts, supporting Chromium, Firefox, and WebKit engines.
• Embedding models download through the Fastembed provider in src/embedding/fastembed-provider.ts, while reranker models load via src/providers/rerank-provider.ts.
• Use specific flags (--browser, --embeddings, --reranker) to download individual components, or --all for complete setup.
• The --verify flag triggers runVerify to perform end-to-end validation that all downloaded components function correctly.

Frequently Asked Questions

What is the difference between --all and running individual warmup flags?

The --all flag executes every optional installation phase—including Chromium, Firefox, WebKit, embeddings, reranker, and SearxNG bootstrap—in a single command. Individual flags like --browser or --embeddings invoke only their specific install* functions, saving time when you need just one component.

How do I force a fresh download of warmup components?

Pass the --force flag to clear existing SearxNG bootstrap state via wipeSearxngState before reinstallation. For browser binaries, Playwright manages its own cache, but --force ensures the SearxNG sidecar reinitializes from scratch.

Can I run wigolo warmup without installing all browsers?

Yes. Omit --all and use --browser to install only Chromium, or combine specific flags like --browser --embeddings to skip Firefox and WebKit. This is useful on Linux servers where you only need the default Chromium engine for headless operations.

What does the --verify flag check during warmup?

The --verify flag invokes runVerify from src/tui/verify.ts to reload every installed component and confirm it operates correctly. This catches corrupted downloads or missing dependencies by actually executing the browser launch, embedding generation, and rerank operations rather than just checking file existence.

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