Related Pages

Related topics: AI & Web Search Provider Configuration

Project Overview & Deployment Modes

Purpose and Scope

Deep Research Web UI is a browser-based visualization layer for the open-source deep-research agent. It wraps a recursive web-research loop — where an LLM generates follow-up questions, performs iterative web searches, and distills learnings — in a four-step user interface: research topic, model feedback, web browsing, and final report. Source: README.md.

The project distinguishes itself from the upstream CLI by emphasizing realtime feedback, search-flow visualization, and a flexible deployment model. Realtime feedback is achieved by streaming AI responses and reflecting them in the UI; search flow is rendered as a tree structure so users can inspect individual nodes (research goal, visited URLs, learnings) and retry failed ones. Source: i18n/en.json.

The core research engine itself is split into a small set of TypeScript modules re-exported through a single entry point. Source: lib/core/index.ts.

lib/core/
├── index.ts          // barrel re-export
├── deep-research.ts  // iterative search + final report
└── feedback.ts       // clarification question generator

Supported Providers

The application is intentionally provider-agnostic on both the LLM and the web-search axes. On the AI side, the README advertises OpenAI-compatible endpoints, SiliconFlow, InfiniAI, DeepSeek, OpenRouter, Ollama, and 302.AI. On the web-search side, it lists Tavily (1000 free credits/month), Firecrawl (cloud or self-hosted), fastCRW, and Google PSE. Source: README.md.

Compatibility is preserved by using plain prompt-based JSON extraction rather than newer features such as Structured Outputs. The project ships its own streaming JSON parser that tolerates partial / repaired parses so that weaker models do not break the pipeline. Source: shared/utils/json.ts.

The provider catalog has grown steadily through community-driven releases: Google PSE landed in v1.1.9, InfiniAI in v1.1.8, and 302.AI in v1.2.0. Source: release notes v1.1.9 / v1.1.8 / v1.2.0.

Deployment Modes

The project supports two distinct operational modes, switched at build/runtime via the NUXT_PUBLIC_SERVER_MODE flag. The choice has major implications for where API keys live and where inference requests are executed.

Client Mode (BYOK)

In Client Mode, configuration values — provider, API key, API base URL, model, context size, web-search settings — are entered through the settings panel and persisted in the browser. All requests to AI and search providers originate directly from the user's browser. The application is a static Nuxt 3 build that can be hosted on any static platform. Source: README.md.

This mode is appropriate when the operator wants maximum privacy and minimal operational footprint. The trade-off is that each user must paste their own keys on first use, which is what motivated the original feature request in issue #8 for environment-variable configuration.

Server Mode

Server Mode was introduced in release v1.2.0. Instead of sending requests directly to upstream providers, the browser forwards the heavy LLM calls to two internal Nuxt server routes:

• POST /api/feedback — streams clarification questions. Source: server/api/feedback.post.ts.
• POST /api/report — streams the final research report. Source: server/api/report.post.ts.

Both handlers read the operator's secrets from useRuntimeConfig() and respond with text/event-stream so the frontend can render tokens in real time.

Two TypeScript types in shared/types/config.ts formalize the split between operator-only secrets and values safe to expose to the browser:

export interface ServerRuntimeConfig {
  aiProvider: ConfigAiProvider
  aiModel: string
  aiApiKey: string          // server-only
  aiApiBase?: string
  ...
  webSearchApiKey: string   // server-only
  googlePseId?: string
}

export interface PublicRuntimeConfig {
  serverMode: boolean
  aiProvider: ConfigAiProvider
  aiModel: string
  // no API keys, no apiBase
}

Source: shared/types/config.ts.

flowchart LR
  subgraph Client["Client Mode (BYOK)"]
    U1[User Browser] -- "API key in localStorage" --> U1
    U1 -- "direct HTTPS" --> P1[AI Provider]
    U1 -- "direct HTTPS" --> S1[Search Provider]
  end
  subgraph Server["Server Mode"]
    U2[User Browser] -- "no secrets" --> N[Nuxt Server]
    N -- "useRuntimeConfig" --> N
    N -- "stream /api/feedback, /api/report" --> P2[AI Provider]
    N -- "API key from env" --> S2[Search Provider]
  end

