deep-research

Deep Research can be deployed using Docker. Note that the Docker image may lag behind the latest version by 1-2 days.

Run with a single command:

docker run -d --name deep-research -p 3333:3000 xiangfa/deep-research

Run with environment variables (e.g., password and Gemini key):

docker run -d --name deep-research \
   -p 3333:3000 \
   -e ACCESS_PASSWORD=your-password \
   -e GOOGLE_GENERATIVE_AI_API_KEY=AIzaSy... \
   xiangfa/deep-research

Deploy using Docker Compose: Create a docker-compose.yml file with the following content:

version: '3.9'
services:
   deep-research:
      image: xiangfa/deep-research
      container_name: deep-research
      environment:
         - ACCESS_PASSWORD=your-password
         - GOOGLE_GENERATIVE_AI_API_KEY=AIzaSy...
      ports:
         - 3333:3000

Then run:

docker compose -f docker-compose.yml build

The Deep Research API uses Server-Sent Events (SSE) over HTTP to stream real-time updates. To consume the API, establish a POST connection to the /api/sse endpoint and keep it open to receive a continuous stream of events. It is highly recommended to use the @microsoft/fetch-event-source library to handle the connection and event parsing.

import { fetchEventSource } from "@microsoft/fetch-event-source";

const ctrl = new AbortController();

fetchEventSource("/api/sse", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    // Authorization: "Bearer YOUR_ACCESS_PASSWORD",
  },
  body: JSON.stringify({
    query: "AI trends for this year",
    provider: "google",
    thinkingModel: "gemini-2.0-flash-thinking-exp",
    taskModel: "gemini-2.0-flash-exp",
    searchProvider: "model",
    language: "en-US",
    maxResult: 5,
    enableCitationImage: true,
    enableReferences: true,
    promptOverrides: {
      systemInstruction: "You are an expert researcher. Keep answers concise and evidence-driven.",
    },
  }),
  signal: ctrl.signal,
  onmessage(msg) {
    const msgData = JSON.parse(msg.data);
    // Handle events based on msg.event type
  },
  onclose() {
    console.log("Stream closed");
  },
});

When making a POST request to /api/sse, provide a JSON body following the Config interface.

Required Fields:

• query: The research topic string.
• provider: AI provider (e.g., google, openai, anthropic, deepseek, xai, mistral, azure, openrouter, openaicompatible, pollinations, ollama).
• thinkingModel: ID of the model used for thinking.
• taskModel: ID of the model used for tasks.
• searchProvider: Search provider (e.g., model, tavily, firecrawl, crw, exa, bocha, searxng).

Optional Fields:

• language: Response and search language (e.g., en-US).
• maxResult: Maximum number of search results (default: 5).
• enableCitationImage: Include content-related images in the report (default: true).
• enableReferences: Include citation links (default: true).
• promptOverrides: A partial object to override built-in prompt templates (e.g., systemInstruction, reportPlanPrompt, finalReportPrompt, etc.).