---
title: Quick Start
description: This guide walks you through starting DeerFlow App on your local machine using the `make dev` workflow. Gateway, Frontend, and nginx start together and are accessible through a single URL.
---

import { Callout, Cards, Steps } from "nextra/components";

# Quick Start

<Callout type="info" emoji="⚡">
  Get DeerFlow App running locally in about 10 minutes. You need a machine with
  Python 3.12+, Node.js 22+, and at least one LLM API key.
</Callout>

This guide walks you through starting DeerFlow App on your local machine using the `make dev` workflow. Gateway, Frontend, and nginx start together and are accessible through a single URL.

## Prerequisites

Check that all required tools are installed:

```bash
make check
```

Required:

| Tool    | Minimum version    |
| ------- | ------------------ |
| Python  | 3.12               |
| uv      | latest             |
| Node.js | 22                 |
| pnpm    | 10                 |
| nginx   | any recent version |

On macOS, install with `brew install python uv node pnpm nginx`. On Linux, use your distribution's package manager.

## Steps

<Steps>

### Clone the repository

```bash
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
```

### Install dependencies

```bash
make install
```

This installs both backend Python dependencies (via `uv`) and frontend Node.js dependencies (via `pnpm`).

### Create your config file

```bash
cp config.example.yaml config.yaml
```

Then edit `config.yaml` to add at least one model. The minimum change is adding a model under the `models:` section:

```yaml
models:
  - name: gpt-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    supports_vision: true
```

Set the corresponding environment variable before starting:

```bash
export OPENAI_API_KEY=sk-...
```

See the [Application Configuration](/docs/application/configuration) page for examples with other model providers.

### Start all services

```bash
make dev
```

This starts:

- Gateway API and embedded agent runtime on port `8001`
- Frontend on port `3000`
- nginx reverse proxy on port `2026`

Open [http://localhost:2026](http://localhost:2026) in your browser.

### Stop all services

```bash
make stop
```

</Steps>

## What happens when you run `make dev`

- Existing service processes are stopped first (safe to run after an interrupted start).
- Each service is started in the background and writes logs to the `logs/` directory.
- nginx proxies all traffic through port `2026`, so you only need one URL.

Log files:

| Service   | Log file             |
| --------- | -------------------- |
| Gateway   | `logs/gateway.log`   |
| Frontend  | `logs/frontend.log`  |
| nginx     | `logs/nginx.log`     |

<Callout type="tip">
  If something is not working, check the log files first. Most startup errors
  (missing API keys, config parsing failures) appear in `logs/gateway.log`.
</Callout>

<Cards num={2}>
  <Cards.Card
    title="Deployment Guide"
    href="/docs/application/deployment-guide"
  />
  <Cards.Card title="Configuration" href="/docs/application/configuration" />
</Cards>
