Lobe Chat System Requirements: Local, Desktop, and Self-Hosting Setup Guide

Lobe Chat requires Node.js 22+, pnpm 10+, and optional PostgreSQL/Redis for self-hosting, supporting Windows, macOS, and Linux architectures.

Lobe Chat (also branded as LobeHub) is a modern, full-stack AI agent workspace that supports multiple deployment modes including local development, desktop applications, and server-side self-hosting. Understanding the specific system requirements ensures smooth installation whether you are contributing to the lobehub/lobe-chat repository or deploying a production instance.

Core Runtime Requirements

The foundation of Lobe Chat relies on a modern JavaScript toolchain. According to the source code in apps/desktop/README.md, the minimum versions are strictly enforced for compatibility with the monorepo structure and build tools.

Node.js 22+ (LTS) is required to compile and run the Next.js backend, Vite SPA frontend, and the Electron-based desktop client. The project leverages modern Node.js features for its build pipeline and API server.

pnpm 10+ serves as the mandatory package manager. The repository uses pnpm workspaces to manage the monorepo dependencies, and all installation, building, linting, and testing scripts assume pnpm is available. Attempting to use npm or yarn will result in dependency resolution failures.

Electron is bundled automatically with the desktop build, providing the native cross-platform wrapper for the UI and system integration.

Operating System Support

The desktop client supports multiple architectures across major operating systems, as documented in apps/desktop/README.md:

• Windows: 64-bit (x64) architecture only
• macOS: Both Intel (x64) and Apple Silicon (arm64) with separate installer files provided for each architecture
• Linux: Most modern distributions supporting glibc ≥ 2.28, distributed as AppImage or tarball formats

Server-Side Dependencies for Self-Hosting

When self-hosting Lobe Chat on servers or via Docker, additional infrastructure services are required beyond the Node.js runtime. The docker-compose/dev/docker-compose.yml file defines the development stack, while production deployments follow similar patterns.

PostgreSQL stores persistent application data. While no explicit version is locked in the source, PostgreSQL 13+ is recommended for compatibility with the Drizzle ORM implementation.

Redis handles session caching and background job processing. This is mandatory for production deployments to maintain state across server restarts.

Docker Compose v2 is required to orchestrate the multi-container stack including PostgreSQL, Redis, RustFS, and optional services like SearXNG.

Optional Services:

• RustFS: Provides S3-compatible object storage for file uploads
• SearXNG: Enables the "Smart Internet Search" feature within chat sessions

Environment Configuration

Self-hosted instances require specific environment variables defined in .env.example. At minimum, you must provide an OpenAI API key via OPENAI_API_KEY or configure alternative AI providers. Additional variables such as OPENAI_PROXY_URL for network routing or ENABLE_OIDC for authentication can be customized based on your deployment needs.

Development and CI Requirements

Contributors running the test suite should note the requirements documented in e2e/README.md. The continuous integration pipeline tests against Node.js 20, 22, or ≥24, and requires Playwright with Chromium browsers for end-to-end testing. All contributors must use pnpm 10+ and have Docker Compose available to run integration tests against real database instances.

Deployment Examples

Local Development Setup

To run the full-stack development environment locally, execute the following commands from the repository root:

# Clone and install dependencies

git clone https://github.com/lobehub/lobe-chat.git
cd lobe-chat
pnpm install

# Start supporting services (PostgreSQL, Redis, RustFS, SearXNG)

pnpm dev:docker

# Run the full-stack dev server (Next.js + Vite SPA)

pnpm dev

The pnpm dev script, defined in package.json (lines 61-63), concurrently starts the Next.js API server and Vite frontend with hot-reload enabled at http://localhost:3010.

Desktop Client Build

For building the native desktop application, navigate to the desktop-specific directory:

cd apps/desktop
pnpm install-isolated
pnpm dev  # Launch Electron with hot-reload

# Create distributable packages

pnpm package:mac    # macOS Intel + Apple Silicon bundles

pnpm package:win    # Windows installer

pnpm package:linux  # Linux AppImage/Tarball

Each package:* command invokes Electron Builder to produce native installers targeting the specific operating system architecture.

Docker Compose Production Deployment

For production self-hosting, use the deployment-specific compose configuration:

# Download production configuration files

curl -O https://raw.githubusercontent.com/lobehub/lobe-chat/HEAD/docker-compose/deploy/docker-compose.yml
curl -O https://raw.githubusercontent.com/lobehub/lobe-chat/HEAD/docker-compose/deploy/.env.example
mv .env.example .env

# Edit .env with your database credentials and API keys, then start services

docker compose up -d

This configuration launches PostgreSQL, Redis, the LobeHub server, RustFS, and SearXNG in detached mode. The production compose file also includes optional observability stacks (Grafana, Loki, Tempo) that can be enabled by uncommenting the relevant service definitions.

Summary

• Node.js 22+ and pnpm 10+ are mandatory for all deployment modes
• Desktop builds support Windows (x64), macOS (Intel/Apple Silicon), and Linux
• Self-hosting requires PostgreSQL and Redis via Docker Compose
• Development workflows use pnpm dev:docker to spin up infrastructure dependencies
• Production deployments rely on environment variables defined in .env.example for API keys and database connections

Frequently Asked Questions

What are the minimum Node.js and pnpm versions for Lobe Chat?

Lobe Chat requires Node.js 22+ (LTS) and pnpm 10+ to function correctly. These versions are enforced across the monorepo to ensure compatibility with the Next.js framework, Vite build tooling, and Electron desktop wrapper. Using older versions will result in build failures or runtime errors.

Can I run Lobe Chat on Apple Silicon Macs?

Yes, Lobe Chat fully supports Apple Silicon (arm64) architecture. According to apps/desktop/README.md, separate installer files are provided for both Intel (x64) and Apple Silicon Macs. When building from source, the pnpm package:mac command generates universal binaries or architecture-specific bundles depending on your build configuration.

What database does Lobe Chat require for self-hosting?

Lobe Chat uses PostgreSQL as its primary database for persistent storage, recommended at version 13 or higher for Drizzle ORM compatibility. Redis is also required for session management and caching. Both services are automatically configured when using the Docker Compose setup defined in docker-compose/dev/docker-compose.yml.

How do I start the development environment with Docker Compose?

Run pnpm dev:docker from the repository root to initialize the development stack. This command, defined in package.json, starts PostgreSQL, Redis, RustFS, and SearXNG in Docker containers. To stop the services, use pnpm dev:docker:down, or run pnpm dev:docker:reset to clear volumes and restart with fresh data.

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