MiniSearch Server Environment Variables: Complete Configuration Reference

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 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, the server compares SHA-256 hashes of incoming keys against the ACCESS_KEYS list:

// 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.

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:

// 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.

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 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, while the display name is handled in vite.config.ts at line 52.

Model Handling and Inference Defaults

Located in 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.

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.

Default Inference Backend

The DEFAULT_INFERENCE_TYPE variable (line 55 of 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:

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:

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:

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

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:

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
• 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 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, 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 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.

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