dzhng/deep-research installation guide

Install Open Deep Research on macOS Tahoe (Apple silicon)

What this repository is

Open Deep Research is a small TypeScript/Node.js command-line research assistant. It asks for a topic, breadth, and depth; generates search queries; processes web results; follows promising directions recursively; and writes a Markdown report. Its documented default services are Firecrawl for search/content extraction and OpenAI for the `o3-mini` model.

**Claude Code classification: unclassified.** The supplied repository evidence does not document a Claude Code plugin, skill, hook, MCP server, command, or other Claude Code integration. Install and run it as its own Node.js terminal application, not inside Claude Code. You may keep using Claude Code separately, but no connection between the two is established here.

This guide uses the repository’s documented Node.js installation path. The supplied files do not identify any Intel-only dependency, but they also do not provide an explicit Apple-silicon compatibility statement. The package requires **Node.js 22.x**.

Before you begin

You need:

• A Mac with macOS Tahoe on Apple silicon.
• A **Node.js 22.x** environment. The package’s `engines` field specifies `22.x`.
• Git, because the repository’s setup begins by cloning it.
• A Firecrawl API key.
• An OpenAI API key for the default model setup.
• Terminal access and an internet connection.

The repository does not provide a supported command for installing Node.js or Git. To avoid inventing installation commands, obtain Node.js 22 from the first-party Node.js website if it is not already installed. On macOS, Git may prompt you to install Apple’s developer command-line components when first needed; follow the operating-system prompt rather than using an undocumented command from this guide.

API usage may be subject to provider pricing, quotas, and rate limits. Treat both keys as secrets. Do not paste them into chat, commit them to Git, or include them in a report.

1. Open Terminal

Open **Terminal** from Applications → Utilities, or find it with Spotlight. Commands in this guide should be pasted into Terminal one block at a time.

The remaining steps assume Node.js 22.x and Git are already available. The repository does not document a separate macOS app or graphical installer.

2. Clone the public repository

Choose the folder in which you want the project to live. Then clone the HTTPS URL supplied by the repository metadata, enter the new folder, and install its declared dependencies:

git clone https://github.com/dzhng/deep-research.git
cd deep-research
npm install

`npm install` reads `package.json` and installs the project’s dependencies. These include the TypeScript runner, AI SDK integrations, Firecrawl client, Express, and supporting libraries. Let the command finish before continuing.

The repository does not document use of `sudo` for installation. Do not add it. It also does not provide a working test suite: its `test` script explicitly prints “Error: no test specified” and exits with an error, so there is no documented test command to run as an installation check.

3. Obtain the required API keys

For the standard setup, create accounts with the two providers named by the README:

1. **Firecrawl:** obtain a Firecrawl API key for web search and content extraction.
2. **OpenAI:** obtain an OpenAI API key for the default `o3-mini` model configuration.

Keep the Terminal window open in the `deep-research` directory. You now need to create a file named exactly `.env.local` in that directory. The repository does not supply a documented Terminal command or editor command for creating this file, so use a macOS text editor or another editor you already trust.

Make sure the editor saves plain text and does not silently append `.txt` to the filename. The full filename must be `.env.local`, including the initial period.

4. Configure `.env.local`

Paste the following repository-provided configuration into `.env.local`, replacing both placeholder values with your real keys:

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"

For the normal hosted setup, leave `FIRECRAWL_BASE_URL` commented out. Save the file in the repository’s top-level folder—the same folder containing `package.json`.

The project’s start script is `tsx --env-file=.env.local src/run.ts`, so the exact filename and location matter. If the application later reports missing credentials, first check that the file is not named `.env.local.txt`, that the variable names match exactly, and that the placeholder text was replaced.

Optional model configurations

Skip this subsection for the simplest installation.

The README says that setting a Fireworks key makes the program switch from `o3-mini` to R1 automatically. The documented entry is:

FIREWORKS_KEY="api_key"

Add that line to `.env.local` only if you intend to use Fireworks and have a valid key.

For other OpenAI-compatible services, the documented optional variables are:

OPENAI_ENDPOINT="custom_endpoint"
CUSTOM_MODEL="custom_model"

Replace the placeholders with values supplied by your chosen service. The README separately says that a local LLM setup should comment out `OPENAI_KEY` and use `OPENAI_ENDPOINT` plus `OPENAI_MODEL`, with the endpoint pointing to the local server—for example, `http://localhost:1234/v1`. Because those two documented sections use different model variable names (`CUSTOM_MODEL` versus `OPENAI_MODEL`), do not mix them casually. The hosted Firecrawl-and-OpenAI setup above is the least ambiguous path.

A local model does not remove the documented Firecrawl requirement for web search and extraction. The repository also does not provide installation instructions for a local model server or self-hosted Firecrawl, so those services must already be operating if you choose those paths.

5. Start the research assistant

From Terminal, while still inside the cloned `deep-research` folder, run the repository’s documented start command:

npm start

The application will prompt you interactively for:

1. Your research query.
2. Research breadth—recommended range **3–10**, default **4**.
3. Research depth—recommended range **1–5**, default **2**.
4. Answers to follow-up questions that refine the research direction.

For a first run, use the defaults or modest values. Breadth controls how widely the assistant searches; depth controls how many recursive rounds it performs. Larger values can cause more searches, model calls, elapsed time, and provider usage.

The assistant then generates search queries, processes results, explores follow-up directions, and creates a Markdown report. According to the README, the result is saved in the working directory as either `report.md` or `answer.md`, depending on the selected mode. Open that file with any plain-text or Markdown-capable application.

A generated report is not automatically authoritative. Check important claims against the listed sources, especially for medical, legal, financial, security, or other consequential decisions.

6. Rate-limit and concurrency adjustment

Firecrawl’s free tier may produce rate-limit errors. The README says you can reduce the concurrency limit to `1`, which will be slower. Paid or local Firecrawl users may increase it. Add the following documented environment-variable form to `.env.local` when needed:

CONCURRENCY_LIMIT="1"

Save the file, stop the current run if necessary, and start the assistant again with:

npm start

Do not raise concurrency merely because the Mac has a fast Apple-silicon processor: the relevant constraint may be the external service’s quota rather than local CPU performance.

Troubleshooting checklist

• **Node version rejection:** confirm that the installed major version is Node.js 22; the package specifies `22.x`.
• **Missing Firecrawl or OpenAI key:** verify `.env.local` is in the repository root and contains the exact documented variable names.
• **Authentication failure:** replace expired, revoked, malformed, or placeholder keys with valid provider-issued values.
• **Firecrawl rate-limit messages:** add `CONCURRENCY_LIMIT="1"` to `.env.local` and retry.
• **No output file yet:** allow the interactive process to complete. Greater breadth and depth require more work.
• **`npm start` cannot find the project:** return to the cloned `deep-research` folder—the one containing `package.json`—before running it.
• **Local-model problems:** verify your local server independently. This repository does not document how to install or operate that server.

Updating and removal

The supplied first-party files do not document update or uninstall commands. Therefore, this guide does not recommend any. If you later want a newer version or want to remove the project, consult the repository’s current first-party documentation before acting. Revoke unused API keys through Firecrawl, OpenAI, or Fireworks as appropriate; deleting a local project folder alone does not revoke provider credentials.

You now have the documented Node.js installation configured and can launch it whenever you are in the repository folder by running `npm start`.