Operating-Mode Selection

Server Mode is selected by setting NUXT_PUBLIC_SERVER_MODE and the rest of the operator configuration in a .env file (copied from .env.example), then running the published Docker image with --env-file. The static-hosting alternative remains EdgeOne Pages, where the project provides a one-click deploy button and pins Node 20.18.0. Source: README_zh.md, edgeone.json.

flowchart TD
  Start{Where do API keys live?}
  Start -- "User's browser" --> CM[Client Mode]
  Start -- "Server .env" --> SM[Server Mode]
  CM --> CM1["Static host (EdgeOne, Docker nginx)"]
  SM --> SM1["Nuxt server runtime (Docker)"]
  SM1 --> SM2["/api/feedback, /api/report"]

Common Pitfalls and Community Notes

• CORS errors in Client Mode: Some AI providers block cross-origin browser requests. The UI surfaces a localized hint: "The current API provider may not allow cross-origin requests. Please try a different service provider or contact the provider for support." Source: i18n/en.json.
• Azure OpenAI: Issue #70 reports that the URL builder does not yet support Azure's api-version query parameter, so Azure deployments may fail unless used through the OpenAI-compatible provider with a custom base URL.
• PWA / offline use: A long-standing request in issue #43 for PWA support remains open; the production build is not currently service-worker-enabled.
• Tavily quota: Single-account Tavily keys hit their 1k/month ceiling quickly during deep research. A rotation scheme was proposed in PR #77 and merged, so Server Mode deployments can supply a comma-separated key list.

See Also

• Provider & Configuration Reference — detailed env-var table and per-provider notes.
• Web Search & Browsing Pipeline — how the recursive search loop and Firecrawl/Tavily integrations work.
• Internationalization & History — translation workflow and the history feature shipped via issue #57.

Related Pages

Related topics: Project Overview & Deployment Modes, Research Engine, API Endpoints & Data Flow

AI & Web Search Provider Configuration

Overview

The deep-research-web-ui project decouples its research pipeline from any single AI or search vendor by exposing a pluggable provider configuration layer. Every research run accepts a ConfigAi and a ConfigWebSearch object, so the same UI can target OpenAI-compatible endpoints, regional Chinese providers, or self-hosted models, and can pair them with Tavily, Firecrawl, fastCRW, or Google PSE for web search. The configuration layer governs four things: (1) which provider to use, (2) authentication material, (3) endpoint and language, and (4) per-provider tuning (context size, search topic, rate limit).

Configuration is delivered to the application through one of two parallel paths — a Client Mode form that writes to the browser's localStorage (see app/stores/config.ts) and a Server Mode path that reads environment variables at boot via Nuxt's runtime config (shared/types/config.ts).

Configuration Modes

The project ships two mutually exclusive deployment modes, selected at build/run time:

