# How to Set Up the Development Environment for Lobe Chat: A Complete Guide > Set up the Lobe Chat development environment easily. Clone the repo, install dependencies, configure API keys, and run `pnpm dev` to start building. - Repository: [LobeHub/lobe-chat](https://github.com/lobehub/lobe-chat) - Tags: how-to-guide - Published: 2026-03-03 --- **To set up the development environment for Lobe Chat, clone the `lobehub/lobe-chat` repository, install pnpm 10, run `pnpm install` to bootstrap the monorepo workspaces, copy `.env.example` to `.env` and configure your API keys, then execute `pnpm dev` to start the parallel Next.js and Vite development servers.** Lobe Chat is a full-stack AI-agent workspace built as a monorepo using Next.js 16, Vite, TypeScript, and pnpm workspaces. Whether you are contributing to the core application or extending the desktop Electron wrapper, configuring a local development environment requires specific toolchain versions and environment variables to orchestrate the concurrent server architecture. ## Prerequisites and System Requirements Before cloning the repository, ensure your system meets the following requirements defined in the [`package.json`](https://github.com/lobehub/lobe-chat/blob/main/package.json) `packageManager` field and workspace configuration: - **Node.js** compatible with pnpm 10 - **pnpm** version 10 or higher (required by the `packageManager` field) - **Git** to clone the `canary` branch (the default development branch) - Optional: **Bun** runtime for faster script execution (the repository includes bun wrappers for all npm scripts) ## Step-by-Step Development Environment Setup ### Clone the Repository and Checkout the Canary Branch Start by cloning the official repository and entering the directory. The active development branch is `canary`, which contains the latest features and fixes: ```bash git clone https://github.com/lobehub/lobe-chat.git cd lobe-chat git checkout canary ``` ### Install Dependencies with pnpm The repository uses pnpm workspaces to manage the monorepo structure, including shared packages under `packages/*` and application code under `apps/`. Install all workspace dependencies with: ```bash npm i -g pnpm@10 pnpm install ``` This command bootstraps every workspace defined in [`pnpm-workspace.yaml`](https://github.com/lobehub/lobe-chat/blob/main/pnpm-workspace.yaml), including the desktop Electron application and shared UI components. ### Configure Environment Variables Create a local environment file from the provided template. The `.env.example` file contains all required variables for API keys, database connections, Redis, authentication, and security settings: ```bash cp .env.example .env ``` Edit `.env` to include at minimum: - `OPENAI_API_KEY` or keys for other model providers (Anthropic, Google, etc.) - Database URL if using Drizzle ORM with PostgreSQL - Redis connection string for session management - `NEXT_PUBLIC_` prefixed variables for client-side feature flags The `.env.example` file documents each variable, including CSP toggles and SSRF protection settings required for secure local development. ### Launch the Development Servers Start the full development environment using the convenience script defined in [`package.json`](https://github.com/lobehub/lobe-chat/blob/main/package.json): ```bash pnpm dev ``` This command executes `scripts/devStartupSequence.mts`, which orchestrates the parallel startup of the Next.js server and Vite SPA, handles graceful shutdown on `SIGINT`/`SIGTERM`, and monitors server health. ## Understanding the Development Server Architecture When you run `pnpm dev`, the `devStartupSequence.mts` script performs several critical functions referenced in the source code: 1. **Port Extraction**: It reads the `dev:next` script from [`package.json`](https://github.com/lobehub/lobe-chat/blob/main/package.json) to extract the default Next.js port (3010) as implemented in lines 9-22 of `devStartupSequence.mts`. 2. **Process Spawning**: It spawns two child processes—`npm run dev:next` for the Next.js application and `npm run dev:spa` for the Vite development server (lines 31-35). 3. **Health Monitoring**: The script watches both processes, implements graceful shutdown handlers, and logs the Next.js URL for quick access (lines 95-103). The Next.js server handles server-side rendering, API routes, and database connections via Drizzle ORM, while the Vite SPA (running on port 9876 by default) provides the hot-module-replaced frontend development experience. ## Alternative Development Workflows ### Running Individual Servers For debugging specific components, you can start the servers independently: ```bash # Next.js server only (useful for backend/API debugging) pnpm dev:next # Vite SPA only (port 9876 by default) pnpm dev:spa ``` ### Using Bun Runtime The repository supports Bun as an alternative package manager and runtime. If you have Bun installed, you can use it interchangeably with pnpm: ```bash bun run dev bun run dev:next bun run dev:spa ``` ### Building Production Assets To verify your changes compile correctly without Docker: ```bash pnpm build ``` This command builds both the Next.js application and the Vite SPA, outputting static assets to the `dist` directories. ## Summary Setting up the Lobe Chat development environment requires: - **Cloning** the `lobehub/lobe-chat` repository and switching to the `canary` branch - **Installing** pnpm 10 and running `pnpm install` to bootstrap the monorepo workspaces - **Configuring** environment variables by copying `.env.example` to `.env` and adding your API keys - **Launching** the parallel development servers with `pnpm dev`, which executes `scripts/devStartupSequence.mts` to manage the Next.js and Vite processes With these steps, you will have a fully functional local instance of the AI-agent workspace running on ports 3010 (Next.js) and 9876 (Vite SPA), ready for customization and contribution. ## Frequently Asked Questions ### What is the minimum Node.js version required for Lobe Chat development? The repository specifies pnpm 10 in the `packageManager` field of [`package.json`](https://github.com/lobehub/lobe-chat/blob/main/package.json), which requires a compatible Node.js version (generally Node.js 18 or higher). While the exact Node version isn't strictly pinned in the documentation, using the current LTS release ensures compatibility with Next.js 16 and the Vite build toolchain. ### Can I run Lobe Chat without setting up a database? Yes, for basic frontend development and testing AI model integrations, you can run Lobe Chat using only the OpenAI API key or other LLM provider keys configured in `.env`. However, to test features requiring persistent storage—such as user authentication, conversation history, or agent configurations—you will need to configure the database connection variables (Drizzle ORM with PostgreSQL) and optionally Redis for session management. ### How do I debug only the backend API routes? To isolate backend debugging, run `pnpm dev:next` instead of the full `pnpm dev` command. This starts only the Next.js server (defaulting to port 3010) without launching the Vite SPA, allowing you to focus on server-side rendering, API route handlers, and database interactions via Drizzle ORM without the frontend build process consuming resources. ### Is there a way to use Bun instead of pnpm for development? Yes, the Lobe Chat repository supports Bun as an alternative runtime and package manager. After installing Bun, you can substitute `pnpm` commands with `bun run` (e.g., `bun run dev`, `bun run dev:next`, `bun run build`). The repository structure includes Bun-compatible wrappers for the npm scripts defined in [`package.json`](https://github.com/lobehub/lobe-chat/blob/main/package.json), though pnpm remains the officially documented package manager for workspace compatibility.