How to Install Lobe Chat Locally: Complete Development Setup

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:

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:

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:

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:

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:

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:

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:

# 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/.

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