• Client Mode — Every visitor enters their own AI and search credentials in the in-app settings dialog. Keys never leave the browser; the in-page ConfigManager.vue reads them on each research request. This mode is the only one supported by static exports such as pnpm generate or EdgeOne Pages (README.md).
• Server Mode — Added in v1.2.0 (release notes) in response to long-standing requests to set credentials via environment variables (see issue #8). The server reads NUXT_* variables into ServerRuntimeConfig, exposes the non-secret subset through PublicRuntimeConfig, and the UI displays a "Server Mode" banner with configNotice: "Current configuration is set by the server administrator..." (i18n/en.json).

flowchart LR
  A[Operator] -->|env vars| B[Nuxt Server<br/>ServerRuntimeConfig]
  B -->|public subset| C[PublicRuntimeConfig]
  C --> D[Browser UI<br/>Settings Dialog]
  E[End User] -->|types keys| D
  D -->|Client Mode| F[localStorage]
  D -->|Server Mode| C
  F --> G[Research Pipeline]
  C --> G
  G --> H[AI Provider]
  G --> I[Search Provider]

Supported AI Providers

The AI provider field is typed as ConfigAiProvider in shared/types/config.ts and is materialised into a model adapter by getLanguageModel(aiConfig) inside lib/core/deep-research.ts. The README and i18n files enumerate the supported values:

Per-provider settings live in the ai section of the i18n file and include apiKey, apiBase, model, and contextSize. The contextSize field controls how much of the running prompt is sent back to the model and is enforced in the research pipeline through trimPrompt(..., aiConfig.contextSize) (lib/core/deep-research.ts); the v1.1.5 release fixed a bug where this value was silently ignored (release v1.1.5).

The project deliberately uses "plain prompts" rather than OpenAI's Structured Outputs feature so that older or regional providers that have not yet shipped the newer API surface continue to work (README.md). Users on Azure OpenAI should note that base URL construction and api-version handling is not currently abstracted — see the open report in issue #70.

Supported Web Search Providers

The webSearch block of the configuration controls the SERP and scraping backend. Four providers are first-class:

• tavily — Default, ~1000 free credits / month. Supports advancedSearch (costs one extra credit) and searchTopic (one of 'general' | 'news' | 'finance'), both of which appear as typed fields on ServerRuntimeConfig and PublicRuntimeConfig (shared/types/config.ts). To address the single-account quota problem raised in issue #75, NUXT_WEB_SEARCH_API_KEY accepts a comma-separated list (key1,key2,key3) and the server rotates through them.
• firecrawl — Cloud or self-hosted. Self-hosted deployments are configured through NUXT_WEB_SEARCH_API_BASE (README_zh.md). Since v1.1.3, scraping is restricted to the Markdown format to keep downstream LLM prompts predictable (release v1.1.3). Note: issue #73 reports that the in-app concurrencyLimit setting is not yet honoured when Firecrawl runs in self-hosted mode.
• crw — A Firecrawl-compatible binary scraper that can be self-hosted or used as a cloud service. Identical configuration surface to Firecrawl (i18n/en.json).
• google-pse — Added in v1.1.9 (release v1.1.9). Requires both an API key (NUXT_WEB_SEARCH_API_KEY) and a Programmable Search Engine ID exposed as NUXT_PUBLIC_GOOGLE_PSE_ID. Multiple keys for rotation are supported the same way as Tavily.

The concurrencyLimit field, added in v1.1.1, bounds the number of in-flight search tasks to avoid rate limiting (release v1.1.1). searchLanguage overrides the language used in the search query while leaving the UI/report language untouched (i18n/en.json).

Server Mode Environment Variables

When NUXT_PUBLIC_SERVER_MODE=true is set, the server-side runtime config below takes precedence over any client-side settings. Operators normally inject these via the Docker docker run -e ... flags shown in the README.

(Sources: README_zh.md and the PublicRuntimeConfig interface in shared/types/config.ts.)

Common Failure Modes

• CORS rejection in Client Mode — When a provider does not advertise permissive CORS headers, browser calls fail with requestBlockedByCORS. The error message in i18n/en.json advises switching providers or moving to Server Mode.
• "Invalid JSON structure" — Older or smaller models occasionally return malformed structured output. The pipeline surfaces a translated invalidStructuredOutput error suggesting a larger model (i18n/en.json). v1.1.2 reduced the frequency of this error (release v1.1.2).
• Tavily quota exhaustion — Solved by configuring multiple keys in NUXT_WEB_SEARCH_API_KEY, added in response to issue #75.
• Self-hosted Firecrawl rate limiting — The client-side concurrencyLimit is not propagated to a self-hosted Firecrawl instance; see issue #73.

See Also

• README.md — feature list and deployment quickstart
• Release notes index — version history (v1.1.1 → v1.2.0) cited above
• dzhng/deep-research — the underlying research engine this UI wraps

Related Pages

Related topics: AI & Web Search Provider Configuration, Frontend Components, Search Visualization & History

Research Engine, API Endpoints & Data Flow

1. Purpose and Scope

The Research Engine is the heart of deep-research-web-ui. It wraps the original Node-based research loop from dzhng/deep-research into a set of TypeScript modules that can be invoked both inside the browser (Client Mode) and from Nitro server routes (Server Mode). Source: README.md.

The engine drives a four-stage user journey visible in the UI:

1. Research Topic — user submits a query, depth, and breadth.
2. Model Feedback — AI asks clarifying follow-up questions.
3. Web Browsing — recursive search/scrape loop produces a tree of learnings.
4. Research Report — final synthesis streamed back to the UI.

Source: i18n/en.json (sections researchTopic, modelFeedback, webBrowsing, researchReport).

In Server Mode (introduced in v1.2.0), the engine is exposed through HTTP endpoints under server/api/, allowing external clients to invoke the pipeline programmatically — a direction requested by the community in issue #79.

2. Core Library Layout (`lib/core/`)

lib/core/index.ts is a thin facade that re-exports the two engine entry points:

export * from './deep-research'
export * from './feedback'

Source: lib/core/index.ts.

• generateFeedback(...) in lib/core/feedback.ts — builds a clarifying-questions prompt and streams an array of questions back as deltas.
• deepResearch(...) in lib/core/deep-research.ts — orchestrates the iterative breadth/depth loop, producing a tree of search nodes whose leaves accumulate learnings.

Both functions accept an aiConfig: ConfigAi parameter so the engine is provider-agnostic. Prompts are factored into lib/prompt.ts and app/utils/prompt.ts, allowing browser and server bundles to share wording while keeping the server bundle trim.

3. Server API Endpoints

Server Mode is implemented with Nitro routes in server/api/. Each endpoint accepts a JSON body, attaches the server-side runtimeConfig, and responds with a Server-Sent Events stream so the UI can render partial results.

3.1 `POST /api/feedback`

The feedback endpoint validates query and language, then delegates to generateFeedback:

const serverConfig: ConfigAi = {
  provider: runtimeConfig.public.aiProvider as ConfigAi['provider'],
  apiKey: runtimeConfig.aiApiKey,
  apiBase: runtimeConfig.aiApiBase,
  model: runtimeConfig.public.aiModel,
  contextSize: runtimeConfig.public.aiContextSize,
}

It sets Content-Type: text/event-stream, Cache-Control: no-cache, and Connection: keep-alive, then iterates the async generator, encoding each chunk as data: <json>\n\n. Errors are serialized into a final SSE error event rather than thrown. Source: server/api/feedback.post.ts.

3.2 `POST /api/research`

The research endpoint follows the same pattern but invokes the longer-running deepResearch(...) generator. Because the loop runs many sequential search/scrape calls, this endpoint benefits from the webSearchConcurrencyLimit setting — which the community reports is not always honored by self-hosted Firecrawl, see issue #73.

4. Data Flow

The end-to-end flow in Server Mode looks like this:

sequenceDiagram
    participant Browser as Browser UI
    participant Nitro as Nitro API Route
    participant Engine as lib/core (Engine)
    participant AI as AI Provider
    participant Search as Web Search Provider

    Browser->>Nitro: POST /api/feedback (query, language)
    Nitro->>Engine: generateFeedback(aiConfig)
    Engine->>AI: stream chat completion
    AI-->>Engine: deltas (reasoning + text)
    Engine-->>Nitro: {type:'object'|'reasoning'} events
    Nitro-->>Browser: SSE stream

    Browser->>Nitro: POST /api/research (answers, depth, breadth)
    Nitro->>Engine: deepResearch(aiConfig, webSearchConfig)
    loop depth iterations
        Engine->>Search: search(query) × breadth
        Search-->>Engine: URLs + snippets
        Engine->>AI: extract learnings
        Engine-->>Nitro: node + learnings events
    end
    Engine->>AI: synthesize report
    Engine-->>Nitro: final report stream
    Nitro-->>Browser: SSE stream

The engine never blocks on a single full response — it yields events continuously. The UI consumes them to populate the search tree and report panel in real time, which is the feature advertised as "Realtime feedback" in README.md.

5. Streaming JSON Parsing

Because providers do not return strict Structured Outputs, the engine relies on parseStreamingJson in shared/utils/json.ts. It walks the AI SDK's fullStream, accumulates text-delta chunks, strips Markdown fences, and re-parses after every delta. It yields three event types:

Source: shared/utils/json.ts.

This mechanism explains the failure mode reported in issue #69 — when the report JSON is truncated or malformed, the final report collapses to a single model summary because the loop has no further context to expand.

6. Runtime Configuration Contract

The split between private and public runtime config is enforced by shared/types/config.ts:

• ServerRuntimeConfig carries secrets (aiApiKey, webSearchApiKey) and provider base URLs — only available server-side.
• PublicRuntimeConfig exposes only non-secret knobs (aiProvider, aiModel, aiContextSize, webSearchConcurrencyLimit, webSearchSearchLanguage, tavilyAdvancedSearch, tavilySearchTopic, googlePseId, serverMode) so the client can render the settings UI without leaking credentials.

Source: shared/types/config.ts.

This separation was the request behind issue #8 and is what enables the single-Docker-command deployment shown in README.md.

Static deployments (e.g. EdgeOne Pages via edgeone.json) build with pnpm generate:optimize and do not run Nitro routes, so Server Mode APIs are unavailable there — users must stay in Client Mode.

7. Common Failure Modes

• Retry does nothing (issue #71) — retry state is local to the failed node and may not re-enter the SSE stream after a transport error.
• Azure OpenAI base URL mis-construction (issue #70) — the engine concatenates apiBase naively, ignoring Azure's api-version query parameter.
• CORS rejection — surfaced by the requestBlockedByCORS toast; the engine cannot proxy AI calls in Client Mode. Source: i18n/en.json.

See Also

• Configuration & Server Mode
• Deep Research (upstream library)
• Community issues: #8 (env vars), #73 (Firecrawl rate limit), #79 (API support).

Related Pages

Related topics: Research Engine, API Endpoints & Data Flow

Error with Openai API: Error code: 500 - {'type': 'error', 'error': {'type': 'server_error', 'message': 'unknown error, 999 (1000)', 'http_code': '500'}, 'request_id': '068d5b03c22107371180a77312fdee59'}

Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.

Doramagic Pitfall Log

Found 14 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/8

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/AnotiaWang/deep-research-web-ui

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/43

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/AnotiaWang/deep-research-web-ui

5. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/AnotiaWang/deep-research-web-ui

6. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/71

7. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/70

8. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/AnotiaWang/deep-research-web-ui

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/AnotiaWang/deep-research-web-ui

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/AnotiaWang/deep-research-web-ui

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/73

12. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/AnotiaWang/deep-research-web-ui/issues/79

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using deep-research-web-ui with real data or production workflows.

• [[Feature] PWA functionality](https://github.com/AnotiaWang/deep-research-web-ui/issues/43) - github / github_issue
• Community source 2 - github / github_issue
• Community source 3 - github / github_issue
• Community source 4 - github / github_issue
• Community source 5 - github / github_issue
• [[Bug] firecrawl rate limit is not wokring](https://github.com/AnotiaWang/deep-research-web-ui/issues/73) - github / github_issue
• Community source 7 - github / github_issue
• Community source 8 - github / github_issue
• Community source 9 - github / github_issue
• 1.2.0 - github / github_release
• 1.1.9 - github / github_release
• 1.1.8 - github / github_release