Local Development Setup
Set up a local FastGPT development and debugging environment with Node.js, pnpm, database dependencies, environment variables, and plugin services.
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
- Docker
- Node.js 22.23.4+ / 24.22.1+ / 26.12.1+ (Node.js 24.x matching the Dockerfile is recommended; use nvm to manage Node versions)
- pnpm 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.
2. Clone the Repository
Clone your forked repository from GitHub:
git clone [email protected]:<your_github_username>/FastGPT.git3. 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:
cd FastGPT/deploy/dev
docker compose up -d- If you cannot pull images, use the China mirror file
docker-compose.cn.yml:docker compose -f docker-compose.cn.yml up -d. - For MongoDB, add the
directConnection=trueparameter to your connection string to connect to the replica set.
4. Initial Configuration
All files below are in the projects/app directory.
# Make sure you're in projects/app
pwd
# Should output /xxxx/xxxx/xxx/FastGPT/projects/app1. 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.
cp .env.template .env.local2. 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 for the full list:
VECTOR_MAX_PROCESS: Max vector generation processes (defaults to10). Adjust based on database and model key concurrency; 10–15 is recommended for a 2c4g server.QA_MAX_PROCESS: Max QA generation processesVLM_MAX_PROCESS: Max image understanding model processesHNSW_EF_SEARCH: HNSW vector search width (defaults to200) 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.
# 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 devNext.js runs on port 3000 by default. Visit http://localhost:3000
6. Build
We recommend using Docker for builds.
# 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=1Without Docker, you'd need to manually execute all the run-stage commands from the Dockerfile (not recommended).
Contributing to the Open Source Repository
- Make sure your code is forked from the FastGPT repository.
- Keep commits small and focused — each should address one issue.
- 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. Once your PR is merged, you'll be listed in the contributors table.
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
- For remote databases, check if the port is open.
- For local databases, try changing
hosttolocalhostor127.0.0.1. - For local connections to remote MongoDB, add
directConnection=trueto connect to replica sets. - Use MongoDB Compass for MongoDB connection testing and visual management.
- 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:
pnpm gen:theme-typings && pnpm run build:sdks && pnpm run build:workflow-packagesTypeError: 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:
- Root directory:
pnpm i - Copy
.env.template->.env.localand setFILE_TOKEN_KEY - Configure other environment variables in
.env.localas needed cd projects/apppnpm 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:
appis 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.mdLast updated