Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JasonHonKL/spy-search/llms.txt

Use this file to discover all available pages before exploring further.

Spy Search is an open-source, self-hosted agentic search framework that goes beyond simple keyword retrieval. Instead of returning a list of blue links, Spy Search dispatches a coordinated pipeline of AI agents that plan, search, retrieve, and synthesize live web content into coherent, structured answers — including long-form research reports of around 2,000 words. Born as a cost-effective alternative to commercial tools like Perplexity and Manus (which can cost upwards of $200/month), Spy Search is designed for developers who want full control over their stack, the freedom to run entirely free local models via Ollama, and the ability to self-host without sending queries to a third-party service.

​
How It Works: The Agent Pipeline

Spy Search orchestrates three specialized agents in sequence:
1

Planner

The Planner agent receives the user’s query and decomposes it into a structured research plan — deciding what sub-questions to answer and what search strategies to use.
2

Searcher / RAG

The Searcher agent executes live web searches using DuckDuckGo, scrapes and crawls the resulting pages with Playwright (via Crawl4AI), and indexes the retrieved content into a local ChromaDB vector store for Retrieval-Augmented Generation (RAG).
3

Reporter

The Reporter agent reads the indexed content and synthesizes a structured, ~2,000-word report grounded in the freshly retrieved web sources, citing real information rather than relying solely on model weights.
This architecture means Spy Search always works with up-to-date information from the live web — not stale training data.

​
Key Differentiators

FeatureSpy SearchPerplexity / Manus
Open-source✅ MIT licensed❌ Proprietary
Self-hosted✅ Runs on your machine❌ Cloud-only
Free local models✅ Ollama support❌ API costs only
Long-form reports✅ ~2,000 wordsVaries
Monthly cost$0 (with Ollama)Up to $200+

​
Supported LLM Providers

Spy Search’s config.json accepts any of the following providers out of the box:
  • OpenAI — GPT-4o, GPT-4.1, and any OpenAI-compatible endpoint (including OpenRouter)
  • DeepSeek — DeepSeek-V3, DeepSeek-R1
  • Gemini — Google Gemini models via the google-genai SDK
  • Grok (xAI) — xAI’s Grok models via XAI_API_KEY
  • Anthropic — Claude 3.x and Claude Sonnet series
  • Ollama — Any locally running model (Qwen3, Llama 3, Mistral, etc.) — completely free, no API key required
Switching providers is a one-line change in config.json. See the Quickstart and Docker Setup guides for full configuration examples.

​
Current Version: v0.3

Released: 2025-06-10 v0.3 is the latest stable release of Spy Search. The team is actively working toward v1.0, which will address current search-speed limitations. The core report generation pipeline is stable and production-ready for personal and team use.

​
Get Started

Quickstart

Install Spy Search locally with Python in under 5 minutes.

Docker Setup

Deploy the full stack with a single docker-compose up command.
Join the Spy Search community on Discord to ask questions, share feedback, and follow development: discord.gg/rrsMgBdJJt

Build docs developers (and LLMs) love

Get started for freeTalk to us