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

> Discover Lobe Chat system requirements for local, desktop, and self-hosting. Learn about Node.js, pnpm, and database needs for Windows, macOS, and Linux.

- Repository: [LobeHub/lobe-chat](https://github.com/lobehub/lobe-chat)
- Tags: how-to-guide
- Published: 2026-03-02

---

**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`](https://github.com/lobehub/lobe-chat/blob/main/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`](https://github.com/lobehub/lobe-chat/blob/main/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`](https://github.com/lobehub/lobe-chat/blob/main/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`](https://github.com/lobehub/lobe-chat/blob/main/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:

```bash

# 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`](https://github.com/lobehub/lobe-chat/blob/main/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:

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

```bash

# 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`](https://github.com/lobehub/lobe-chat/blob/main/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`](https://github.com/lobehub/lobe-chat/blob/main/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`](https://github.com/lobehub/lobe-chat/blob/main/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.