LobeChat

https://lobehub.com/docs/
Admin
LobeChat is an open-source AI chat application that supports multiple AI providers, local LLMs,...
Tokens:96,448
Snippets:1,620
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clone and Install Dependencies

Source: https://lobehub.com/docs/self-hosting/migration/v2/auth/clerk-to-betterauth

Initial setup steps to prepare the local environment for migration.

```shell
git clone https://github.com/lobehub/lobehub.git
cd lobehub
pnpm install
```

--------------------------------

### Install Dokploy

Source: https://lobehub.com/docs/self-hosting/platform/dokploy

Use this command to install the Dokploy platform on your server.

```shell
curl -sSL https://dokploy.com/install.sh | sh
```

--------------------------------

### Start the development server

Source: https://lobehub.com/docs/development/basic/setup-development

Launch the Next.js development server to begin local development.

```shell
bun run dev
```

--------------------------------

### PostgreSQL Connection URL Example

Source: https://lobehub.com/docs/self-hosting/platform/dokploy

Example format for the Postgres database connection string used in Dokploy.

```shell
postgresql://postgres:wAbLxfXSwkxxxxxx@45.577.281.48:5432/postgres
```

--------------------------------

### Model Extension Configuration Examples

Source: https://lobehub.com/docs/self-hosting/advanced/model-list

Various examples demonstrating how to map model IDs to display names with specific token limits and enabled capabilities.

```text
chatglm-6b=ChatGLM 6B<4096>
spark-v3.5=讯飞星火 v3.5<8192:fc>
gemini-2.5-flash=Gemini 2.5 Flash<16000:vision>
o3-mini=OpenAI o3-mini<200000:reasoning:fc>
qwen-max-latest=Qwen Max<32768:search:fc>
gpt-4-all=ChatGPT Plus<128000:fc:vision:file>
gemini-2.0-flash-exp-image-generation=Gemini 2.0 Flash (Image Generation) Experimental<32768:imageOutput:vision>
```

--------------------------------

### Install project dependencies

Source: https://lobehub.com/docs/development/basic/setup-development

Use PNPM to install all required project dependencies.

```shell
pnpm i
```

--------------------------------

### View Configuration Report

Source: https://lobehub.com/docs/self-hosting/platform/docker-compose

Example output showing generated service URLs and credentials.

```text
The results of the secure key generation are as follows:
LobeHub:
  - URL: http://localhost:3210
RustFS:
  - URL: http://localhost:9000
  - Username: admin
  - Password: 8c82ea41
```

```text
The results of the secure key generation are as follows:
LobeHub:
  - URL: http://your_server_ip:3210
RustFS:
  - URL: http://your_server_ip:9000
  - Username: admin
  - Password: dbac8440
```

--------------------------------

### Configure environment files

Source: https://lobehub.com/docs/development/basic/setup-development

Copy the example environment configuration files to their active locations.

```shell
# Docker services configuration
cp docker-compose/dev/.env.example docker-compose/dev/.env

# Next.js development server configuration
cp .env.example.development .env
```

--------------------------------

### Start Docker services

Source: https://lobehub.com/docs/development/basic/setup-development

Launch the required infrastructure services using the Bun script.

```shell
bun run dev:docker
```

--------------------------------

### Install vLLM with uv

Source: https://lobehub.com/docs/usage/providers/vllm

Commands to create a virtual environment and install vLLM using the uv package manager.

```shell
uv venv myenv --python 3.12 --seed
source myenv/bin/activate
uv pip install vllm
```

--------------------------------

### Install Ollama on Linux

Source: https://lobehub.com/docs/usage/providers/ollama

Use the official installation script to set up Ollama on a Linux system.

```shell
curl -fsSL https://ollama.com/install.sh | sh
```

--------------------------------

### Example image generation prompts

Source: https://lobehub.com/docs/usage/getting-started/generation

These examples demonstrate how to combine style, lighting, and subject details for specific visual outcomes.

