> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/bytedance/deer-flow/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to DeerFlow

> Learn how to contribute to DeerFlow with development setup, workflow guidelines, and pull request process

Thank you for your interest in contributing to DeerFlow! This guide will help you set up your development environment and understand our development workflow.

## Development Environment Setup

We offer two development environments. **Docker is recommended** for the most consistent and hassle-free experience.

### Option 1: Docker Development (Recommended)

Docker provides a consistent, isolated environment with all dependencies pre-configured. No need to install Node.js, Python, or nginx on your local machine.

#### Prerequisites

* Docker Desktop or Docker Engine
* pnpm (for caching optimization)

#### Setup Steps

1. **Configure the application**:
   ```bash theme={null}
   # Copy example configuration
   cp config.example.yaml config.yaml

   # Set your API keys
   export OPENAI_API_KEY="your-key-here"
   # or edit config.yaml directly
   ```

2. **Initialize Docker environment** (first time only):
   ```bash theme={null}
   make docker-init
   ```
   This will:
   * Build Docker images
   * Install frontend dependencies (pnpm)
   * Install backend dependencies (uv)
   * Share pnpm cache with host for faster builds

3. **Start development services**:
   ```bash theme={null}
   make docker-start
   ```
   All services will start with hot-reload enabled:
   * Frontend changes are automatically reloaded
   * Backend changes trigger automatic restart
   * LangGraph server supports hot-reload

