# How to Connect Vane to an External SearxNG Instance: Complete Configuration Guide

> Easily connect Vane to an external SearxNG instance using the SEARXNG_API_URL environment variable or config.json. Configure your SearxNG URL and enhance your search experience now.

- Repository: [Kushagra Srivastava/Vane](https://github.com/ItzCrazyKns/Vane)
- Tags: how-to-guide
- Published: 2026-03-11

---

**You can connect Vane to any external SearxNG instance by setting the `SEARXNG_API_URL` environment variable or the `search.searxngURL` value in [`config.json`](https://github.com/ItzCrazyKns/Vane/blob/main/config.json) to your instance's base URL, such as `https://search.my-domain.com`.**

Vane is an open-source AI search interface that delegates web search responsibilities to a configurable SearxNG backend. Connecting to an external SearxNG instance requires zero code changes—simply update the configuration value that Vane reads at runtime. This guide explains the exact implementation details found in the ItzCrazyKns/Vane repository and provides practical configuration examples.


## Configuration Methods

Vane reads the SearxNG endpoint URL from two sources, checked in priority order: the environment variable `SEARXNG_API_URL` overrides the `search.searxngURL` key in [`config.json`](https://github.com/ItzCrazyKns/Vane/blob/main/config.json).

### Using Environment Variables

For production deployments using Docker or Kubernetes, set the environment variable before starting the application:

```bash
export SEARXNG_API_URL="https://search.my-domain.com"
npm start

```

This approach keeps sensitive URLs out of version-controlled configuration files and simplifies secret management in containerized environments.

### Using config.json

For local development or static deployments, edit the [`config.json`](https://github.com/ItzCrazyKns/Vane/blob/main/config.json) file directly:

```json
{
  "version": 1,
  "setupComplete": false,
  "preferences": {},
  "personalization": {},
  "modelProviders": [],
  "search": {
    "searxngURL": "https://search.my-domain.com"
  }
}

```

The configuration loader in [`src/lib/config/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts) (lines 104-115) merges these values at startup, defaulting to an empty string if neither source is provided.


## How the Integration Works

The connection to an external SearxNG instance follows a three-layer architecture: configuration loading, registry access, and request execution.

### Configuration Loading

The `ConfigManager` class in [`src/lib/config/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts) handles the initial ingestion of settings. It checks for the `SEARXNG_API_URL` environment variable first, then falls back to the `search.searxngURL` key in [`config.json`](https://github.com/ItzCrazyKns/Vane/blob/main/config.json). This logic ensures that environment-specific overrides take precedence over file-based configuration.

### Registry Access

Once loaded, the URL is exposed through the server registry. The `getSearxngURL()` function in [`src/lib/config/serverRegistry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/serverRegistry.ts) (lines 14-15) provides a synchronous accessor that other modules use to retrieve the current endpoint:

```typescript
import { getSearxngURL } from '@/lib/config/serverRegistry';

const url = getSearxngURL();
console.log('Current SearXNG endpoint →', url);

```

### Search Implementation

The actual HTTP request logic resides in [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts) (lines 21-30). The `searchSearxng()` function dynamically constructs the request URL by appending query parameters to the configured base URL. This means all search traffic routes through your specified external instance automatically:

```typescript
import { searchSearxng } from '@/lib/searxng';

async function example() {
  const { results, suggestions } = await searchSearxng('latest AI research');
  console.log(results);
}

```

Because the URL is injected at runtime rather than hardcoded, you can switch between different SearxNG instances (local, staging, or public) simply by changing the configuration value.


## Validation and Testing

After configuring the external instance, verify the connection by checking the resolved URL and executing a test query. The system requires no additional headers or authentication tokens for standard SearxNG instances, though you should ensure your external instance allows CORS if accessing from browser contexts.

If the `searxngURL` value is empty or invalid, the `searchSearxng()` function will fail to construct a valid request URL, so always validate that `getSearxngURL()` returns a string starting with `http` before attempting searches.


## Summary

- **Vane delegates web search to SearxNG** through the configurable `search.searxngURL` key.
- **Set the `SEARXNG_API_URL` environment variable** for containerized deployments, or edit [`config.json`](https://github.com/ItzCrazyKns/Vane/blob/main/config.json) for local development.
- **The `getSearxngURL()` accessor** in [`src/lib/config/serverRegistry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/serverRegistry.ts) provides runtime access to the configured endpoint.
- **The `searchSearxng()` function** in [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts) automatically uses the external instance for all queries.
- **No code changes are required** to switch between SearxNG instances—only configuration updates.


## Frequently Asked Questions

### Can I use a public SearxNG instance instead of self-hosting?

Yes. You can point Vane to any publicly accessible SearxNG instance by setting the configuration value to the public URL (e.g., `https://searx.example.com`). However, public instances may have rate limits or privacy implications compared to self-hosted alternatives.

### What URL format should I use for the SearxNG endpoint?

Provide the **base URL** of the SearxNG instance without path suffixes. For example, use `https://search.my-domain.com` rather than `https://search.my-domain.com/search`. The `searchSearxng()` function in [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts) appends the necessary `/search` path and query parameters automatically.

### Does Vane support authentication headers for private SearxNG instances?

The current implementation in [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts) uses a standard JSON fetch without custom authentication headers. If your external instance requires API keys or tokens, you would need to modify the fetch configuration in that file to include the appropriate headers, as the base configuration only supports URL specification.

### Where is the SearxNG configuration documented in the Vane repository?

The search API documentation is located at [`docs/API/SEARCH.md`](https://github.com/ItzCrazyKns/Vane/blob/main/docs/API/SEARCH.md), which describes how the public interface interacts with the underlying SearxNG service. The implementation details referenced in this guide are found in [`src/lib/config/index.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/index.ts) (configuration loading), [`src/lib/config/serverRegistry.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/config/serverRegistry.ts) (registry access), and [`src/lib/searxng.ts`](https://github.com/ItzCrazyKns/Vane/blob/main/src/lib/searxng.ts) (request execution).