```plaintext
"A futuristic city skyline at sunset, digital art, cyberpunk style, neon lights reflecting on wet streets, cinematic lighting, 4K detail"

"A cozy coffee shop interior, watercolor illustration, warm golden light streaming through windows, potted plants on windowsills, soft and inviting atmosphere"

"A product photo of a minimalist leather wallet on a clean white background, studio lighting, sharp focus, commercial photography style"
```

--------------------------------

### Execute Deployment Script

Source: https://lobehub.com/docs/self-hosting/platform/docker-compose

Fetches and runs the automated setup script for LobeHub.

```bash
bash <(curl -fsSL https://lobe.li/setup.sh) -l en
```

--------------------------------

### Perform Clean Install

Source: https://lobehub.com/docs/development/basic/setup-development

Removes existing node_modules and performs a fresh dependency installation to resolve environment issues.

```shell
bun run clean:node_modules && pnpm install
```

--------------------------------

### Install Filesystem MCP Server

Source: https://lobehub.com/docs/usage/community/mcp-market

Command to install the filesystem MCP server globally via npm.

```shell
npm install -g @modelcontextprotocol/server-filesystem
```

--------------------------------

### Start vLLM server

Source: https://lobehub.com/docs/usage/providers/vllm

Command to launch the vLLM server with a specific model.

```shell
vllm serve Qwen/Qwen2.5-1.5B-Instruct
```

--------------------------------

### Start Desktop App Development

Source: https://lobehub.com/docs/development/basic/setup-development

Commands to initiate the development environment for the Electron desktop application.

```shell
cd apps/desktop
pnpm run dev
```

--------------------------------

### Configure Migration Environment Variables

Source: https://lobehub.com/docs/self-hosting/migration/v2/auth/clerk-to-betterauth

Example .env configuration for defining migration modes, database URLs, and Clerk API keys.

```shell
# ============================================
# Migration mode: test or prod
# Recommended: Start with test mode to verify on a test database,
# then switch to prod after confirming everything works
# ============================================
CLERK_TO_BETTERAUTH_MODE=test

# ============================================
# Database connection (uses corresponding variable based on mode)
# TEST_ prefix for test environment, PROD_ prefix for production
# ============================================
TEST_CLERK_TO_BETTERAUTH_DATABASE_URL=postgresql://user:pass@test-host:5432/testdb
PROD_CLERK_TO_BETTERAUTH_DATABASE_URL=postgresql://user:pass@prod-host:5432/proddb

# ============================================
# Clerk API keys (for exporting user data via API)
# Get from Clerk Dashboard: Configure → Developers → API Keys
# ============================================
TEST_CLERK_TO_BETTERAUTH_CLERK_SECRET_KEY=sk_test_xxx
PROD_CLERK_TO_BETTERAUTH_CLERK_SECRET_KEY=sk_live_xxx

# ============================================
# Database driver (optional)
# neon: Neon serverless driver (default)
# node: node-postgres driver
# ============================================
CLERK_TO_BETTERAUTH_DATABASE_DRIVER=neon

# ============================================
# Dry Run mode (optional)
# Set to 1 to only print logs without modifying the database
# Recommended: Enable for first run, disable after verification
# ============================================
CLERK_TO_BETTERAUTH_DRY_RUN=1
```

--------------------------------

### Install Comfy-Manager via Script

Source: https://lobehub.com/docs/usage/providers/comfyui

Execute the installation script directly from the ComfyUI root directory.

```shell
# Run from the ComfyUI root directory
curl -fsSL https://raw.githubusercontent.com/ltdrdata/ComfyUI-Manager/main/install.sh | bash
```

--------------------------------

### Install vLLM with conda

Source: https://lobehub.com/docs/usage/providers/vllm

Commands to create a conda environment and install vLLM via pip.

```shell
conda create -n myenv python=3.12 -y
conda activate myenv
pip install vllm
```

--------------------------------

### Configure Straico API Key

Source: https://lobehub.com/docs/self-hosting/environment-variables/model-provider

Example value for the required Straico API key.

```text
sk-xxxxxx...xxxxxx
```

--------------------------------

### Create Feature Branches

Source: https://lobehub.com/docs/development/basic/contributing-guidelines

Examples of branch naming conventions following the username/type/description format.

