Skip to content
Get packs

Guide · Open source

How to use deep-research: setup, run and read the report

Updated · written with AI from the project's own documentation and checked against our catalogue data

deep-research is an open-source, command-line research assistant written in TypeScript. You give it a topic, it runs repeated rounds of web search and scraping with a large language model, and it writes a markdown report with findings and sources. This guide is for developers, students and anyone comfortable with Node.js who wants to run it, and by the end you will know what you need, how to configure it and how to read its output.

Open Deep Researchdzhng/deep-research · ★ 19.9k · MIT

Quick start

  1. 1Check prerequisites. Make sure Node.js is installed and you have a Firecrawl key and an OpenAI key, or a local OpenAI-compatible LLM server.
  2. 2Clone the repository. Download the dzhng/deep-research source code to your machine and open its folder.
  3. 3Install dependencies. Run npm install in the project folder.
  4. 4Create .env.local. Add FIRECRAWL_KEY and OPENAI_KEY, or the local endpoint and model variables.
  5. 5Start the assistant. Run npm start, then enter your query, breadth and depth values.
  6. 6Open the report. Find report.md or answer.md in your working directory and check the cited sources.

What you need before you install deep-research

The project needs a Node.js environment, a Firecrawl API key for web search and content extraction, and either an OpenAI API key or a local OpenAI-compatible LLM server. The README describes the OpenAI option as using the o3 mini model.

Because both Firecrawl and OpenAI are paid services, budget for API usage before you start. The README does not list prices, so check each provider's own pricing.

  • Node.js
  • A Firecrawl API key (or a self-hosted Firecrawl)
  • An OpenAI API key, or a local LLM server that exposes an OpenAI-compatible endpoint

Install deep-research from source on Node.js

The README uses a clone-and-build workflow. Clone the repository, change into its folder, then install its dependencies with npm.

Next, create a file named .env.local in the project folder and add your keys. The README shows FIRECRAWL_KEY and OPENAI_KEY as the required variables, with FIRECRAWL_BASE_URL available if you run a self-hosted Firecrawl.

npm install # .env.local FIRECRAWL_KEY="your_firecrawl_key" # If you want to use your self-hosted Firecrawl, add the following below: # FIRECRAWL_BASE_URL="http://localhost:3002" OPENAI_KEY="your_openai_key"

Run your first research session with npm start

Start the assistant with npm start. It prompts you for a research query, then asks for a breadth value (the README recommends 3 to 10, default 4) and a depth value (recommended 1 to 5, default 2). It may also ask follow-up questions to refine the direction of the research.

While it runs, the system generates and executes search queries, processes the results, and recursively explores deeper when depth is above zero. When it finishes, it saves the report as report.md or answer.md in your working directory, depending on the modes you selected.

  • Breadth controls how wide each round searches.
  • Depth controls how many rounds of follow-up exploration happen.
  • Higher values usually mean longer runs and more API calls.
npm start

Use a local LLM instead of OpenAI

To use a local model, comment out OPENAI_KEY in .env.local and uncomment OPENAI_ENDPOINT and OPENAI_MODEL. Set the endpoint to the address of your local server and the model to the name of the model loaded there.

The README gives http://localhost:1234/v1 as an example endpoint. Other OpenAI-compatible APIs, such as OpenRouter or Gemini, can be used through the custom endpoint and model variables.

# .env.local # OPENAI_KEY="your_openai_key" OPENAI_ENDPOINT="http://localhost:1234/v1" OPENAI_MODEL="your_loaded_model_name"

Tune speed and rate limits with concurrency settings

The project runs searches and result processing in parallel. If you have a paid or self-hosted Firecrawl, you can raise the concurrency limit by setting the CONCURRENCY_LIMIT environment variable so the run finishes faster.

On a free Firecrawl plan you may hit rate limit errors. The README suggests reducing the limit to 1, which works but runs much more slowly.

CONCURRENCY_LIMIT=1

Read the markdown report and check the sources yourself

The report is the main output. The README says it includes findings and all sources and references, organised in a readable format.

The README does not describe any verification of sources or claims. Open the cited sources and confirm important facts before you rely on the report.

  • Look at the sources listed for each claim.
  • Verify figures, quotes and dates against the original pages.
  • Treat the report as a starting draft, not a finished answer.

What people use it for

  • Learning how a deep research agent chains search, scraping and LLM calls by reading a short TypeScript codebase.
  • Extending the agent with your own search provider or report format as a starting point.
  • Generating a first-draft markdown overview of a topic, with sources, for later checking.
  • Experimenting with a local LLM through an OpenAI-compatible endpoint.

Frequently asked questions

Is deep-research free to use?

The code is released under the MIT License, which permits use and modification. The README requires Firecrawl and OpenAI API keys (or a local LLM server), and those services may charge for usage, so check their pricing.

What do I need to run deep-research?

The README lists Node.js, a Firecrawl API key, and either an OpenAI API key or a local OpenAI-compatible LLM server. You also need to clone the repository and run npm install.

Can I use a local LLM instead of OpenAI?

Yes. Comment out OPENAI_KEY in .env.local and set OPENAI_ENDPOINT to your local server address and OPENAI_MODEL to the loaded model's name. The README gives http://localhost:1234/v1 as an example.

Why does deep-research hit rate limit errors?

The README notes that free Firecrawl plans can cause rate limit errors. You can set CONCURRENCY_LIMIT to 1 to reduce parallel requests, which is slower but more reliable.

Where is the research report saved?

The final report is saved as report.md or answer.md in your working directory, depending on which modes you selected when you ran it.

How does deep-research compare to gpt-researcher or STORM?

The README describes deep-research as a deliberately simple implementation under 500 lines of code, meant to be read and extended. It does not compare itself to gpt-researcher or STORM, so review each project's documentation to compare features.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

deep-research suits developers and students who want a short, readable example of a deep research agent and already have Firecrawl and OpenAI keys or a local LLM. If you want a polished app with a graphical interface, or guaranteed-accurate research without checking sources, pick a different tool.

Install options & downloads