🛸 BeamXNG

The fastest way to give your local LLM web search superpowers

Stop running heavy SearXNG containers. BeamXNG is a zero-dependency Rust gateway that beams your queries to public SearXNG instances from searx.space with intelligent load balancing and automatic failover.

Perfect for: Ollama · LM Studio · Open WebUI · MCP Servers · Any LLM Stack

✨ Features

• 🛸 Smart routing across 100+ public SearXNG instances
• ⚡ Ultra-lightweight: 5.1MB binary, ~7.4MB idle RAM (measured — see BENCHMARKS.md)
• 🔄 Auto-failover with health checks and retry logic
• 🎯 Multiple load balancing strategies: Round-robin, latency-based, random
• 🔌 Drop-in replacement for localhost:8080 SearXNG
• 🦀 Blazingly fast - built with Rust and async I/O
• 📊 Health monitoring - real-time instance status
• 🌐 Zero configuration - works out of the box

🚀 Quick Start

Download Binary (Recommended)

Grab the archive for your platform from the latest release, then:

# Linux/macOS example (adjust filename to the asset you downloaded)
tar -xzf beamxng-x86_64-unknown-linux-gnu.tar.gz
chmod +x beamxng
./beamxng

Prebuilt archives are published for Linux (x86_64), macOS (x86_64, Apple Silicon) and Windows (x86_64) on every tagged release.

Build from Source

# Clone repository
git clone https://github.com/xonoxitron/beamxng.git
cd beamxng

# Build release binary
cargo build --release

# Run
./target/release/beamxng

BeamXNG will start on http://127.0.0.1:8080 by default.

📡 Usage

Basic Search

curl "http://localhost:8080/search?q=rust+programming&format=json"

With Parameters

curl "http://localhost:8080/search?q=machine+learning&format=json&categories=science&engines=google,duckduckgo&language=en"

Health Check

curl "http://localhost:8080/health"

View Available Instances

curl "http://localhost:8080/instances"

🔧 Configuration

Configure via environment variables:

# Listen address and port
export BEAMXNG_ADDR="0.0.0.0"
export BEAMXNG_PORT=8080

# Load balancing strategy: roundrobin, latency, random
export BEAMXNG_STRATEGY="latency"

# Run
./beamxng

🤖 Integration Examples

Ollama with Open WebUI

1. Start BeamXNG:

./beamxng

2. Configure Open WebUI to use http://localhost:8080 as SearXNG URL

3. Enable web search in your chat

MCP Server Integration

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}

LM Studio

1. Start BeamXNG
2. Configure web search tool with URL: http://localhost:8080
3. Enable web search in your model

Python Integration

import requests

def search(query: str) -> dict:
    response = requests.get(
        "http://localhost:8080/search",
        params={"q": query, "format": "json"}
    )
    return response.json()

results = search("artificial intelligence news")

🎯 Why BeamXNG?

Before (Self-hosted SearXNG)	After (BeamXNG)
❌ Docker + Redis + uwsgi	✅ Single binary
❌ ~200MB memory	✅ ~7-9MB memory
❌ Manual configuration	✅ Zero config
❌ Single point of failure	✅ Auto-failover
❌ Maintain instance updates	✅ Always up-to-date

📊 Performance

• /search latency: 200-500ms typical (dominated by the selected public instance's response time — not measured in a fixed lab setup, see BENCHMARKS.md)
• /health latency: ~2.4ms mean, ~20,700 req/s, 0 failures under load (measured)
• Memory usage: ~7.4MB idle, ~8.6MB under load (measured)
• Binary size: 5.1MB (release build, measured)
• Startup time: ~140ms to ready (measured)

See BENCHMARKS.md for detailed performance analysis and comparison.

Quick Benchmark

cd benchmarks
./quick-bench.sh

🛠️ Advanced Usage

Custom Instance Selection Strategy

BeamXNG supports three load balancing strategies:

1. Latency-based (default): Selects fastest responding instance
2. Round-robin: Cycles through instances sequentially
3. Random: Randomly selects from healthy instances

export BEAMXNG_STRATEGY="roundrobin"
./beamxng

Health Monitoring

BeamXNG automatically:

• Fetches instance list from searx.space every 5 minutes
• Health checks all instances every 60 seconds
• Marks instances unhealthy after 3 consecutive failures
• Automatically recovers instances when they come back online

📝 API Reference

GET /search

Search endpoint compatible with SearXNG API.

Query Parameters:

• q (required): Search query
• format: Response format (default: json)
• categories: Search categories (e.g., general,science)
• engines: Search engines (e.g., google,duckduckgo)
• language: Language code (e.g., en)
• pageno: Page number
• time_range: Time filter (day, month, year)

GET /health

Returns gateway health status and instance statistics.

Response:

{
  "status": "healthy",
  "healthy_instances": 87,
  "total_instances": 102
}

GET /instances

Lists all healthy instances with response times.

Response:

[
  {
    "url": "https://search.example.com",
    "response_time_ms": 245
  }
]

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• SearXNG - Privacy-respecting metasearch engine
• searx.space - Public instance directory

🔗 Links

• Report Issues
• SearXNG Documentation
• Public Instances

---

Made with 🦀 and 🛸 by the BeamXNG community