```shell
git checkout -b feat/add-voice-input
git checkout -b fix/message-duplication
git checkout -b docs/update-api-guide
```

--------------------------------

### Launch Vitest UI

Source: https://lobehub.com/docs/development/basic/test

Starts the interactive test explorer in the browser.

```bash
bunx vitest --ui
```

--------------------------------

### Define settings in JSON format

Source: https://lobehub.com/docs/self-hosting/advanced/settings-url-share

Example structure for the settings object to be passed in the URL.

```json
{
  "keyVaults": {
    "openai": {
      "apiKey": "user-key"
    }
  }
}
```

--------------------------------

### Start Mobile SPA Development

Source: https://lobehub.com/docs/development/basic/setup-development

Command to launch the mobile web application development server.

```shell
bun run dev:spa:mobile
```

--------------------------------

### Run Specific Feature Tests

Source: https://lobehub.com/docs/development/basic/feature-development

Example command to run tests for a specific store selector file.

```shell
bunx vitest run --silent='passed-only' 'src/store/agent/selectors/selectors.test.ts'
```

--------------------------------

### Configure Basic Authentication

Source: https://lobehub.com/docs/usage/providers/comfyui

Setup steps for Basic Auth, including generating credentials and configuring LobeHub.

```shell
# Install apache2-utils
sudo apt-get install apache2-utils

# Create user 'admin'
sudo htpasswd -c /etc/nginx/.htpasswd admin
```

```yaml
Authentication Type: Basic
Server Address: https://your-domain.com
Username: admin
Password: your_secure_password
```

--------------------------------

### Start ComfyUI in Debug Mode

Source: https://lobehub.com/docs/development/basic/comfyui-development

Use this command to initiate the development server with debug logging enabled.

```shell
# Start ComfyUI debug mode
DEBUG=lobe-image:* pnpm dev
```

--------------------------------

### Configure SSRF Protection Environment Variables

Source: https://lobehub.com/docs/self-hosting/environment-variables/basic

Examples for configuring SSRF protection settings in a shell environment.

```shell
# Scenario 1: Public deployment (recommended)
# Block all private IP addresses for security
SSRF_ALLOW_PRIVATE_IP_ADDRESS=0

# Scenario 2: Internal deployment
# Allow all private IP addresses to access internal image servers
SSRF_ALLOW_PRIVATE_IP_ADDRESS=1

# Scenario 3: Hybrid deployment (most common)
# Block private IPs by default, but allow specific trusted internal servers
SSRF_ALLOW_PRIVATE_IP_ADDRESS=0
SSRF_ALLOW_IP_ADDRESS_LIST=192.168.1.100,10.0.0.50
```

--------------------------------

### Configure MCP Servers for Self-Hosted Deployments

Source: https://lobehub.com/docs/usage/community/mcp-market

Examples for defining MCP server connections using either local stdio processes or remote HTTP services.

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"],
      "type": "stdio"
    }
  }
}
```

```json
{
  "mcpServers": {
    "github": {
      "url": "https://mcp-server-github.example.com",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      }
    }
  }
}
```

--------------------------------

### Start LobeHub Container

Source: https://lobehub.com/docs/self-hosting/platform/docker

Command to launch the LobeHub application container using the previously created network and environment file.

```shell
docker run -it -d -p 3210:3210 --network pg --env-file lobehub.env --name lobehub lobehub/lobehub
```

--------------------------------

### Install Codex CLI

Source: https://lobehub.com/docs/usage/agent/codex

Installation commands for the Codex CLI via npm or Homebrew. Ensure the command is available on your PATH after installation.

```bash
npm install -g @openai/codex
```

```bash
brew install --cask codex
```

--------------------------------

### Start Docker Containers

Source: https://lobehub.com/docs/self-hosting/platform/docker-compose

Starts the LobeHub services in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Create Deployment Directory

Source: https://lobehub.com/docs/self-hosting/platform/docker-compose

Initializes the directory for storing configuration and database files.

```bash
mkdir lobehub && cd lobehub
```

--------------------------------

### Successful Startup Log Output

Source: https://lobehub.com/docs/self-hosting/platform/docker

Expected log output indicating that database migration passed and the Next.js server is ready.

```text
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        http://localhost:3210
  - Network:      http://0.0.0.0:3210

 ✓ Starting...
 ✓ Ready in 95ms
