# LobeChat AI Assistant

## Overview

[LobeChat](https://github.com/lobehub/lobe-chat) is a modern, open-source AI chat framework with 55K+ GitHub stars, known for its polished UI and extensive feature set. It supports virtually every major LLM provider — OpenAI, Anthropic Claude, Google Gemini, Mistral, and local models via Ollama — all from a single, self-hosted interface.

**Why run LobeChat on Clore.ai?**

* **No GPU required** — LobeChat itself is a lightweight web app. Clore.ai CPU-only or minimal-GPU instances are perfectly sufficient for the interface.
* **Pair with local LLMs** — Spin up Ollama or vLLM on the same Clore.ai server and point LobeChat at it for fully local, private inference.
* **Affordable hosting** — A basic Clore.ai instance costs a fraction of traditional VPS providers, and you can shut it down when not in use.
* **Full data ownership** — Database mode stores all conversations, files, and embeddings in your own PostgreSQL instance on the server.

LobeChat operates in two distinct modes:

| Mode           | Description                                         | Best For                                  |
| -------------- | --------------------------------------------------- | ----------------------------------------- |
| **Standalone** | Single Docker container, settings stored in browser | Quick testing, personal use               |
| **Database**   | Full stack (PostgreSQL + MinIO + Auth + App)        | Teams, persistent history, knowledge base |

***

## Requirements

### Server Specifications

| Component   | Minimum       | Recommended                      | Notes                                    |
| ----------- | ------------- | -------------------------------- | ---------------------------------------- |
| **GPU**     | None required | RTX 3090 (if running local LLMs) | Only needed for Ollama/vLLM backend      |
| **VRAM**    | —             | 24 GB (RTX 3090)                 | For local model inference                |
| **CPU**     | 2 vCPU        | 4+ vCPU                          | LobeChat itself is lightweight           |
| **RAM**     | 2 GB          | 8 GB                             | 4+ GB if using database mode             |
| **Storage** | 10 GB         | 50+ GB                           | More if storing uploaded files or models |

### Clore.ai Pricing Reference

| Server Type           | Approx. Cost    | Use Case                          |
| --------------------- | --------------- | --------------------------------- |
| CPU-only instance     | \~$0.05–0.10/hr | Standalone LobeChat only          |
| RTX 3090 (24 GB VRAM) | \~$0.20/hr      | LobeChat + Ollama local LLMs      |
| RTX 4090 (24 GB VRAM) | \~$0.35/hr      | LobeChat + faster local inference |
| A100 80 GB            | \~$1.10/hr      | LobeChat + large models (70B+)    |

> 💡 **Tip:** For API-only use (connecting to OpenAI, Anthropic, etc.), any small instance works. A GPU server only makes sense if you want to also run local LLMs. See [GPU Comparison Guide](https://docs.clore.ai/guides/getting-started/gpu-comparison) for details.

### Prerequisites

* Clore.ai account with a deployed server
* SSH access to your server
* Docker and Docker Compose (pre-installed on Clore.ai servers)
* NVIDIA drivers (pre-installed; only relevant if using local LLM backend)
* At least one API key (OpenAI, Anthropic, etc.) **or** a local Ollama instance

***

## Quick Start

### Option A: Standalone Mode (Recommended for Getting Started)

Standalone mode runs LobeChat as a single container. Settings and conversation history are stored in the browser's local storage — no database required.

**Step 1: Connect to your Clore.ai server**

```bash
ssh root@<your-clore-server-ip> -p <ssh-port>
```

**Step 2: Pull and run LobeChat**

```bash
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OPENAI_API_KEY=sk-your-openai-key-here \
  -e OPENAI_PROXY_URL=https://api.openai.com/v1 \
  lobehub/lobe-chat
```

**Step 3: Verify it's running**

```bash
docker ps
docker logs lobechat --tail 20
```

**Step 4: Access the interface**

Open your browser and navigate to:

```
http://<your-clore-server-ip>:3210
```

> ⚠️ **Security Note:** Clore.ai servers are publicly accessible. Consider setting `ACCESS_CODE` to password-protect your instance (see Configuration section below).

***

### Option B: Standalone with Multiple Providers

Pass multiple API keys to support different providers simultaneously:

```bash
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OPENAI_API_KEY=sk-your-openai-key \
  -e ANTHROPIC_API_KEY=sk-ant-your-anthropic-key \
  -e GOOGLE_API_KEY=your-google-gemini-key \
  -e MISTRAL_API_KEY=your-mistral-key \
  -e ACCESS_CODE=your-secret-password \
  lobehub/lobe-chat
```

***

### Option C: With Local Ollama Backend

If you have Ollama running on the same Clore.ai server (see [Ollama Guide](https://docs.clore.ai/guides/language-models/ollama)):

```bash
# First, start Ollama
docker run -d \
  --name ollama \
  --restart unless-stopped \
  --gpus all \
  -p 11434:11434 \
  -v ollama:/root/.ollama \
  ollama/ollama

# Pull a model
docker exec ollama ollama pull llama3.2

# Start LobeChat pointing to Ollama
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OLLAMA_PROXY_URL=http://host-gateway:11434 \
  --add-host=host-gateway:host-gateway \
  lobehub/lobe-chat
```

> On Linux, replace `host-gateway` with the actual Docker bridge IP, typically `172.17.0.1`:
>
> ```bash
> -e OLLAMA_PROXY_URL=http://172.17.0.1:11434
> ```

***

### Option D: Database Mode (Docker Compose)

Database mode enables persistent conversation history, multi-user support, file uploads to S3-compatible storage, and a full knowledge base.

**Step 1: Create project directory**

```bash
mkdir -p ~/lobechat && cd ~/lobechat
```

**Step 2: Create `docker-compose.yml`**

```bash
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  postgresql:
    image: pgvector/pgvector:pg16
    container_name: lobe-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: lobechat
      POSTGRES_USER: lobechat
      POSTGRES_PASSWORD: changeme_strong_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U lobechat -d lobechat"]
      interval: 10s
      timeout: 5s
      retries: 5

  minio:
    image: minio/minio
    container_name: lobe-minio
    restart: unless-stopped
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: changeme_minio_password
    command: server /data --console-address ":9001"
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"

  lobechat:
    image: lobehub/lobe-chat-database
    container_name: lobe-chat
    restart: unless-stopped
    depends_on:
      postgresql:
        condition: service_healthy
    ports:
      - "3210:3210"
    environment:
      # Database
      DATABASE_URL: postgresql://lobechat:changeme_strong_password@postgresql:5432/lobechat
      # S3 Storage (MinIO)
      S3_ENDPOINT: http://minio:9000
      S3_BUCKET: lobechat
      S3_ACCESS_KEY_ID: minioadmin
      S3_SECRET_ACCESS_KEY: changeme_minio_password
      S3_PUBLIC_DOMAIN: http://<your-server-ip>:9000
      # Auth (NextAuth)
      NEXTAUTH_SECRET: your-random-32-char-secret-here
      NEXTAUTH_URL: http://<your-server-ip>:3210
      # LLM Providers
      OPENAI_API_KEY: sk-your-openai-key
      ANTHROPIC_API_KEY: sk-ant-your-key
      # App
      APP_URL: http://<your-server-ip>:3210

volumes:
  postgres_data:
  minio_data:
EOF
```

**Step 3: Start the stack**

```bash
docker compose up -d
docker compose logs -f lobechat
```

**Step 4: Create MinIO bucket**

```bash
# Install MinIO client
docker exec lobe-minio mc alias set local http://localhost:9000 minioadmin changeme_minio_password
docker exec lobe-minio mc mb local/lobechat
docker exec lobe-minio mc anonymous set download local/lobechat
```

***

## Configuration

### Environment Variables Reference

| Variable               | Description                                | Default                     |
| ---------------------- | ------------------------------------------ | --------------------------- |
| `OPENAI_API_KEY`       | OpenAI API key                             | —                           |
| `OPENAI_PROXY_URL`     | Custom OpenAI-compatible endpoint          | `https://api.openai.com/v1` |
| `ANTHROPIC_API_KEY`    | Anthropic Claude API key                   | —                           |
| `GOOGLE_API_KEY`       | Google Gemini API key                      | —                           |
| `MISTRAL_API_KEY`      | Mistral AI API key                         | —                           |
| `OLLAMA_PROXY_URL`     | URL to local Ollama instance               | —                           |
| `ACCESS_CODE`          | Password to protect the interface          | —                           |
| `DEFAULT_AGENT_CONFIG` | JSON config for default assistant behavior | —                           |
| `FEATURE_FLAGS`        | Enable/disable specific features           | —                           |

### Enabling Specific Features

**Enable web search plugin:**

```bash
-e BING_API_KEY=your-bing-search-key
```

**Enable text-to-speech:**

```bash
-e AZURE_TTS_API_KEY=your-azure-key \
-e AZURE_TTS_REGION=eastus
```

**Set custom system prompt for default agent:**

```bash
-e DEFAULT_AGENT_CONFIG='{"systemRole":"You are a helpful assistant."}'
```

### Updating LobeChat

```bash
# Pull latest image
docker pull lobehub/lobe-chat

# Stop and remove old container
docker stop lobechat && docker rm lobechat

# Start new container with same parameters
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OPENAI_API_KEY=sk-your-key \
  lobehub/lobe-chat
```

For Docker Compose:

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

***

## GPU Acceleration

LobeChat itself does **not** require GPU. However, when paired with a GPU-accelerated backend on Clore.ai, you get local, private LLM inference:

### Pairing with vLLM (High-Performance Inference)

See the [vLLM Guide](https://docs.clore.ai/guides/language-models/vllm) for full setup. Quick integration:

```bash
# Start vLLM server (on same host)
docker run -d \
  --name vllm \
  --gpus all \
  --restart unless-stopped \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --served-model-name llama3.1-8b

# Start LobeChat pointing to vLLM (OpenAI-compatible API)
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OPENAI_API_KEY=not-needed \
  -e OPENAI_PROXY_URL=http://172.17.0.1:8000/v1 \
  lobehub/lobe-chat
```

### Resource Usage

| Backend               | GPU VRAM Used | Approximate Throughput        |
| --------------------- | ------------- | ----------------------------- |
| Ollama (Llama 3.2 3B) | \~2 GB        | 50–80 tokens/sec on 3090      |
| Ollama (Llama 3.1 8B) | \~6 GB        | 40–60 tokens/sec on 3090      |
| vLLM (Llama 3.1 8B)   | \~16 GB       | 80–150 tokens/sec on 3090     |
| vLLM (Llama 3.1 70B)  | \~80 GB       | 20–40 tokens/sec on A100 80GB |

***

## Tips & Best Practices

### Cost Optimization

* **Stop your server when idle.** Clore.ai charges by the hour — use the dashboard to pause instances you're not actively using.
* **Standalone mode for personal use.** Unless you need multi-user support or persistent server-side history, standalone mode avoids the overhead of PostgreSQL and MinIO.
* **Use API providers for large models.** Routing Claude or GPT-4 requests through external APIs is cheaper than renting an H100 for occasional queries.

### Security

```bash
# Always set an access code on public Clore.ai IPs
-e ACCESS_CODE=your-strong-password-here

# Restrict to specific origin (optional)
-e NEXT_PUBLIC_SERVICE_MODE=server
```

* Never expose LobeChat without an `ACCESS_CODE` on a public IP.
* Consider using Nginx reverse proxy with HTTPS if running long-term.
* Rotate API keys if you suspect exposure.

### Performance

```bash
# Increase Node.js heap if running database mode with many users
-e NODE_OPTIONS="--max-old-space-size=4096"
```

* For database mode with 10+ concurrent users, ensure at least 8 GB RAM on the host.
* MinIO performs better with SSD-backed storage (Clore.ai NVMe instances).

### Persistence Between Clore.ai Sessions

Since Clore.ai servers can be terminated:

```bash
# Create a Docker volume for standalone conversation exports
docker run -d \
  --name lobechat \
  -p 3210:3210 \
  -v lobechat_data:/app/data \
  lobehub/lobe-chat
```

Regularly export conversations from Settings → Data Export in the UI.

***

## Troubleshooting

### Container fails to start

```bash
# Check logs
docker logs lobechat --tail 50

# Verify port is not in use
ss -tlnp | grep 3210

# Check Docker daemon is running
systemctl status docker
```

### Cannot connect to Ollama from LobeChat

```bash
# Test connectivity from LobeChat container
docker exec lobechat curl -s http://172.17.0.1:11434/api/tags

# If that fails, check Ollama is listening on all interfaces
docker exec ollama ollama serve --host 0.0.0.0
```

### Database connection errors (database mode)

```bash
# Check PostgreSQL health
docker exec lobe-postgres pg_isready -U lobechat

# Verify DATABASE_URL format
# postgresql://user:password@host:port/dbname

# Run migrations manually if needed
docker exec lobe-chat npx prisma migrate deploy
```

### Images/files not uploading (database mode)

```bash
# Check MinIO is accessible
curl -s http://localhost:9000/minio/health/live

# Verify bucket exists
docker exec lobe-minio mc ls local/

# Check S3_PUBLIC_DOMAIN is set to the correct server IP
```

### Out of memory errors

```bash
# Check current memory usage
docker stats lobechat

# Increase container memory limit
docker run -d \
  --name lobechat \
  --memory=2g \
  -p 3210:3210 \
  lobehub/lobe-chat
```

***

## Further Reading

* [LobeChat Documentation](https://lobehub.com/docs) — official docs, plugin development, deployment guides
* [LobeChat GitHub](https://github.com/lobehub/lobe-chat) — source code, issues, discussions
* [Running Ollama on Clore.ai](https://docs.clore.ai/guides/language-models/ollama) — local LLM backend for LobeChat
* [Running vLLM on Clore.ai](https://docs.clore.ai/guides/language-models/vllm) — high-performance OpenAI-compatible inference
* [GPU Comparison Guide](https://docs.clore.ai/guides/getting-started/gpu-comparison) — choosing the right Clore.ai GPU
* [LobeChat Docker Hub](https://hub.docker.com/r/lobehub/lobe-chat) — image tags and versions
* [LobeChat Environment Variables](https://lobehub.com/docs/self-hosting/environment-variables) — full variable reference


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/ai-platforms-and-agents/lobechat.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.