# How to Install Lobe Chat Locally: Complete Development Setup > Install Lobe Chat locally with our step-by-step guide. Clone the repository environment variables and launch the full-stack development server quickly and easily. - Repository: [LobeHub/lobe-chat](https://github.com/lobehub/lobe-chat) - Tags: getting-started - Published: 2026-03-02 --- **Clone the `lobehub/lobe-chat` repository, run `pnpm install` to install monorepo dependencies, create a `.env.local` file with your API keys, and execute `pnpm dev` to start the full-stack development server on `localhost:3010`.** Lobe Chat (branded as **LobeHub**) is a modern, open-source AI agent workspace built as a **monorepo** architecture combining Next.js, Electron, and PostgreSQL. This guide provides the exact steps to install Lobe Chat locally using the official source code, covering everything from dependency installation to running the development environment. ## Prerequisites for Local Installation Before you install Lobe Chat locally, ensure your environment meets the following requirements: - **Node.js ≥ 20** – The repository requires modern Node features; Bun is used for some scripts, but `pnpm` on Node works reliably. - **pnpm ≥ 10** – The monorepo uses pnpm workspaces and the lockfile is pnpm-based. - **Docker** (optional) – Only required if you prefer container-based deployment or need to run PostgreSQL/Redis via Docker Compose. ## Step-by-Step Installation Guide ### 1. Clone the Repository Start by cloning the official repository and navigating into the project directory: ```bash git clone https://github.com/lobehub/lobe-chat.git cd lobe-chat ``` ### 2. Install Monorepo Dependencies Run the following command to install all dependencies across the workspaces defined in [`package.json`](https://github.com/lobehub/lobe-chat/blob/main/package.json): ```bash pnpm install ``` This command installs packages for the frontend (`src/app/`), the desktop client (`apps/desktop/`), the database layer (`packages/database/`), and all other monorepo modules. ### 3. Configure Environment Variables To connect to external LLM providers, create a `.env.local` file in the project root. At minimum, set your OpenAI API key: ```dotenv OPENAI_API_KEY=sk-xxxxxx... ``` The repository includes an `.env.example` file you can copy for additional configuration options. Environment variables are loaded by Next.js according to the schema defined in the server configuration. ### 4. Start the Development Server Run the main development script to start the full-stack environment: ```bash pnpm dev ``` This executes `tsx scripts/devStartupSequence.mts`, which concurrently launches: - The **Next.js** server on `http://localhost:3010` - The **Vite SPA** dev server on `http://localhost:9876` Open your browser to `http://localhost:3010` to access the LobeHub interface. ## Alternative Installation Methods Depending on your use case, you can run specific parts of the stack: ### Running Only the Frontend SPA For UI development without the backend API, use: ```bash pnpm dev:spa ``` This starts the Vite-based single-page application on `http://localhost:9876`, utilizing the proxy configuration for API calls. ### Desktop Client (Electron) To run the Electron wrapper that bundles the SPA: ```bash pnpm dev:desktop ``` This command navigates to `apps/desktop/` and starts the Electron main process with hot-reload enabled for the renderer process. ### Docker Deployment For a fully containerized local instance: ```bash # Build the Docker image pnpm self-hosting:docker # Run the container docker run -p 3210:3210 lobehub:local ``` The Dockerfile at the repository root bundles the Next.js build, database migrations, and a lightweight Alpine runtime, exposing port `3210` by default. ## Understanding the Monorepo Structure When you install Lobe Chat locally, you are working with a **pnpm monorepo** organized as follows: - **`src/app/`** – Next.js 16 app router containing the main web application and API routes (`src/server/`). - **`src/spa/`** – Vite-based SPA entry points for the client-side rendered bundle. - **`apps/desktop/`** – Electron main process and desktop-specific code (`apps/desktop/src/main`). - **`packages/database/`** – Drizzle ORM schema and PGLite/PostgreSQL adapters. - **`packages/agent-runtime/`** – Plugin architecture for agent execution. - **`scripts/devStartupSequence.mts`** – Orchestration script that coordinates the dev servers. This structure allows you to modify the frontend, backend, or desktop client independently while sharing code through the `packages/` directory. ## Summary - **Prerequisites**: Node.js ≥ 20, pnpm ≥ 10, and optionally Docker. - **Core command**: `pnpm dev` starts the full stack via `scripts/devStartupSequence.mts`, launching Next.js on port 3010 and the Vite SPA on port 9876. - **Environment**: Create `.env.local` with your `OPENAI_API_KEY` to enable LLM features. - **Alternatives**: Run `pnpm dev:spa` for frontend-only, `pnpm dev:desktop` for Electron, or use `pnpm self-hosting:docker` for containerized deployment. - **Architecture**: The monorepo uses pnpm workspaces with distinct packages for the web app (`src/app/`), desktop (`apps/desktop/`), and database layer (`packages/database/`). ## Frequently Asked Questions ### What are the minimum system requirements to install Lobe Chat locally? You need **Node.js version 20 or higher** and **pnpm version 10 or higher** to handle the monorepo workspaces and lockfile format. While Bun is used internally for some build scripts, pnpm on Node is the standard development workflow. Docker is only required if you choose the containerized deployment method or need to run PostgreSQL/Redis via Docker Compose. ### Can I run Lobe Chat without connecting to external LLM providers? Yes, the application will start without API keys configured, but functionality will be limited to the UI and local features. To enable AI conversations, you must provide at least one provider key—typically `OPENAI_API_KEY` in your `.env.local` file. The repository includes an `.env.example` file documenting all supported environment variables for various providers. ### How do I switch between the web version and desktop client during development? The monorepo provides separate commands for each target. Use `pnpm dev` to run the full-stack web version (Next.js + Vite SPA), or `pnpm dev:desktop` to launch the Electron wrapper located in `apps/desktop/`. Both commands leverage hot-reload, allowing you to switch contexts without reinstalling dependencies, though the desktop client requires building the SPA assets first. ### Where are the database migrations located in the Lobe Chat monorepo? Database schema and migrations are managed in the **`packages/database/`** directory using **Drizzle ORM**. This package handles both PostgreSQL for production deployments and **PGLite** for lightweight local development. The migration files and schema definitions are co-located here, separate from the Next.js application code in `src/app/` and the desktop client in `apps/desktop/`.