```

--------------------------------

### Install Comfy-Manager Manually

Source: https://lobehub.com/docs/usage/providers/comfyui

Use git to clone the Comfy-Manager repository into the custom_nodes directory of your ComfyUI installation.

```shell
# Navigate to ComfyUI's custom_nodes directory
cd ComfyUI/custom_nodes

# Clone the Comfy-Manager repository
git clone https://github.com/ltdrdata/ComfyUI-Manager.git

# Restart the ComfyUI server
# After restarting, you should see a "Manager" button in the UI
```

--------------------------------

### Verify Startup Logs

Source: https://lobehub.com/docs/self-hosting/platform/docker-compose

Expected output indicating successful service migration and startup.

```text
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        http://localhost:3210
  - Network:      http://0.0.0.0:3210

 ✓ Starting...
 ✓ Ready in 95ms
```

```text
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        http://your_server_ip:3210
  - Network:      http://0.0.0.0:3210
 ✓ Starting...
 ✓ Ready in 95ms
```

--------------------------------

### Install Claude Code CLI

Source: https://lobehub.com/docs/usage/agent/claude-code

Installation commands for the Claude Code CLI via shell script or Homebrew.

```shell
curl -fsSL https://claude.ai/install.sh | bash
```

```shell
brew install --cask claude-code
```

--------------------------------

### Run database migrations

Source: https://lobehub.com/docs/development/basic/setup-development

Execute the migration script to initialize the database schema.

```shell
pnpm db:migrate
```

--------------------------------

### Low Complexity Store Structure

Source: https://lobehub.com/docs/development/state-management/state-management-intro

Recommended structure for projects with 2-5 states and 3-4 actions.

```Shell
DataFill/store
├── index.ts
└── initialState.ts
```

--------------------------------

### Read Documentation via Agent

Source: https://lobehub.com/docs/usage/providers/ollama/qwen

Use this prompt to instruct an agent to read the documentation page for the Qwen model integration.

```text
Read https://lobehub.com/docs/usage/providers/ollama/qwen
```

--------------------------------

### Configure S3 Endpoint

Source: https://lobehub.com/docs/self-hosting/platform/docker-compose

Example configuration for the S3 endpoint environment variable.

```plaintext
S3_ENDPOINT=https://s3.example.com
```

--------------------------------

### Configure LobeComfyUI Authentication

Source: https://lobehub.com/docs/development/basic/comfyui-development

Examples for initializing LobeComfyUI with different authentication strategies.

```TypeScript
// No authentication
const comfyUI = new LobeComfyUI({
  baseURL: 'http://localhost:8000',
  authType: 'none'
});

// Basic authentication
const comfyUI = new LobeComfyUI({
  baseURL: 'https://your-comfyui-server.com',
  authType: 'basic',
  username: 'your-username',
  password: 'your-password'
});

// Bearer Token
const comfyUI = new LobeComfyUI({
  baseURL: 'https://your-comfyui-server.com',
  authType: 'bearer',
  apiKey: 'your-api-key'
});

// Custom headers
const comfyUI = new LobeComfyUI({
  baseURL: 'https://your-comfyui-server.com',
  authType: 'custom',
  customHeaders: {
    'X-API-Key': 'your-custom-key',
    'Authorization': 'Custom your-token'
  }
});
```

--------------------------------

### Read documentation via agent prompt

Source: https://lobehub.com/docs/usage/providers/qiniu

Use this prompt to instruct an AI agent to read the Qiniu Cloud integration documentation.

```text
Read https://lobehub.com/docs/usage/providers/qiniu
```

--------------------------------

### Read documentation via agent prompt

Source: https://lobehub.com/docs/usage/providers/groq

Use this prompt to instruct an agent to read the Groq integration documentation.

```text
Read https://lobehub.com/docs/usage/providers/groq
```

--------------------------------

### Instruct Agent to Read Documentation

Source: https://lobehub.com/docs/usage/agent/sandbox

Use this prompt to allow an agent to access and understand the cloud sandbox documentation.

```text
Read https://lobehub.com/docs/usage/agent/sandbox
```

--------------------------------

### Troubleshoot service status

Source: https://lobehub.com/docs/self-hosting/platform/docker-compose

Commands to inspect service status and logs when containers fail to start.

```shell
docker compose ps
docker compose logs [service-name]
```

--------------------------------

### Create Postgres Database Instance

Source: https://lobehub.com/docs/self-hosting/platform/docker

Initializes a Docker network and a ParadeDB container with necessary extensions for RAG and search functionality.

```shell
docker network create pg

