# MiniSearch Server Environment Variables: Complete Configuration Reference

> Explore over 18 MiniSearch server environment variables for complete configuration of security, networking AI routing, and model behavior. Get full details now.

- Repository: [Victor Nogueira/minisearch](https://github.com/felladrin/minisearch)
- Tags: api-reference
- Published: 2026-03-01

---

**MiniSearch reads 18+ server environment variables at startup to configure security, networking, internal AI API routing, and model behavior, with all values parsed from `process.env` in [`vite.config.ts`](https://github.com/felladrin/minisearch/blob/main/vite.config.ts) and the server hooks.**

MiniSearch, the open-source AI-powered search interface in the `felladrin/minisearch` repository, uses server environment variables to customize everything from access key validation to model retry logic. These variables are evaluated when the Vite server initializes and affect both the development preview server and internal API proxy endpoints.

## Security Configuration

MiniSearch provides optional access key validation to protect the search interface. When enabled, clients must present a valid hashed key to the validation endpoint.

### Access Key Validation

The **`ACCESS_KEYS`** variable accepts a comma-separated list of pre-hashed access keys. When defined, clients can validate against these keys via the `/api/validate-access-key` endpoint. If undefined, the endpoint returns disabled.

The **`ACCESS_KEY_TIMEOUT_HOURS`** variable controls how long a validated key remains active. Set to `0` to disable expiration entirely (default behavior).

In [`server/validateAccessKeyServerHook.ts`](https://github.com/felladrin/minisearch/blob/main/server/validateAccessKeyServerHook.ts), the server compares SHA-256 hashes of incoming keys against the `ACCESS_KEYS` list:

```typescript
// server/validateAccessKeyServerHook.ts
const accessKeys = process.env.ACCESS_KEYS?.split(",") ?? [];
const timeoutHours = Number(process.env.ACCESS_KEY_TIMEOUT_HOURS ?? "0");

```

## Server Networking and SSL

MiniSearch uses Vite's dev/preview server, configurable through networking variables found in [`vite.config.ts`](https://github.com/felladrin/minisearch/blob/main/vite.config.ts).

### Host and Port Configuration

- **`HOST`** – Binds the server to a specific interface (defaults to Vite's `localhost`)
- **`PORT`** – Sets the TCP port for HTTP traffic
- **`HMR_PORT`** – Configures the WebSocket port for hot-module reloading

These are defined at lines 69-72 of [`vite.config.ts`](https://github.com/felladrin/minisearch/blob/main/vite.config.ts):

```typescript
// vite.config.ts
host: process.env.HOST,
port: process.env.PORT ? Number(process.env.PORT) : undefined,
hmr: { port: process.env.HMR_PORT ? Number(process.env.HMR_PORT) : undefined },

```

### Preview Security and HTTPS

The **`ALLOWED_HOSTS`** variable accepts a comma-separated whitelist of hostnames for the preview server. When empty, all hosts are permitted (default: `*`).

Setting **`BASIC_SSL=true`** enables the `@vitejs/plugin-basic-ssl` plugin, providing self-signed certificates for local HTTPS development. This is checked at line 95 of [`vite.config.ts`](https://github.com/felladrin/minisearch/blob/main/vite.config.ts).

## Internal OpenAI-Compatible API

MiniSearch can proxy requests to a self-hosted OpenAI-compatible service (such as Ollama or vLLM) through an internal endpoint.

### Required Connection Settings

Two variables are mandatory to enable the `/api/openai` endpoint:

- **`INTERNAL_OPENAI_COMPATIBLE_API_BASE_URL`** – The base URL of the external service
- **`INTERNAL_OPENAI_COMPATIBLE_API_KEY`** – The authentication key for that service

If either is missing, the endpoint returns a 500 error. These are consumed in [`server/internalApiEndpointServerHook.ts`](https://github.com/felladrin/minisearch/blob/main/server/internalApiEndpointServerHook.ts) at lines 173-174.

### Optional Model Configuration

- **`INTERNAL_OPENAI_COMPATIBLE_API_MODEL`** – Specifies the default model when clients omit one (auto-selected if undefined)
- **`INTERNAL_OPENAI_COMPATIBLE_API_NAME`** – Sets a human-readable display name in the UI (defaults to `"openai"`)

The model selection logic appears at line 226 of [`internalApiEndpointServerHook.ts`](https://github.com/felladrin/minisearch/blob/main/internalApiEndpointServerHook.ts), while the display name is handled in [`vite.config.ts`](https://github.com/felladrin/minisearch/blob/main/vite.config.ts) at line 52.

## Model Handling and Inference Defaults

Located in [`server/config/modelConfig.ts`](https://github.com/felladrin/minisearch/blob/main/server/config/modelConfig.ts), these variables control retry logic, timeouts, and generation parameters for model requests.

### Retry and Timeout Behavior

- **`MODEL_MAX_RETRIES`** – Maximum retry attempts for failed requests
- **`MODEL_BASE_BACKOFF_MS`** – Initial delay for exponential backoff
- **`MODEL_MAX_BACKOFF_MS`** – Upper limit for backoff duration
- **`MODEL_REQUEST_TIMEOUT_MS`** – HTTP request timeout in milliseconds
- **`MODEL_MAX_CONCURRENT_REQUESTS`** – Limit on parallel model calls

These are parsed at lines 33-45 of [`modelConfig.ts`](https://github.com/felladrin/minisearch/blob/main/modelConfig.ts).

### Generation Parameters

- **`MODEL_DEFAULT_MAX_TOKENS`** – Token limit for completions
- **`MODEL_TEMPERATURE`** – Sampling temperature (float)
- **`MODEL_TOP_P`** – Nucleus sampling threshold
- **`MODEL_FREQUENCY_PENALTY`** – Penalty for token repetition
- **`MODEL_PRESENCE_PENALTY`** – Penalty for concept repetition

Found at lines 48-60 of [`modelConfig.ts`](https://github.com/felladrin/minisearch/blob/main/modelConfig.ts).

### Default Inference Backend

The **`DEFAULT_INFERENCE_TYPE`** variable (line 55 of [`vite.config.ts`](https://github.com/felladrin/minisearch/blob/main/vite.config.ts)) selects the default client-side engine (`webgpu`, `webllm`, `wllama`, etc.). When undefined, MiniSearch auto-selects the first supported backend.

## Practical Configuration Examples

### Enabling the Internal AI API

Create a `.env` file to route OpenAI-compatible requests to a local Ollama instance:

```bash
INTERNAL_OPENAI_COMPATIBLE_API_BASE_URL=https://my-ollama.local:11434
INTERNAL_OPENAI_COMPATIBLE_API_KEY=sk-local-secret
INTERNAL_OPENAI_COMPATIBLE_API_MODEL=llama3.1
INTERNAL_OPENAI_COMPATIBLE_API_NAME="Local Ollama"

```

Test the proxy with:

```bash
curl "http://localhost:5173/api/openai" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}'

```

### Securing the Interface with Access Keys

Generate hashed keys and enable validation:

```bash

# .env

ACCESS_KEYS=$(echo -n "secret-key-1" | sha256sum | cut -d' ' -f1),$(echo -n "secret-key-2" | sha256sum | cut -d' ' -f1)
ACCESS_KEY_TIMEOUT_HOURS=24

```

Client-side validation:

```typescript
const response = await fetch("/api/validate-access-key", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ accessKeyHash: await sha256(userInput) }),
});
const { valid } = await response.json();

```

### Tuning Model Resilience

Configure aggressive retry logic for unstable connections:

```bash
MODEL_MAX_RETRIES=5
MODEL_BASE_BACKOFF_MS=100
MODEL_MAX_BACKOFF_MS=5000
MODEL_REQUEST_TIMEOUT_MS=30000
MODEL_TEMPERATURE=0.8
MODEL_TOP_P=0.95

```

## Summary

- **Security**: `ACCESS_KEYS` and `ACCESS_KEY_TIMEOUT_HOURS` gate the validation endpoint in [`validateAccessKeyServerHook.ts`](https://github.com/felladrin/minisearch/blob/main/validateAccessKeyServerHook.ts)
- **Networking**: `HOST`, `PORT`, `HMR_PORT`, `ALLOWED_HOSTS`, and `BASIC_SSL` configure the Vite server binding and HTTPS
- **Internal API**: `INTERNAL_OPENAI_COMPATIBLE_API_*` variables enable the `/api/openai` proxy to external AI services
- **Model Behavior**: `MODEL_*` variables in [`modelConfig.ts`](https://github.com/felladrin/minisearch/blob/main/modelConfig.ts) control retries, timeouts, and sampling parameters
- **UI Defaults**: `DEFAULT_INFERENCE_TYPE` sets the preferred client-side inference engine

All environment variables are optional; MiniSearch disables related features or uses library defaults when values are omitted.

## Frequently Asked Questions

### What happens if the internal OpenAI API variables are not set?

The `/api/openai` endpoint remains functional but returns a 500 error for all requests. According to [`internalApiEndpointServerHook.ts`](https://github.com/felladrin/minisearch/blob/main/internalApiEndpointServerHook.ts), both `INTERNAL_OPENAI_COMPATIBLE_API_BASE_URL` and `INTERNAL_OPENAI_COMPATIBLE_API_KEY` are required to enable the proxy functionality.

### How do I enable HTTPS for local development?

Set `BASIC_SSL=true` in your environment. This loads the `@vitejs/plugin-basic-ssl` Vite plugin, which generates self-signed certificates automatically. This is defined at line 95 of [`vite.config.ts`](https://github.com/felladrin/minisearch/blob/main/vite.config.ts) and is intended only for development, not production.

### What format should I use for ACCESS_KEYS?

Provide SHA-256 hashes as a comma-separated string with no spaces. For example: `a1b2c3...,d4e5f6...`. The server hashes incoming keys using the same algorithm and compares them against this list in constant time to prevent timing attacks.

### Do the MODEL_* variables affect client-side inference?

No. Variables like `MODEL_TEMPERATURE` and `MODEL_MAX_RETRIES` only affect server-side requests proxied through the internal OpenAI-compatible API endpoint. Client-side inference engines (WebGPU, WebLLM) use parameters sent from the browser or defaults compiled into the client bundle.