# 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