docker run --name my-postgres --network pg -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d paradedb/paradedb:latest-pg17 -c shared_preload_libraries=pg_search
```

--------------------------------

### Restart LobeHub Container

Source: https://lobehub.com/docs/self-hosting/advanced/upstream-sync

Command to start a new LobeHub container with specific environment variables.

```fish
docker run -d -p 3210:3210 \
  -e OPENAI_API_KEY=sk-xxxx \
  -e OPENAI_PROXY_URL=https://api-proxy.com/v1 \
  --name lobehub \
  lobehub/lobehub
```

--------------------------------

### Configure SSO Environment Variables

Source: https://lobehub.com/docs/development/basic/add-new-authentication-providers

Enable the provider and set required credentials in the environment configuration.

```Shell
AUTH_SSO_PROVIDERS=google,github,gitlab
AUTH_GITLAB_ID=your-client-id
AUTH_GITLAB_SECRET=your-client-secret
AUTH_GITLAB_ISSUER=https://gitlab.example.com
```

--------------------------------

### Clean Slate Model Configuration

Source: https://lobehub.com/docs/self-hosting/advanced/model-list

Use -all to hide default models and explicitly add only the desired ones.

```Shell
OPENAI_MODEL_LIST=-all,+gpt-4o,+gpt-4o-mini
```

--------------------------------

### Agent Tool Invocation Example

Source: https://lobehub.com/docs/usage/community/mcp-market

A conceptual representation of an agent interacting with the filesystem MCP tool.

```plaintext
You: Search my project files for the authentication code

Agent: I'll search your files now.
       [Uses filesystem MCP — executes search tool]

Agent: I found authentication-related code in src/auth/login.ts and
       src/middleware/auth.ts. Here's what I found...
```

--------------------------------

### Generate Images with LobeComfyUI

Source: https://lobehub.com/docs/development/basic/comfyui-development

Examples for generating images using different models and optimization settings.

```typescript
import { LobeComfyUI } from '@lobechat/model-runtime';

const comfyUI = new LobeComfyUI({
  baseURL: 'http://localhost:8000',
  authType: 'none'
});

// FLUX Dev model generation
const result = await comfyUI.createImage({
  model: 'flux-dev',
  params: {
    prompt: 'Beautiful landscape painting, high quality, detailed',
    width: 1024,
    height: 1024,
    steps: 20,
    cfg: 3.5,
    seed: -1
  }
});

console.log('Generated image URL:', result.imageUrl);
```

```typescript
// SD3.5 automatically detects available encoders
const sd35Result = await comfyUI.createImage({
  model: 'stable-diffusion-35',
  params: {
    prompt: 'Futuristic cityscape',
    width: 1344,
    height: 768,
    steps: 28,
    cfg: 4.5
  }
});
```

```typescript
// System automatically selects best available variant (e.g., FP8 quantized)
const optimizedResult = await comfyUI.createImage({
  model: 'flux-dev',
  params: {
    prompt: 'Professional business portrait',
    width: 768,
    height: 1024,
    steps: 15  // FP8 models can use fewer steps
  }
});
```

--------------------------------

### Moderate Complexity Store Structure

Source: https://lobehub.com/docs/development/state-management/state-management-intro

Recommended structure for projects with 5-15 states and 5-10 actions, including selectors and reducers.

```Shell
IconPicker/store
├── index.ts
├── initialState.ts
├── selectors.ts
└── store.ts
```

```Shell
SortableList/store
├── index.ts
├── initialState.ts
├── listDataReducer.ts
└── store.ts
```

--------------------------------

### Add New Components

Source: https://lobehub.com/docs/development/basic/comfyui-development

Examples for registering new LoRA or ControlNet components into the system configuration.

```TypeScript
// Add new LoRA
'your-custom-lora.safetensors': {
  compatibleVariants: ['dev', 'schnell'],
  modelFamily: 'FLUX',
  priority: 2,
  type: 'lora',
},

