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.

Docker Compose is the recommended way to deploy Spy Search for most users. It bundles the FastAPI backend and React frontend into a single orchestrated stack, handles all Python and Node.js dependencies inside the container, and eliminates the need to manage virtual environments or install Playwright manually on your host machine.

​
Prerequisites

  • Docker Desktop (includes Docker Compose) — download from docker.com
    • If you are on Linux and installed Docker Engine without Docker Desktop, install the Compose plugin separately: 
      sudo apt-get install docker-compose-plugin
# verify
docker compose version
  • An LLM API key — for OpenAI, DeepSeek, Gemini, Grok (xAI), or Anthropic; or Ollama running locally for a fully free setup

​
Deployment Steps

1

Clone the repository

git clone https://github.com/JasonHonKL/spy-search.git
cd spy-search
2

Copy and configure config.json

cp config.example.json config.json
Edit config.json to match your chosen LLM provider. Select the tab below for your setup:
The default example routes through OpenRouter using the OpenAI-compatible API, which lets you access hundreds of models (including Llama, Mistral, and GPT-4o) with a single API key:
{
  "provider": "openai",
  "model": "meta-llama/llama-3.3-70b-instruct",
  "agents": ["reporter"],
  "db": "./local_files/test",
  "base_url": "https://openrouter.ai/api/v1",
  "language": "en"
}
To use the native OpenAI API instead, remove the base_url field (or set it to "https://api.openai.com/v1") and set "model" to an OpenAI model such as "gpt-4o".
Config FieldDescription
providerLLM provider: openai, deepseek, gemini, xai, anthropic, or ollama
modelModel identifier as expected by the provider
agentsActive agent roles — ["reporter"] enables the full pipeline
dbPath for the local ChromaDB vector store (resolved inside the container)
base_urlProvider API base URL — must be http://host.docker.internal:11434 for Ollama inside Docker
languageOutput language code: "en", "zh", "ja", etc.
3

Set your API key

Create a .env file in the project root with your provider’s API key:
OPENAI_API_KEY=sk-...
If you are using Ollama, you can create an empty .env file or skip this step entirely — no key is needed.
4

Build and start the stack

Run the following from the project root:
docker-compose up --build
The --build flag ensures Docker rebuilds the images with the latest code and dependencies. On first run this will take a few minutes while layers are downloaded and compiled.To run the stack in the background (detached mode):
docker-compose up -d --build
Check that the container is running:
docker-compose ps
5

Access the application

Once the stack is up, both ports are immediately available:
ServiceURL
Backend APIhttp://localhost:8000
Interactive API Docshttp://localhost:8000/docs
React Frontendhttp://localhost:8080
Open http://localhost:8080 in your browser to start using the search UI, or call the API directly:
curl -X POST http://localhost:8000/quick/"what+is+quantum+computing" \
  -F 'messages=[{"role":"user","content":"what is quantum computing"}]'

​
Port Reference

PortServiceDescription
8000Backend APIFastAPI application served by Uvicorn
8080React FrontendVite-built React UI

​
Configuration Hot-Reload

config.json is volume-mounted into the container, which means any changes you make to the file on your host are immediately reflected inside the running container — no restart is required. This lets you switch models or providers on the fly during development.
Ollama users: The base_url in your config.json must be set to http://host.docker.internal:11434 when running inside Docker. Using http://localhost:11434 will not work because localhost inside the container refers to the container itself, not your host machine. host.docker.internal is the correct DNS name that Docker provides for reaching services on the host from within a container.

​
Stopping the Stack

To stop the running container: 
docker-compose down
Running docker-compose down removes the container and its internal filesystem, including any ChromaDB search data stored at ./local_files/test inside the container. To persist indexed data across restarts, add a named volume for ./local_files in your docker-compose.yml before running for the first time.

​
Next Steps

Introduction

Understand the Planner → Searcher → Reporter agent pipeline.

Quickstart

Prefer a local Python install? Follow the 5-minute quickstart guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us