How to Set Up the Development Environment for Lobe Chat: A Complete Guide

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 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:

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:

npm i -g pnpm@10
pnpm install

This command bootstraps every workspace defined in 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:

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:

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 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:

# 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:

bun run dev
bun run dev:next
bun run dev:spa

Building Production Assets

To verify your changes compile correctly without Docker:

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, 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, though pnpm remains the officially documented package manager for workspace compatibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}