// Add new ControlNet
'your-controlnet-pose.safetensors': {
  compatibleVariants: ['dev'],
  controlnetType: 'pose',
  modelFamily: 'FLUX',
  priority: 2,
  type: 'controlnet',
},
```

--------------------------------

### LobeHub Environment Configuration

Source: https://lobehub.com/docs/self-hosting/advanced/upstream-sync

Example content for a lobe.env file containing necessary environment variables.

```plaintext
OPENAI_API_KEY=sk-xxxx
OPENAI_PROXY_URL=https://api-proxy.com/v1
OPENAI_MODEL_LIST=-gpt-4,-gpt-4-32k,-gpt-3.5-turbo-16k,gpt-3.5-turbo-1106=gpt-3.5-turbo-16k,gpt-4.1=gpt-4-turbo,gpt-4o=gpt-4-vision
```

--------------------------------

### Commit with Gitmoji

Source: https://lobehub.com/docs/development/basic/contributing-guidelines

Examples of commit messages using gitmoji prefixes to indicate the type of change.

```shell
git commit -m "✨ feat: add voice input support"
git commit -m "🐛 fix: resolve message duplication in group chat"
git commit -m "📝 docs: update installation guide"
```

--------------------------------

### Configure Security and Authentication Keys

Source: https://lobehub.com/docs/self-hosting/platform/dokploy

Environment variables for encryption and authentication. Values should be generated via the provided UI buttons.

```shell
KEY_VAULTS_SECRET='Click button to generate'
```

```shell
AUTH_SECRET='Click button to generate'
```

```shell
JWKS_KEY='Click button to generate'
```

--------------------------------

### Define Task Content Prompt

Source: https://lobehub.com/docs/usage/agent/scheduled-task

Example of a structured prompt for an Agent to perform a recurring analysis task.

```plaintext
Analyze today's top tech news and summarize:
1. Major product launches
2. Funding announcements
3. Industry trends
Format as a brief executive summary.
```

--------------------------------

### Read documentation via agent prompt

Source: https://lobehub.com/docs/usage/providers/openai

Use this prompt to instruct an AI agent to read the OpenAI provider documentation.

```text
Read https://lobehub.com/docs/usage/providers/openai
```

--------------------------------

### Identify UNABLE_TO_VERIFY_LEAF_SIGNATURE Error

Source: https://lobehub.com/docs/self-hosting/faq/proxy-with-unable-to-verify-leaf-signature

Examples of the error output encountered when Node.js fails to verify proxy certificates.

```shell
[TypeError: fetch failed] {
  cause: [Error: unable to verify the first certificate] {
    code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
  }
}
```

```json
{
  "endpoint": "https://api.openai.com/v1",
  "error": {
    "cause": {
      "code": "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
    }
  }
}
```

--------------------------------

### Read SambaNova documentation prompt

Source: https://lobehub.com/docs/usage/providers/sambanova

Use this prompt to instruct an agent to read the SambaNova integration documentation.

```text
Read https://lobehub.com/docs/usage/providers/sambanova
```

--------------------------------

### Read xAI documentation via agent prompt

Source: https://lobehub.com/docs/usage/providers/xai

Use this prompt to instruct an agent to read the xAI integration documentation.

```text
Read https://lobehub.com/docs/usage/providers/xai
```

--------------------------------

### Read Documentation Prompt

Source: https://lobehub.com/docs/self-hosting/auth/providers/authelia

A prompt optimized for agents to read the Authelia configuration documentation.

```text
Read https://lobehub.com/docs/self-hosting/auth/providers/authelia
```
Tokens:
Raw