# Local Development Setup

> Set up a local FastGPT development and debugging environment with Node.js, pnpm, database dependencies, environment variables, and plugin services.

Source: https://doc.fastgpt.io/self-host/dev
Last Updated: 2026-11-12

This guide covers how to set up your development environment to build and test FastGPT.

## Prerequisites

Install and configure these dependencies on your machine to build FastGPT:

* [Git](https://git-scm.com/)
* [Docker](https://www.docker.com/)
* [Node.js 22.23.4+ / 24.22.1+ / 26.12.1+](https://nodejs.org) (Node.js 24.x matching the Dockerfile is recommended; use [nvm](https://github.com/nvm-sh/nvm) to manage Node versions)
* [pnpm](https://pnpm.io/) 10.x, matching the repository packageManager version

We recommend developing on \*nix environments (Linux, macOS, Windows WSL).

## Local Development

### 1. Fork the FastGPT Repository

Fork the [FastGPT repository](https://github.com/labring/FastGPT).

### 2. Clone the Repository

Clone your forked repository from GitHub:

```
git clone git@github.com:<your_github_username>/FastGPT.git
```

### 3. Start the Development Environment with Docker

If you're already running FastGPT locally via Docker, stop it first to avoid port conflicts.

Navigate to `FastGPT/deploy/dev` and run `docker compose up -d` to start FastGPT's dependencies:

```bash
cd FastGPT/deploy/dev
docker compose up -d
```

> 1. If you cannot pull images, use the China mirror file `docker-compose.cn.yml`: `docker compose -f docker-compose.cn.yml up -d`.
> 2. For MongoDB, add the `directConnection=true` parameter to your connection string to connect to the replica set.

### 4. Initial Configuration

All files below are in the `projects/app` directory.

```bash
# Make sure you're in projects/app
pwd
# Should output /xxxx/xxxx/xxx/FastGPT/projects/app
```

**1. Environment Variables**

Copy `.env.template` to create `.env.local` in the same directory. Only changes in `.env.local` take effect.
See `.env.template` for variable descriptions.
`FILE_TOKEN_KEY=` is empty in the template but required (at least 6 characters). Set it to a random string in `.env.local` first, or startup fails with `Invalid environment variables`. For the other variables, if you haven't modified them in docker-compose.yaml, the defaults in `.env.template` work as-is. Otherwise, match the values in your `yml` file.
Also update `PLUGIN_TOKEN` in `.env.local` to match `x-plugin-auth-token` in `deploy/dev/docker-compose.yml` (`fastgpt-plugin-dev-token-12345678`). For all other variables, the `.env.template` defaults work when `docker-compose.yml` is unchanged.

```bash
cp .env.template .env.local
```

**2. System Parameters**

Starting with 4.15.0, the open-source edition reads environment variables for system parameters; set them in `.env.local` as needed. See [Environment Variables](https://doc.fastgpt.io/self-host/config/env) for the full list:

* `VECTOR_MAX_PROCESS`: Max vector generation processes (defaults to `10`). Adjust based on database and model key concurrency; 10–15 is recommended for a 2c4g server.
* `QA_MAX_PROCESS`: Max QA generation processes
* `VLM_MAX_PROCESS`: Max image understanding model processes
* `HNSW_EF_SEARCH`: HNSW vector search width (defaults to `200`) for PG, Milvus, OceanBase, SeekDB, and openGauss. Higher values generally improve recall with increased search latency.

### 5. Run

See `dev.md` in the project root. The first build may take longer while dependencies are compiled.

```bash
# Run from the code root directory to install all dependencies
# If isolate-vm installation fails, see: https://github.com/laverdet/isolated-vm?tab=readme-ov-file#requirements
pwd # Should be in the code root directory
pnpm i
cd projects/app
pnpm dev
```

Next.js runs on port 3000 by default. Visit [http://localhost:3000](http://localhost:3000)

### 6. Build

We recommend using Docker for builds.

```bash
# Without proxy
docker build -f ./projects/app/Dockerfile -t fastgpt .
# With China mirrors (any non-empty proxy switches to the ustc apt mirror and npmmirror registry)
docker build -f ./projects/app/Dockerfile -t fastgpt . --build-arg proxy=1
```

Without Docker, you'd need to manually execute all the run-stage commands from the `Dockerfile` (not recommended).

## Contributing to the Open Source Repository

1. Make sure your code is forked from the [FastGPT](https://github.com/labring/FastGPT) repository.
2. Keep commits small and focused — each should address one issue.
3. Submit a PR to FastGPT's main branch. The FastGPT team and community will review it with you.

If you run into issues like merge conflicts, check GitHub's [pull request tutorial](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests). Once your PR is merged, you'll be listed in the [contributors table](https://github.com/labring/FastGPT/graphs/contributors).

## Local Development Troubleshooting

### System Time Anomaly

If your default timezone is `Asia/Shanghai`, system time may be incorrect in non-Linux environments. For local development, change your timezone to UTC (+0).

### Can't Connect to Local Database

1. For remote databases, check if the port is open.
2. For local databases, try changing `host` to `localhost` or `127.0.0.1`.
3. For local connections to remote MongoDB, add `directConnection=true` to connect to replica sets.
4. Use MongoDB Compass for MongoDB connection testing and visual management.
5. Use Navicat or another PostgreSQL client for PostgreSQL connection and management.

### postinstall Script Fails

FastGPT runs the `postinstall` script from the root `package.json` after `pnpm i` to generate Chakra UI types and build the SDK and workflow subpackages. If `postinstall` fails, run the steps manually from the repository root:

```bash
pnpm gen:theme-typings && pnpm run build:sdks && pnpm run build:workflow-packages
```

### TypeError: Cannot read properties of null (reading 'useMemo')

Verify the repository requirements (Node.js `22.23.4+` / `24.22.1+` / `26.12.1+` and pnpm 10.x), check React dependency consistency, and reinstall from the lockfile. Local dev workflow:

1. Root directory: `pnpm i`
2. Copy `.env.template` -> `.env.local` and set `FILE_TOKEN_KEY`
3. Configure other environment variables in `.env.local` as needed
4. `cd projects/app`
5. `pnpm dev`

### Error response from daemon: error while creating mount source path 'XXX': mkdir XXX: file exists

This may be caused by leftover files from a previous container stop. Make sure all related containers are stopped, then manually delete the files or restart Docker.

## Join the Community

Having trouble? Join the Lark group to connect with developers and users.

## Code Structure

### Next.js

FastGPT uses Next.js page routing. To separate frontend and backend code, directories are split into global, service, and web subdirectories for shared, backend-only, and frontend-only code respectively.

### Monorepo

FastGPT uses pnpm workspace for its monorepo structure, with two main parts:

* projects/ - Application projects: `app` is the FastGPT main project, alongside services such as code-sandbox, agent-sandbox, agent-sandbox-proxy, volume-manager, mcp_server, and marketplace
* packages/ - Submodules
  * global - Shared code: functions, type declarations, and constants usable on both frontend and backend
  * service - Server-side code
  * web - Frontend code
  * dal, next, workflow-cli, workflow-core - Other shared subpackages

### Domain-Driven Design (DDD)

FastGPT's code modules follow DDD principles, divided into these domains:

* core - Core features (Dataset, workflow, app, conversation)
* support - Supporting features (user system, billing, authentication, etc.)
* common - Base features (log management, file I/O, etc.)

**Code Structure Details**

```
.
├── .github                      // GitHub config
├── .husky                       // Formatting config
├── deploy                       // Deployment template sources (docker-compose, k8s, etc.)
├── document                     // Documentation
├── packages                     // Subpackages
│   ├── dal
│   ├── global                   // Frontend/backend shared subpackage
│   ├── next
│   ├── service                  // Backend subpackage
│   ├── web                      // Frontend subpackage
│   ├── workflow-cli
│   └── workflow-core
├── projects
│   ├── app                      // FastGPT main project
│   ├── agent-sandbox            // Agent sandbox image
│   ├── agent-sandbox-proxy      // Agent sandbox proxy
│   ├── code-sandbox             // Code run sandbox
│   ├── fastgpt-ide-agent
│   ├── marketplace              // Plugin marketplace
│   ├── mcp_server               // MCP Server
│   └── volume-manager           // OpenSandbox volume manager
├── sdk                          // SDKs such as otel, sandbox-adapter, and storage
├── scripts                      // Automation scripts
│   ├── icon                     // Icon scripts: pnpm initIcon (write SVG to code), pnpm previewIcon (preview icons)
│   └── postinstall.sh           // ChakraUI custom theme TS type initialization
├── test                         // Tests
├── package.json                 // Top-level monorepo
├── pnpm-lock.yaml
├── pnpm-workspace.yaml          // Monorepo declaration
├── LICENSE
├── README.md
├── README_en.md
├── README_ja.md
└── dev.md
```
