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

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

Using Environment Variables

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

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 file directly:

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

The configuration loader in 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 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. 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 (lines 14-15) provides a synchronous accessor that other modules use to retrieve the current endpoint:

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 (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:

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 for local development.
• The getSearxngURL() accessor in src/lib/config/serverRegistry.ts provides runtime access to the configured endpoint.
• The searchSearxng() function in 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 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 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, 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 (configuration loading), src/lib/config/serverRegistry.ts (registry access), and src/lib/searxng.ts (request execution).

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