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

> Learn the Wigolo warmup process to download browsers embeddings and reranker models for offline operation. Ensure your Wigolo installation is ready with this essential guide.

- Repository: [Towhid Khan/wigolo](https://github.com/KnockOutEZ/wigolo)
- Tags: how-to-guide
- Published: 2026-07-19

---

**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](https://github.com/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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:

```bash
npx wigolo warmup --browser

```

This executes `installBrowser('chromium')` from [`src/fetch/browser-acquire.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/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:

```bash
npx wigolo warmup --embeddings

```

The command imports [`src/embedding/fastembed-provider.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/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:

```bash
npx wigolo warmup --reranker

```

This loads the provider from [`src/providers/rerank-provider.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/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:

```bash
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`](https://github.com/KnockOutEZ/wigolo/blob/main/src/cli/warmup.ts)** – Core orchestrator containing `runWarmup`, flag parsing logic, and result aggregation.
- **[`src/fetch/browser-acquire.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/fetch/browser-acquire.ts)** – Low-level Playwright integration with `installBrowser` and `probeBrowser` utilities.
- **[`src/embedding/fastembed-provider.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/embedding/fastembed-provider.ts)** – Fastembed implementation that handles ONNX model downloads and warmup tests.
- **[`src/providers/rerank-provider.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/providers/rerank-provider.ts)** – Factory for cross-encoder reranker instances used during model certification.
- **[`src/searxng/bootstrap.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/searxng/bootstrap.ts)** – Native SearxNG sidecar preparation and Python environment validation.
- **[`src/tui/verify.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/src/fetch/browser-acquire.ts), supporting Chromium, Firefox, and WebKit engines.
- **Embedding models** download through the Fastembed provider in [`src/embedding/fastembed-provider.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/embedding/fastembed-provider.ts), while **reranker models** load via [`src/providers/rerank-provider.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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.