4. **Access the application**:
   * Web Interface: [http://localhost:2026](http://localhost:2026)
   * API Gateway: [http://localhost:2026/api/](http://localhost:2026/api/)\*
   * LangGraph: [http://localhost:2026/api/langgraph/](http://localhost:2026/api/langgraph/)\*

#### Docker Commands

```bash theme={null}
# Build the custom k3s image (with pre-cached sandbox image)
make docker-init

# Start Docker services (mode-aware, localhost:2026)
make docker-start

# Stop Docker development services
make docker-stop

# View Docker development logs
make docker-logs

# View Docker frontend logs
make docker-logs-frontend

# View Docker gateway logs
make docker-logs-gateway
```

#### Docker Architecture

```
Host Machine
  ↓
Docker Compose (deer-flow-dev)
  ├→ nginx (port 2026) ← Reverse proxy
  ├→ web (port 3000) ← Frontend with hot-reload
  ├→ api (port 8001) ← Gateway API with hot-reload
   ├→ langgraph (port 2024) ← LangGraph server with hot-reload
   └→ provisioner (optional, port 8002) ← Started only in provisioner/K8s sandbox mode
```

**Benefits of Docker Development**:

* ✅ Consistent environment across different machines
* ✅ No need to install Node.js, Python, or nginx locally
* ✅ Isolated dependencies and services
* ✅ Easy cleanup and reset
* ✅ Hot-reload for all services
* ✅ Production-like environment

### Option 2: Local Development

If you prefer to run services directly on your machine:

#### Prerequisites

Check that you have all required tools installed:

```bash theme={null}
make check
```

Required tools:

* Node.js 22+
* pnpm
* uv (Python package manager)
* nginx

#### Setup Steps

1. **Configure the application** (same as Docker setup above)

2. **Install dependencies**:
   ```bash theme={null}
   make install
   ```

3. **Run development server** (starts all services with nginx):
   ```bash theme={null}
   make dev
   ```

4. **Access the application**:
   * Web Interface: [http://localhost:2026](http://localhost:2026)
   * All API requests are automatically proxied through nginx

#### Manual Service Control

If you need to start services individually:

1. **Start backend services**:
   ```bash theme={null}
   # Terminal 1: Start LangGraph Server (port 2024)
   cd backend
   make dev

   # Terminal 2: Start Gateway API (port 8001)
   cd backend
   make gateway

   # Terminal 3: Start Frontend (port 3000)
   cd frontend
   pnpm dev
   ```

2. **Start nginx**:
   ```bash theme={null}
   make nginx
   # or directly: nginx -c $(pwd)/docker/nginx/nginx.local.conf -g 'daemon off;'
   ```

3. **Access the application**:
   * Web Interface: [http://localhost:2026](http://localhost:2026)

#### Nginx Configuration

The nginx configuration provides:

* Unified entry point on port 2026
* Routes `/api/langgraph/*` to LangGraph Server (2024)
* Routes other `/api/*` endpoints to Gateway API (8001)
* Routes non-API requests to Frontend (3000)
* Centralized CORS handling
* SSE/streaming support for real-time agent responses
* Optimized timeouts for long-running operations

## Project Structure

```
deer-flow/
├── config.example.yaml      # Configuration template
├── extensions_config.example.json  # MCP and Skills configuration template
├── Makefile                 # Build and development commands
├── scripts/
│   └── docker.sh           # Docker management script
├── docker/
│   ├── docker-compose-dev.yaml  # Docker Compose configuration
│   └── nginx/
│       ├── nginx.conf      # Nginx config for Docker
│       └── nginx.local.conf # Nginx config for local dev
├── backend/                 # Backend application
│   ├── src/
│   │   ├── gateway/        # Gateway API (port 8001)
│   │   ├── agents/         # LangGraph agents (port 2024)
│   │   ├── mcp/            # Model Context Protocol integration
│   │   ├── skills/         # Skills system
│   │   └── sandbox/        # Sandbox execution
│   ├── docs/               # Backend documentation
│   └── Makefile            # Backend commands
├── frontend/               # Frontend application
│   └── Makefile            # Frontend commands
└── skills/                 # Agent skills
    ├── public/             # Public skills
    └── custom/             # Custom skills
```

## Architecture

```
Browser
  ↓
Nginx (port 2026) ← Unified entry point
  ├→ Frontend (port 3000) ← / (non-API requests)
  ├→ Gateway API (port 8001) ← /api/models, /api/mcp, /api/skills, /api/threads/*/artifacts
  └→ LangGraph Server (port 2024) ← /api/langgraph/* (agent interactions)
```

## Development Workflow

### 1. Create a Feature Branch

```bash theme={null}
git checkout -b feature/your-feature-name
```

### 2. Make Your Changes

With hot-reload enabled in both Docker and local development, your changes will be reflected immediately:

* Frontend changes reload automatically
* Backend changes trigger service restarts
* No need to manually restart services during development

### 3. Test Your Changes

Thoroughly test your changes before committing. See the [Testing Guide](/advanced/testing) for details on running tests.

```bash theme={null}
# Backend tests
cd backend
make test

# Frontend tests
cd frontend
pnpm test
```

### 4. Commit Your Changes

Follow conventional commit message format:

```bash theme={null}
git add .
git commit -m "feat: description of your changes"
```

Commit message prefixes:

* `feat:` - New feature
* `fix:` - Bug fix
* `docs:` - Documentation changes
* `refactor:` - Code refactoring
* `test:` - Adding or updating tests
* `chore:` - Maintenance tasks

### 5. Push and Create a Pull Request

```bash theme={null}
git push origin feature/your-feature-name
```

Then create a pull request on GitHub with:

* Clear description of the changes
* Reference to any related issues
* Screenshots or demos for UI changes
* Test results and coverage information

## Pull Request Guidelines

### Before Submitting

* [ ] Code follows our [style guide](/advanced/code-style)
* [ ] All tests pass (`make test`)
* [ ] New tests added for new features
* [ ] Documentation updated if needed
* [ ] Commit messages follow conventional format
* [ ] No merge conflicts with main branch

### PR Description Template

```markdown theme={null}
## Description
Brief description of what this PR does.

## Changes
- List of specific changes made
- Include technical details

## Testing
- How was this tested?
- What test cases were added?

## Related Issues
Fixes #123
Related to #456

## Screenshots (if applicable)
[Add screenshots for UI changes]
```

### Review Process

1. **Automated Checks**: CI/CD runs tests and linting
2. **Code Review**: Maintainers review code quality and design
3. **Testing**: Reviewers test functionality
4. **Approval**: At least one maintainer approval required
5. **Merge**: Maintainer merges the PR

### PR Regression Checks

Every pull request runs the backend regression workflow, including:

* `tests/test_provisioner_kubeconfig.py`
* `tests/test_docker_sandbox_mode_detection.py`
* All unit tests in the test suite

These checks must pass before your PR can be merged.

## Development Best Practices

### Test-Driven Development (TDD)

**Every new feature or bug fix MUST be accompanied by unit tests. No exceptions.**

* Write tests before implementing features
* Ensure all tests pass before submitting PR
* Aim for high test coverage
* See [Testing Guide](/advanced/testing) for details

### Code Quality

* Follow the [Code Style Guide](/advanced/code-style)
* Use type hints in Python code
* Write clear, self-documenting code
* Add comments for complex logic
* Keep functions small and focused

### Documentation

**CRITICAL: Always update documentation after code changes**

* Update `README.md` for user-facing changes
* Update `CLAUDE.md` for development changes
* Keep documentation synchronized with code
* Add inline documentation for complex code

### Debugging

See the [Debugging Guide](/advanced/debugging) for techniques and tools to help troubleshoot issues during development.

## Getting Help

* Check existing [Issues](https://github.com/bytedance/deer-flow/issues)
* Read the [Documentation](https://github.com/bytedance/deer-flow/tree/main/backend/docs)
* Ask questions in [Discussions](https://github.com/bytedance/deer-flow/discussions)
* Review [Architecture Documentation](https://github.com/bytedance/deer-flow/blob/main/backend/CLAUDE.md)

## Common Development Tasks

### Adding a New API Endpoint

1. Add route to appropriate router in `backend/src/gateway/routers/`
2. Add corresponding tests in `backend/tests/`
3. Update API documentation
4. Test endpoint manually and with automated tests

### Adding a New Middleware

1. Create middleware in `backend/src/agents/middlewares/`
2. Add middleware to chain in `backend/src/agents/lead_agent/agent.py`
3. Consider middleware order (see CLAUDE.md for details)
4. Add unit tests for middleware logic
5. Update CLAUDE.md with middleware description

### Adding a New Tool

1. Implement tool in appropriate directory:
   * Built-in: `backend/src/tools/builtins/`
   * Community: `backend/src/community/`
2. Register tool in `config.yaml` under `tools` section
3. Add tool to appropriate tool group
4. Add tests for tool functionality
5. Document tool usage

### Modifying Configuration Schema

1. Update Pydantic models in `backend/src/config/`
2. Update `config.example.yaml` with new fields
3. Add migration notes if breaking changes
4. Update configuration documentation
5. Add tests for config validation

## License

By contributing to DeerFlow, you agree that your contributions will be licensed under the [MIT License](https://github.com/bytedance/deer-flow/blob/main/LICENSE).