# AnythingLLM User Guide

AnythingLLM by Mintplex Labs is an all-in-one, self-hosted AI application. You bring your own LLM — local or cloud — drop in your documents, and get a private ChatGPT-style interface with workspaces, retrieval-augmented generation (RAG), built-in agents, voice, mobile access, web-embed widgets, and a full developer API, all running on a single Docker container or as a desktop app.

This guide covers everything you need to install, configure, and use AnythingLLM as an everyday user. If you are an administrator, developer, or architect, see the **Admin Guide** for architecture, the full environment variable reference, deployment patterns, security hardening, and internals.

---

## 1. Quick Start

Get from zero to chatting with your documents in under five minutes.

**What AnythingLLM does:**

- Private, self-hosted AI chat with RAG — your documents never leave your machine
- Supports 35+ LLM providers, 10+ vector databases, 14 embedding engines, and 5 TTS providers
- Agents that browse the web, query databases, read files, send email, and more
- Embeddable chat widgets for your website, a Telegram bot, mobile app, and browser extension

**Prerequisites:**

- Docker installed (or Node.js 18+ for bare-metal)
- At least one LLM provider ready (an Ollama install, an OpenAI API key, etc.)

**One-command Docker start (Linux / macOS):**

```bash
export STORAGE_LOCATION=$HOME/anythingllm && \
mkdir -p $STORAGE_LOCATION && \
touch "$STORAGE_LOCATION/.env" && \
docker run -d -p 3001:3001 \
  --cap-add SYS_ADMIN \
  -v ${STORAGE_LOCATION}:/app/server/storage \
  -v ${STORAGE_LOCATION}/.env:/app/server/.env \
  -e STORAGE_DIR="/app/server/storage" \
  mintplexlabs/anythingllm
```

Open **http://localhost:3001**, walk through the onboarding wizard, create a workspace, drag in a PDF, and ask a question. Citations appear under every answer so you can verify the source.

> [!TIP]
> If you already have Ollama running locally, select it during onboarding and point the base URL at `http://host.docker.internal:11434` — no API key needed, fully private.

**What to try next:**

- Upload more documents and experiment with chat vs. query mode
- Enable an agent skill like web-scraping and prefix a message with `@agent`
- Create an embed widget and drop it on a test page
- Connect the mobile app via QR code pairing

---

## 2. Installation

AnythingLLM ships in multiple forms. Docker is the recommended path for most users.

### System requirements

| Requirement | Minimum | Recommended |
|---|---|---|
| **Runtime** | Docker 20+ or Node.js 18+ | Docker 24+ |
| **RAM** | 2 GB | 4 GB+ (8 GB+ if running a local LLM alongside) |
| **Disk** | 500 MB for app | 10 GB+ (vector DB and documents grow over time) |
| **CPU** | Any x86_64 or ARM64 | Multi-core for concurrent embedding |
| **OS** | Linux, macOS, Windows (Docker Desktop or WSL2) | Linux |
| **Browser** | Chrome, Edge, Firefox, Safari (latest two versions) | Chrome or Edge |

### Option 1 — Docker (recommended)

Pull the official image:

```bash
docker pull mintplexlabs/anythingllm
```

The image supports both `amd64` and `arm64` architectures.

**Linux / macOS:**

```bash
export STORAGE_LOCATION=$HOME/anythingllm && \
mkdir -p $STORAGE_LOCATION && \
touch "$STORAGE_LOCATION/.env" && \
docker run -d -p 3001:3001 \
  --cap-add SYS_ADMIN \
  -v ${STORAGE_LOCATION}:/app/server/storage \
  -v ${STORAGE_LOCATION}/.env:/app/server/.env \
  -e STORAGE_DIR="/app/server/storage" \
  mintplexlabs/anythingllm
```

**Windows PowerShell:**

```powershell
$env:STORAGE_LOCATION="$HOME\Documents\anythingllm"
If(!(Test-Path $env:STORAGE_LOCATION)) {New-Item $env:STORAGE_LOCATION -ItemType Directory}
If(!(Test-Path "$env:STORAGE_LOCATION\.env")) {New-Item "$env:STORAGE_LOCATION\.env" -ItemType File}
docker run -d -p 3001:3001 `
  --cap-add SYS_ADMIN `
  -v "$env:STORAGE_LOCATION`:/app/server/storage" `
  -v "$env:STORAGE_LOCATION\.env:/app/server/.env" `
  -e STORAGE_DIR="/app/server/storage" `
  mintplexlabs/anythingllm
```

> [!IMPORTANT]
> The `--cap-add SYS_ADMIN` flag is required. AnythingLLM uses Puppeteer (headless Chromium) for the web-scraping agent skill, which needs kernel capabilities that a default Docker container does not grant.

Verify:

```bash
docker ps --filter name=anythingllm
```

```text
CONTAINER ID   IMAGE                       STATUS         PORTS
a1b2c3d4e5f6   mintplexlabs/anythingllm    Up 2 minutes   0.0.0.0:3001->3001/tcp
```

Open **http://localhost:3001** to begin onboarding.

> [!WARNING]
> **Always mount a host volume for storage.** Without `-v`, your chats, vector database, uploaded documents, and all settings are lost when the container is recreated.

### Option 2 — Docker Compose

Create a `docker-compose.yml`:

```yaml
version: '3.8'
services:
  anythingllm:
    image: mintplexlabs/anythingllm
    container_name: anythingllm
    ports:
      - "3001:3001"
    cap_add:
      - SYS_ADMIN
    environment:
      - STORAGE_DIR=/app/server/storage
      - JWT_SECRET=make-this-a-long-random-string-of-at-least-12-characters
      - LLM_PROVIDER=ollama
      - OLLAMA_BASE_PATH=http://host.docker.internal:11434
      - OLLAMA_MODEL_PREF=llama3
      - OLLAMA_MODEL_TOKEN_LIMIT=4096
      - EMBEDDING_ENGINE=native
      - VECTOR_DB=lancedb
    volumes:
      - anythingllm_storage:/app/server/storage
    restart: always

volumes:
  anythingllm_storage:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/on/local/disk
```

Then start:

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

### Option 3 — Bare metal (advanced)

Bare-metal installs are not officially supported but work well for development and customization:

1. Install **Node.js 18+** and **Yarn**.
2. Clone the repository:
   ```bash
   git clone https://github.com/Mintplex-Labs/anything-llm.git && cd anything-llm
   ```
3. Run the all-in-one setup:
   ```bash
   yarn setup
   ```
   This installs dependencies for `server/`, `collector/`, and `frontend/`, copies `.env.example` files, and runs Prisma migrations.
4. Edit `server/.env` and set at minimum:
   ```text
   STORAGE_DIR=/absolute/path/to/server/storage
   ```
5. Edit `frontend/.env` so `VITE_API_BASE='/api'`.
6. Build the frontend and copy it into the server:
   ```bash
   cd frontend && yarn build && cp -R dist ../server/public
   ```
7. Run Prisma setup:
   ```bash
   cd ../server && npx prisma generate --schema=./prisma/schema.prisma && npx prisma migrate deploy --schema=./prisma/schema.prisma
   ```
8. Start the server:
   ```bash
   NODE_ENV=production node index.js &
   ```
9. Start the collector (from the `collector/` directory):
   ```bash
   cd ../collector && NODE_ENV=production node index.js &
   ```

Browse to `http://localhost:3001`.

For development, use the convenience scripts instead:

```bash
yarn dev:server     # server on port 3001
yarn dev:collector  # collector on port 8888
yarn dev:frontend   # Vite dev server with HMR
yarn dev:all        # all three concurrently
```

### Option 4 — Desktop app

The AnythingLLM Desktop app wraps the same engine for single-user local use on Windows, macOS, and Linux. Download from https://anythingllm.com/. The Desktop app does **not** support multi-user mode, embed widgets, the Telegram bot, or the developer API. Use Docker if you need those features.

> [!NOTE]
> Some users have reported issues with the desktop app on certain Windows builds (see GitHub issue #5422). If the desktop app fails to launch, try the Docker path instead.

### Option 5 — Cloud one-click deployments

Community- and team-maintained templates exist for:

| Platform | Method |
|---|---|
| **AWS** | CloudFormation template |
| **GCP** | Deployment Manager template |
| **DigitalOcean** | Terraform or 1-click Droplet |
| **Kubernetes** | Helm chart (`cloud-deployments/helm/`) |
| **HuggingFace Spaces** | Spaces deployment template |
| **Railway / Render / Elestio** | One-click deploy buttons |

These are convenience wrappers around the same Docker image. Find links on the project GitHub page.

### Post-install verification

After installation, confirm everything works:

1. Open `http://localhost:3001` — you should see the onboarding wizard (first run) or the login/chat page.
2. Check the server health endpoint:
   ```bash
   curl http://localhost:3001/api/health
   ```
3. Verify the collector is running (it starts automatically inside Docker):
   ```bash
   curl http://localhost:8888
   ```

---

## 3. Configuration

This section covers the settings most users need. See the **Admin Guide** for the full environment variable reference (559 configuration keys).

### First-run onboarding

The first time you open AnythingLLM, a guided wizard walks you through:

1. **Welcome** — a short introduction to the platform.
2. **LLM Preference** — pick a provider and enter credentials.
3. **User Setup** — optionally enable multi-user mode and create the first admin account.
4. **Data Handling** — opt in or out of anonymous telemetry.
5. **Survey** — optional (fully skippable).
6. **Create Your First Workspace** — name it, and you land in the chat view.

When onboarding completes, AnythingLLM writes `onboarding_complete=true` to its internal settings. You will not see this wizard again.

> [!NOTE]
> Every choice made during onboarding can be changed later from the Settings sidebar. Nothing is permanent.

### Choosing an LLM provider

AnythingLLM supports 35+ LLM providers. The most common choices:

| Provider | Type | API Key Required | Notes |
|---|---|---|---|
| **Ollama** | Local | No | Run any GGUF model locally. Point at `http://host.docker.internal:11434` from Docker. |
| **OpenAI** | Cloud | Yes | GPT-4o, GPT-4, GPT-3.5-turbo. Set `OPEN_AI_KEY`. |
| **Anthropic** | Cloud | Yes | Claude 3.5 Sonnet, Claude 3 Opus. Set `ANTHROPIC_API_KEY`. |
| **LM Studio** | Local | No | Desktop app for local models. Point at `http://host.docker.internal:1234`. |
| **Azure OpenAI** | Cloud | Yes | Enterprise Azure deployments. Requires deployment name + endpoint. |
| **Gemini** | Cloud | Yes | Google's Gemini models. Set `GEMINI_API_KEY`. |
| **AWS Bedrock** | Cloud | Yes | Claude, Llama, Titan via AWS. Requires IAM credentials. |
| **Groq** | Cloud | Yes | Ultra-fast inference. Set `GROQ_API_KEY`. |
| **OpenRouter** | Cloud | Yes | Multi-model gateway. Set `OPENROUTER_API_KEY`. |
| **DeepSeek** | Cloud | Yes | DeepSeek models. Set `DEEPSEEK_API_KEY`. |
| **Together AI** | Cloud | Yes | Open-source model hosting. Set `TOGETHER_AI_API_KEY`. |
| **Fireworks AI** | Cloud | Yes | Fast open-model inference. Set `FIREWORKS_AI_LLM_API_KEY`. |
| **Mistral** | Cloud | Yes | Mistral/Mixtral models. Set `MISTRAL_API_KEY`. |
| **xAI** | Cloud | Yes | Grok models. Set `XAI_LLM_API_KEY`. |
| **Perplexity** | Cloud | Yes | Search-augmented LLM. Set `PERPLEXITY_API_KEY`. |
| **Generic OpenAI** | Either | Varies | Any OpenAI-compatible endpoint. Set base URL + optional key. |
| **KoboldCPP** | Local | No | Local GGML/GGUF inference. |
| **LocalAI** | Local | No | OpenAI-compatible local server. |
| **LiteLLM** | Either | Varies | Universal proxy for 100+ providers. |
| **Private Mode** | Local | No | Runs entirely on browser, no server LLM calls. |

Additional providers: Novita, NVIDIA NIM, PPIO, Moonshot AI, Z.AI, Gitee AI, Cohere, Docker Model Runner, SambaNova, Lemonade, Foundry, Dell Pro AI Studio, HuggingFace, TextGenWebUI, CometAPI, ApiPie.

Change your provider at any time from *Settings → LLM Preference*.

### Choosing a vector database

The vector database stores your document embeddings for RAG retrieval.

| Vector DB | Type | Setup Needed |
|---|---|---|
| **LanceDB** (default) | Built-in | None — works out of the box |
| **Chroma** | Self-hosted | Run Chroma server, set `CHROMA_ENDPOINT` |
| **ChromaCloud** | Cloud | Set `CHROMA_CLOUD_ENDPOINT` + credentials |
| **Pinecone** | Cloud | Set `PINECONE_API_KEY` + `PINECONE_INDEX` |
| **Weaviate** | Self-hosted/Cloud | Set `WEAVIATE_ENDPOINT` + optional API key |
| **Qdrant** | Self-hosted/Cloud | Set `QDRANT_ENDPOINT` + optional API key |
| **Milvus** | Self-hosted | Set `MILVUS_ADDRESS` |
| **Zilliz** | Cloud | Set `ZILLIZ_ENDPOINT` + `ZILLIZ_API_TOKEN` |
| **PGVector** | Self-hosted | Set `POSTGRES_*` connection variables |
| **Astra** | Cloud | Set `ASTRA_DB_*` variables |

> [!TIP]
> For most users, the built-in **LanceDB** is the best choice. It requires zero setup, stores data in your mounted storage directory, and handles moderate-to-large document collections efficiently. Only switch to an external vector DB if you need multi-instance shared storage or very large-scale deployments.

### Choosing an embedding engine

The embedding engine converts your text into vector representations for search.

| Engine | Type | Notes |
|---|---|---|
| **Native** (default) | Built-in | Runs locally in-process, zero config |
| **OpenAI** | Cloud | Higher quality, uses your OpenAI key |
| **Azure OpenAI** | Cloud | Enterprise Azure embedding models |
| **Ollama** | Local | Uses your Ollama server |
| **LM Studio** | Local | Uses your LM Studio server |
| **LocalAI** | Local | Uses your LocalAI server |
| **Cohere** | Cloud | Cohere embed models |
| **Voyage AI** | Cloud | Specialized embedding models |
| **LiteLLM** | Either | Universal proxy |
| **Generic OpenAI** | Either | Any compatible endpoint |
| **OpenRouter** | Cloud | Via OpenRouter gateway |
| **Gemini** | Cloud | Google embedding models |
| **Mistral** | Cloud | Mistral embedding models |
| **Lemonade** | Local | Local embedding engine |

Change your embedding engine at any time from *Settings → Embedding Preference*.

### Key environment variables

These are the variables most users set. Place them in your `.env` file or pass via Docker environment.

| Variable | Purpose | Default |
|---|---|---|
| `STORAGE_DIR` | Absolute path to the storage directory | `/app/server/storage` (Docker) |
| `LLM_PROVIDER` | Active LLM provider name | (set during onboarding) |
| `EMBEDDING_ENGINE` | Active embedding engine | `native` |
| `VECTOR_DB` | Active vector database | `lancedb` |
| `SERVER_PORT` | Server listen port | `3001` |
| `AUTH_TOKEN` | Simple password for single-user mode | (empty = no password) |
| `JWT_SECRET` | Secret for multi-user JWT tokens | (auto-generated if unset) |
| `DISABLE_TELEMETRY` | Set to `true` to disable anonymous telemetry | `false` |

For the complete reference of all 559 configuration keys, see the **Admin Guide**.

> [!IMPORTANT]
> The `STORAGE_DIR` variable is critical. If it is not set or points to a non-existent path, AnythingLLM will fail to start. Always use an absolute path.

### Text splitter settings

Control how documents are chunked for embedding via *Settings → Text Splitter*:

- **Chunk size** — number of characters per chunk (default 1000). Larger chunks give more context per retrieval hit but fewer total chunks.
- **Chunk overlap** — number of characters shared between adjacent chunks (default 20). Helps preserve context across boundaries.

### Privacy and telemetry

AnythingLLM sends anonymous telemetry by default — event counts only, no content, no IP addresses, no document data. Disable with:

```text
DISABLE_TELEMETRY=true
```

Or toggle it off in *Settings → Privacy & Data Handling*.

---

## 4. Core Usage

### The main interface

Once onboarded, the interface has three zones:

```text
+---------------+--------------------------------------+
|  Workspaces   |                                      |
|   Sidebar     |          Chat Area                   |
|               |                                      |
|  - General    |  +--------------------------------+  |
|  - Research   |  | Chat messages / citations      |  |
|  - Support    |  +--------------------------------+  |
|  + New        |  [ Type a message...             ]   |
|               |                                      |
|  Settings >   |                                      |
+---------------+--------------------------------------+
```

- **Left sidebar** — your workspaces, pinned threads, and a gear icon for settings.
- **Chat area** — the current conversation, including drag-and-drop file upload, voice input, and a `/` menu for slash commands.
- **Settings** (admin/manager only) — LLM, vector DB, users, API keys, agents, widgets, branding.

Default-role users see only their assigned workspaces — the settings area is hidden.

### Workspaces

A **workspace** is your primary unit of organization. Each workspace contains:

- A pool of documents (its vector store)
- A specific LLM and model choice (optional — falls back to the system default)
- A system prompt that gives the workspace its personality and rules
- One or more threads (parallel conversations)
- Its own chat history
- A member list (in multi-user mode)

#### Create a workspace

1. Click **+ New Workspace** in the sidebar.
2. Give it a name (a URL slug is auto-generated from the name).
3. The workspace opens with an empty chat.

#### Workspace settings

Click the gear icon next to a workspace name to open its settings:

| Tab | What lives here |
|---|---|
| **General Appearance** | Name, profile picture, suggested messages, delete workspace |
| **Chat Settings** | LLM override, chat model, temperature, history length, chat mode, query refusal response |
| **Vector Database** | Similarity threshold, top-N snippets, vector search mode, re-embed toggle, vector count |
| **Members** | Add/remove users (multi-user mode only) |
| **Agent Configuration** | Agent LLM provider/model, enabled skills |

Every setting is **per-workspace** — your Research workspace can use Claude while your Support workspace uses a local Ollama model, with no conflict.

#### Workspace pinning

**Pin** a workspace or thread to float it to the top of the sidebar. Pinning is per-user.

#### Suggested messages

Each workspace can display up to four **suggested messages** on a blank chat — zero-effort prompts to get users started (e.g., "Summarize the latest policy doc", "What changed in the Q3 report?"). Configure in *Workspace Settings → General Appearance → Suggested Chat Messages*.

### Threads

A thread is a parallel conversation inside a workspace. Threads share the same documents and settings but have independent chat history.

- Click **+ New Thread** under a workspace to start one.
- Rename or delete a thread via the context menu.
- URL pattern: `/workspace/<slug>/t/<thread-slug>`.

Use threads when you want to ask several independent questions against the same knowledge base without polluting context.

### Loading documents

AnythingLLM processes documents through its **collector** service — a companion Express.js process running on port 8888. Inside Docker, it starts automatically alongside the main server.

#### Supported file types

| Category | Formats |
|---|---|
| **Documents** | PDF, DOCX, PPTX, XLSX/XLS, TXT, Markdown, HTML, RTF, ODT, EPUB, CSV, JSON, YAML/YML, XML |
| **Code** | `.js`, `.ts`, `.py`, `.go`, `.rs`, `.java`, `.c`, `.cpp`, `.cs`, `.rb`, `.php`, `.swift`, `.kt`, `.sh`, and many more |
| **Audio** | MP3, WAV, M4A, FLAC, OGG, WebM — transcribed via built-in Whisper or OpenAI Whisper |
| **Images** | JPG, PNG, GIF — via OCR (Tesseract). OCR is off by default; enable in settings. |
| **Email** | MBOX archives |

#### Data connectors

Beyond file uploads, AnythingLLM can pull content from external sources:

| Connector | What it does |
|---|---|
| **GitHub Repos** | Clone a repo and process eligible source files |
| **GitLab Repos** | Same as GitHub, for GitLab-hosted repos |
| **YouTube** | Extract video transcripts as searchable text |
| **Confluence** | Import pages from Atlassian Confluence |
| **DrupalWiki** | Import pages from DrupalWiki instances |
| **Obsidian Vaults** | Import an Obsidian vault directory |
| **PaperlessNGX** | Import documents from a Paperless-ngx instance |
| **Website Depth Crawler** | Crawl a website to a configurable depth and import all pages |
| **URL / Web Link** | Scrape a single URL via Puppeteer |

Access data connectors from the **Document Management** modal → **Data Connectors** tab.

#### How to upload

Three methods:

1. **Drag and drop** a file or folder directly onto the chat area.
2. Click the **paperclip** icon in the chat input, or the document management button near the workspace name.
3. In Document Management, select a folder, then **Upload**.

After upload:

1. Files appear in **Custom Documents** or a folder you choose.
2. Click **Move to Workspace** to select which files to embed into the workspace's vector store.
3. An **embedding progress bar** shows until vectors are ready.
4. Documents display a checkmark once embedded.

> [!TIP]
> Only embed what you need for the current task. Embedded documents consume vector DB storage and slightly increase per-query retrieval time. You can always add more later.

#### Pinning vs. embedding vs. watching

| Action | Effect |
|---|---|
| **Embed** | Chunks the document, vectorizes it, and stores chunks in the workspace's vector store. Used for RAG — only the top-N most-relevant chunks are sent to the LLM each turn. |
| **Pin** | Forces the **full document text** into every LLM request for this workspace. Ideal for short reference docs (company policy, style guide); expensive for large files. |
| **Watch** | Tracks the source (URL, YouTube, GitHub, Confluence) and re-syncs on a schedule when the content changes. |

#### Document folders

Documents live in folders. You can create, rename, move, and delete folders in Document Management. Each folder can be embedded into multiple workspaces — useful for a shared "company docs" folder used by different teams.

### Chatting with your documents

Once documents are embedded in a workspace, type your question. AnythingLLM:

1. Runs a vector search against the workspace's embedded documents.
2. Finds the top-N most-relevant chunks (default 4, configurable per workspace).
3. Builds a prompt: `[system prompt] + [context chunks] + [chat history] + [your message]`.
4. Sends to the configured LLM.
5. Streams the response token-by-token.
6. Shows **citations** — which documents the answer drew from — under each reply.

#### Citations

Under each answer, a **Citations** tray shows the source documents and exact snippets used. Click a snippet to see the full context or jump to the source URL. Citations are how you verify answers — if a claim lacks a citation, treat it as LLM generation rather than document fact.

#### Attaching files to a single message

Drag a file into the chat input (not the document manager) to attach it to **just this message**. The file is parsed and included inline with your prompt but not added to the workspace vector store. Ideal for one-off tasks like "summarize this report."

#### Voice input

Click the **microphone** icon in the chat input to dictate. By default, AnythingLLM uses your browser's built-in speech recognition. If server-side Whisper is configured, longer and noisier recordings are transcribed there instead.

#### Streaming and stopping

Responses stream token-by-token. Click the **Stop** button (which replaces Send during streaming) to cancel mid-response. Partial output is saved to the chat history.

> [!NOTE]
> Streaming requires WebSocket support. If you are behind a reverse proxy, ensure WebSocket upgrade headers are forwarded (see Troubleshooting).

### Chat modes

Each workspace has a **chat mode** setting in *Workspace Settings → Chat Settings → Chat Mode*:

| Mode | Behavior |
|---|---|
| **chat** (default) | Full conversation — prior turns, context chunks, and LLM general knowledge. Best for open-ended work. |
| **query** | Strictly RAG. The LLM answers **only from retrieved document snippets**; if there is no relevant context, it responds with the configured **query refusal response**. Best for factual bots where hallucinations are unacceptable. |
| **automatic** | Checks if the workspace supports native tool calling; if so, the agent is invoked automatically without the `@agent` prefix. Requires a provider with function-calling support (OpenAI, Anthropic, Gemini). |

#### Query refusal response

In *Workspace Settings → Chat Settings*, set the **Query Refusal Response** to define what the bot says when it has no matching context (e.g., *"I can only answer questions about the loaded documents."*). This only applies in **query** mode.

### Slash commands

Type `/` in the chat input to open the command palette.

| Command | Effect |
|---|---|
| `/reset` | Clears the current thread's in-context history (starts a fresh conversation in the same thread) |
| `/exit` | Ends an active agent session |
| `/help` | Shows available slash commands |

#### Custom slash commands (presets)

Create reusable prompt templates as custom slash commands. Example: define `/summarize` that expands to `Summarize the following in 3 bullet points:` — then type `/summarize` followed by your text.

Create presets under *Chat Settings → Prompt Shortcuts* or the lightning-bolt icon in the chat input. Presets are per-user in multi-user mode.

Custom slash commands can be published to and imported from the **Community Hub**.

### System prompts and workspace personality

Every workspace has a **system prompt** — the instruction that shapes every reply. Set it in *Workspace Settings → Chat Settings → System Prompt*.

The default system prompt is:

> Given the following conversation, relevant context, and a follow up question, reply with an answer to the current question the user is asking. Return only your response to the question given the above information following the users instructions as needed.

Override with anything: *"You are a senior legal analyst. Always cite paragraph numbers from the contracts."*

#### System prompt variables

Admins can define named **variables** (e.g., `{user.name}`, `{company.name}`, custom ones) that are expanded before the prompt reaches the LLM. Manage these in *Settings → System Prompt Variables*. Variables let you write one prompt template and personalize it per user or context.

#### Prompt history

Every system prompt edit is saved to **Prompt History** for that workspace. Roll back to any prior version in one click. Revisions are per-workspace and show who changed what and when.

### Text-to-speech (TTS)

AnythingLLM can read responses aloud. Click the **speaker** icon next to any assistant reply.

| Provider | Type | Setup |
|---|---|---|
| **Browser native** (default) | Client-side | None — uses your OS speech engine |
| **PiperTTS Local** | Client-side | Runs in-browser via WebAssembly, offline, high quality |
| **OpenAI TTS** | Cloud | Requires OpenAI API key. Voices: alloy, echo, fable, onyx, nova, shimmer. |
| **ElevenLabs** | Cloud | Requires ElevenLabs API key. Configure voice ID per instance. |
| **Generic OpenAI-Compatible** | Either | Point at any OpenAI-compatible TTS endpoint. |

Configure TTS in *Settings → Audio Preference*.

### Speech-to-text (STT)

The microphone button in the chat input uses your **browser's built-in** speech recognition by default (Chrome, Edge, Safari). For server-side transcription (better for long or noisy recordings), the admin configures a Whisper provider in *Settings → Transcription Preference*:

- **Built-in Whisper** — runs locally inside the collector service
- **OpenAI Whisper** — sends audio to OpenAI's API for transcription

### Audio documents

Drop an audio file (MP3, WAV, etc.) into the collector and AnythingLLM transcribes it to text, then embeds the transcript. Searching the workspace surfaces the topics discussed.

> [!WARNING]
> Audio transcription with the built-in Whisper model can be slow on CPU-only machines. For large audio files, consider using the OpenAI Whisper provider or pre-transcribing externally.

---

## 5. Common Tasks

### Recipe 1: Build a private knowledge base from company docs

**Goal:** Create a workspace backed by your team's internal documents.

1. Create a new workspace named after the project or team.
2. Open Document Management and create a folder (e.g., "Engineering Docs").
3. Drag PDFs, Word documents, and Markdown files into the folder.
4. Select all uploaded files and click **Move to Workspace**.
5. Wait for the embedding progress bar to complete.
6. Ask: *"What is our deployment process?"* — the answer pulls from your documents with citations.

**Verify:** Check that citations reference the correct source documents.

**If it fails:** Check *Settings → Event Logs* for embedding errors. The most common issue is a corrupted PDF — try re-exporting it.

### Recipe 2: Set up a customer support bot with query mode

**Goal:** A bot that only answers from loaded FAQ/knowledge base docs, never hallucinating.

1. Create a workspace named "Support Bot".
2. Upload your FAQ documents and knowledge base articles.
3. Embed all documents into the workspace.
4. Go to *Workspace Settings → Chat Settings*:
   - Set **Chat Mode** to **query**.
   - Set **Query Refusal Response** to: *"I don't have information about that in my knowledge base. Please contact [email removed]."*
5. Test with questions both inside and outside your docs — the refusal should trigger for anything not covered.

### Recipe 3: Connect Ollama for fully private, offline AI

**Goal:** Run everything locally with zero cloud dependency.

1. Install Ollama on your host machine and pull a model:
   ```bash
   ollama pull llama3
   ```
2. In AnythingLLM, go to *Settings → LLM Preference* → select **Ollama**.
3. Set the base URL:
   - Docker: `http://host.docker.internal:11434`
   - Bare metal: `http://localhost:11434`
4. Select your model from the dropdown (it auto-discovers available models).
5. For embedding, go to *Settings → Embedding Preference* → select **Ollama** with the same base URL.
6. Chat in any workspace — all processing stays on your machine.

> [!TIP]
> For best results with RAG, use a model with at least 7B parameters. Smaller models may struggle with context-heavy document queries.

### Recipe 4: Embed a support widget on your website

**Goal:** Put a floating chat button on your website backed by a workspace.

1. Go to *Settings → Embed Chat Widgets* and click **Create Embed**.
2. Select the workspace to back the widget.
3. Configure:
   - **Chat mode**: `query` (recommended for public-facing bots)
   - **Allowlist domains**: `yoursite.com, www.yoursite.com`
   - **Max chats per day**: `50` (rate limit per visitor)
4. Click **Create**. Copy the generated `<script>` snippet.
5. Paste into your site's HTML before `</body>`:
   ```html
   <script
     data-embed-id="your-uuid-here"
     data-base-api-url="https://your-anythingllm.example.com/api/embed"
     src="https://your-anythingllm.example.com/embed/anythingllm-chat-widget.min.js">
   </script>
   ```
6. Load the page — a chat bubble appears in the bottom-right corner.

### Recipe 5: Use agents to browse the web and summarize

**Goal:** Have the agent search the web and give you a summary.

1. Go to *Settings → Agents* and configure a **web search provider** (Serper, SerpAPI, Tavily, Bing, SearXNG, Perplexity, Exa, Serply, or SearchAPI). Enter the required API key.
2. In your workspace, go to *Workspace Settings → Agent Configuration*.
3. Enable the **web-browsing** skill.
4. Optionally set a strong reasoning model as the agent LLM (GPT-4, Claude 3, Llama 3 70B).
5. Chat:
   ```text
   @agent What are the latest developments in WebAssembly? Search the web and summarize the top 5 results.
   ```
6. The agent searches, reads pages, and returns a synthesis.

### Recipe 6: Connect a Telegram bot to your workspace

**Goal:** Let users chat with your knowledge base via Telegram.

1. On Telegram, message `@BotFather` → `/newbot` → follow the prompts to get a bot token.
2. In AnythingLLM, go to *Settings → External Connections → Telegram Bot*.
3. Paste the bot token.
4. Select which workspace the bot should use.
5. Optionally configure:
   - A welcome message
   - Whitelisted Telegram user IDs (restrict access)
6. Click **Start Bot**. The bot connects via long-polling (no webhook setup needed).
7. Message your bot on Telegram — replies come from the linked workspace.

The bot supports text messages, voice notes (transcribed via the STT pipeline), and multimedia attachments.

### Recipe 7: Pair the mobile app

**Goal:** Chat with your AnythingLLM instance from your phone.

1. On desktop, go to *Settings → Mobile Connections*.
2. Click **Generate Pairing Code** — a QR code appears with a time-limited token.
3. On the AnythingLLM mobile app, scan the QR code.
4. The device appears in the connection list — approve it.
5. You can now chat, upload photos, and dictate messages from your phone.

**Connection methods:**
- **Same LAN**: point the app at `http://<server-ip>:3001`.
- **Remote**: put your instance behind a reverse proxy with HTTPS, or use a VPN like Tailscale.

### Recipe 8: Use the browser extension to send pages to a workspace

**Goal:** Send web pages you're browsing directly into a workspace.

1. Install the AnythingLLM extension from the Chrome Web Store.
2. Click the extension icon → *Connect to AnythingLLM*.
3. Enter your server URL and a browser extension API key.
4. To get the key: go to *Settings → Browser Extension API Keys* → **New Key**. The key starts with `brx-`.
5. With the extension connected:
   - **Send page**: adds the current tab's URL to a workspace (collector scrapes it).
   - **Send selection**: adds highlighted text as an inline snippet.
   - **Ask**: opens a chat pop-up scoped to the current page.

### Recipe 9: Build a no-code agent flow

**Goal:** Create a reusable agent workflow without writing code.

1. Go to *Settings → Agents → Agent Flows* and click **New Flow**.
2. Add a **Start** block — define input parameters (e.g., `topic`).
3. Add an **LLM Instruction** block — write a prompt using `{topic}` as a variable.
4. Add an **API Call** block — hit an external API if needed (e.g., fetch data from a REST endpoint).
5. Add a **Finish** block — return the final output.
6. Save the flow.
7. Enable the flow as a skill in your workspace's Agent Configuration.
8. Invoke it:
   ```text
   @agent run the "research summary" flow with topic="quantum computing"
   ```

Available flow blocks:

| Block | Purpose |
|---|---|
| **Start** | Defines the flow's input parameters |
| **LLM Instruction** | Sends text to an LLM, captures the reply |
| **API Call** | HTTP GET/POST/PUT/DELETE with configurable headers and body |
| **Web Scraping** | Fetch and parse a URL |
| **Code** | Execute custom JavaScript logic |
| **Read File** | Read a file from storage |
| **Write File To Browser** | Download content to the end user |
| **Finish** | Returns the final value |

Flows can be exported as JSON, shared, and imported into other AnythingLLM instances or published to the Community Hub.

### Recipe 10: Query a SQL database through the agent

**Goal:** Let the agent run SQL queries against your database.

1. Go to *Settings → Agents*.
2. Enable the **sql-agent** skill.
3. Configure a database connection (PostgreSQL, MySQL, or MSSQL) with host, port, user, password, and database name.
4. In your workspace, enable the sql-agent skill in Agent Configuration.
5. Chat:
   ```text
   @agent How many orders were placed last month? Query the orders table.
   ```
6. The agent generates SQL, runs it, and returns the results in natural language.

> [!CAUTION]
> The SQL agent has read-write access to the configured database. Only connect to databases where you accept the risk of agent-generated queries. Use a read-only database user for safety.

### Recipe 11: Set up multi-user mode for a team

**Goal:** Give team members individual accounts with role-based access.

1. Go to *Settings → Users → Enable Multi-User Mode*.
2. Create the first admin account.
3. AnythingLLM restarts the session — you now see a login page.
4. Create workspaces for different teams/projects.
5. Go to *Settings → Invitations* → generate invite codes.
6. Share codes with team members — they sign up at `/accept-invite/<code>`.
7. Assign users to workspaces via *Workspace Settings → Members*.

### Recipe 12: Import a GitHub repository as a knowledge source

**Goal:** Make an entire codebase searchable via chat.

1. Open Document Management → **Data Connectors** tab → **GitHub**.
2. Enter the repository URL (e.g., `https://github.com/owner/repo`).
3. Optionally provide a GitHub personal access token for private repos.
4. Select which branches and file types to include.
5. Click **Submit**. The collector clones the repo and processes all eligible files.
6. Move the processed files to your workspace.
7. Ask: *"How does the authentication middleware work?"*

### Recipe 13: Import YouTube video transcripts

**Goal:** Search and ask questions about video content.

1. Open Document Management → **Data Connectors** → **YouTube**.
2. Paste the YouTube video URL.
3. The collector extracts the transcript and creates a document.
4. Move it to a workspace and embed.
5. Ask: *"What did the speaker say about performance optimization at the 15-minute mark?"*

### Recipe 14: Crawl an entire website

**Goal:** Import all pages from a website for RAG.

1. Open Document Management → **Data Connectors** → **Website Depth Crawler**.
2. Enter the starting URL.
3. Set the crawl depth (how many links deep to follow).
4. Click **Submit**. The collector uses Puppeteer to crawl pages.
5. Move crawled pages to your workspace and embed.

### Recipe 15: Use the OpenAI-compatible API

**Goal:** Use AnythingLLM as a drop-in replacement for the OpenAI API.

1. Generate an API key from *Settings → Developer API*.
2. Point any OpenAI SDK at your AnythingLLM instance:
   ```python
   from openai import OpenAI

   client = OpenAI(
       base_url="https://your-instance.example.com/api/v1/openai",
       api_key="your-anythingllm-api-key"
   )

   response = client.chat.completions.create(
       model="your-workspace-slug",  # workspace name as model
       messages=[{"role": "user", "content": "What are the key findings?"}]
   )
   ```
3. The "model" parameter maps to a workspace slug. List available workspaces:
   ```bash
   curl -H "Authorization: Bearer $KEY" \
     https://your-instance/api/v1/openai/models
   ```

### Recipe 16: Configure email agent skills (Gmail/Outlook)

**Goal:** Let the agent send emails and read your inbox.

1. Go to *Settings → Agents*.
2. Enable the **gmail** or **outlook** skill.
3. Complete the OAuth 2.0 flow — AnythingLLM redirects you to Google/Microsoft to authorize.
4. Once authorized, enable the skill in your workspace's Agent Configuration.
5. Chat:
   ```text
   @agent Send an email to [email removed] with a summary of today's meeting notes
   ```

### Recipe 17: Use Google Calendar with the agent

**Goal:** Create and query calendar events through chat.

1. Go to *Settings → Agents* and enable **google-calendar**.
2. Complete OAuth 2.0 authorization with Google.
3. Enable in your workspace's Agent Configuration.
4. Chat:
   ```text
   @agent What meetings do I have tomorrow?
   @agent Schedule a 30-minute call with Bob at 2pm Friday
   ```

### Recipe 18: Add an MCP server

**Goal:** Extend agent capabilities with external MCP-compatible tools.

1. Edit `plugins/anythingllm_mcp_servers.json` in your storage directory:
   ```json
   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
         "anythingllm": { "autoStart": true }
       },
       "weather": {
         "type": "streamableHTTP",
         "url": "https://weather.example.com/mcp"
       }
     }
   }
   ```
2. Supported server types:
   - **stdio** (default) — subprocess launched via `command` + `args`
   - **sse** — Server-Sent Events over HTTP
   - **streamableHTTP** — newer MCP HTTP transport
3. Restart AnythingLLM (or hit **Reload MCP** in agent settings).
4. The MCP server's tools now appear in the agent skills list — enable them per-workspace.

### Recipe 19: Customize branding

**Goal:** White-label the AnythingLLM interface.

1. Go to *Settings → Appearance → Branding*:
   - Upload a custom **logo** (replaces the AnythingLLM logo).
   - Set a custom **app name** (appears in the browser tab and welcome screen).
   - Customize **footer links** (add your own icons and URLs).
   - Configure **support email** (shown in error states).
2. Go to *Settings → Appearance → Interface*:
   - Choose a **theme** (light, dark, or custom).
   - Toggle the **scrollbar** visibility.
   - Toggle **spell check** in the chat input.
   - Toggle **HTML rendering** in chat responses.

### Recipe 20: Set up HTTPS

**Goal:** Secure your AnythingLLM instance with SSL/TLS.

AnythingLLM supports built-in HTTPS. Set these environment variables:

```text
ENABLE_HTTPS=true
HTTPS_CERT_PATH=/path/to/cert.pem
HTTPS_KEY_PATH=/path/to/key.pem
```

Alternatively, place AnythingLLM behind a reverse proxy (nginx, Traefik, Caddy) that handles SSL termination. This is the recommended approach for production.

### Recipe 21: Export and manage chat history

**Goal:** Review, export, or delete conversation history.

1. Go to *Settings → Chats* to see all chat logs across workspaces.
2. Filter by workspace, user, or date range.
3. Export chats for audit or review purposes.
4. Delete individual messages or entire conversations.

For per-workspace chat history, click the workspace gear → check history settings.

### Recipe 22: Configure workspace-level LLM overrides

**Goal:** Use different LLM models for different workspaces.

1. Open *Workspace Settings → Chat Settings → LLM Override*.
2. Select a different provider and model for this workspace.
3. Set workspace-specific parameters:
   - **Temperature** (0.0 = deterministic, 1.0 = creative)
   - **Chat history length** (how many prior turns to include)
4. Save. This workspace now uses its own model, independent of the global setting.

### Recipe 23: Import community skills and prompts

**Goal:** Extend AnythingLLM with community-shared content.

1. Go to *Settings → Community Hub → Trending*.
2. Browse popular agent flows, system prompts, and slash commands.
3. Click **Import** on any item.
4. Choose which workspace to attach it to (for flows) or import globally (for prompts/presets).
5. Use immediately — imported flows appear as agent skills, prompts appear in workspace settings.

To **publish** your own items: go to *Settings → Community Hub → Authentication*, sign in, get an API key, and use the **Publish to Hub** button on any flow/prompt/preset you've created.

### Recipe 24: Set up password recovery

**Goal:** Enable self-service password recovery for multi-user mode.

In multi-user mode, admins can generate **recovery codes** for users:

1. Go to *Settings → Users* → select a user → **Generate Recovery Codes**.
2. Recovery codes are displayed once — share them securely with the user.
3. Users enter their recovery code at the login page to reset their password.

> [!IMPORTANT]
> Recovery codes are one-time use. Once used, generate new ones. Store them securely — anyone with a recovery code can reset a user's password.

### Recipe 25: Use the developer API for automation

**Goal:** Automate workspace and document management programmatically.

Generate an API key from *Settings → Developer API* → **New Key**.

**List workspaces:**
```bash
curl -H "Authorization: Bearer $KEY" \
  https://your-instance/api/v1/workspaces
```

**Create a workspace:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Automated Research"}' \
  https://your-instance/api/v1/workspace/new
```

**Upload a document:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" \
  -F "file=@report.pdf" \
  https://your-instance/api/v1/document/upload
```

**Send a chat message:**
```bash
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"What are the key findings?","mode":"chat"}' \
  https://your-instance/api/v1/workspace/sales-research/chat
```

**Stream a chat response (Server-Sent Events):**
```bash
curl -N -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarize Q3","mode":"chat"}' \
  https://your-instance/api/v1/workspace/sales-research/stream-chat
```

**Swagger / OpenAPI:** Open `https://your-instance/api/docs` for the interactive API explorer. Raw spec at `/api/docs/openapi.json`. Disable with `DISABLE_SWAGGER_DOCS=true`.

---

## 6. Troubleshooting

### Diagnostic decision tree

```text
Problem reported
  |
  +-- Can you reach http://localhost:3001?
  |     |
  |     +-- No --> Is the container running? (docker ps)
  |     |          +-- No --> Check docker logs for startup errors
  |     |          +-- Yes --> Check SERVER_PORT and firewall
  |     |
  |     +-- Yes --> Can you log in / see the chat?
  |           |
  |           +-- No --> Auth issue (check AUTH_TOKEN, JWT_SECRET, multi-user config)
  |           |
  |           +-- Yes --> Is the issue with...
  |                 +-- Chat responses --> Check LLM provider config + Event Logs
  |                 +-- Document upload --> Check collector logs (port 8888)
  |                 +-- Agents --> Check agent LLM config + enabled skills
  |                 +-- Embeds/API --> Check API key, CORS, WebSocket headers
```

---

### Error: Cannot connect to LLM running on localhost from Docker

**Cause:** Inside a Docker container, `localhost` resolves to the container itself, not the host machine. Your LLM server (Ollama, LM Studio, LocalAI) is running on the host.

**Solution:**
Replace `localhost` with `host.docker.internal` in all provider URLs:

```text
OLLAMA_BASE_PATH=http://host.docker.internal:11434
```

On Linux, if `host.docker.internal` does not resolve, add the flag to your Docker run command:

```bash
docker run --add-host=host.docker.internal:host-gateway ...
```

Or use the Docker bridge gateway IP directly: `http://172.17.0.1:11434`.

**Prevention:** Always use `host.docker.internal` instead of `localhost` when running providers on the host alongside Docker.

---

### Error: `Cannot create JWT as JWT_SECRET is unset`

**Cause:** Multi-user mode is enabled (or `AUTH_TOKEN` is set) but `JWT_SECRET` is missing from the environment.

**Solution:**
Set `JWT_SECRET` in your `.env` to any random string of at least 12 characters:

```text
JWT_SECRET=your-random-string-at-least-12-chars-long
```

Restart the container.

**Prevention:** Always set `JWT_SECRET` before enabling multi-user mode or `AUTH_TOKEN`.

---

### Error: Embeddings take extremely long on large documents

**Cause:** The native embedding engine runs in-process on CPU. Large documents with many chunks are slow to embed.

**Solution:**
1. Switch the embedder from **native** to a GPU-accelerated one (Ollama on a GPU, OpenAI, or another cloud provider).
2. If using Ollama, increase the batch size:
   ```text
   OLLAMA_EMBEDDING_BATCH_SIZE=16
   ```
3. Reduce the text splitter chunk size in *Settings → Text Splitter* — smaller chunks mean more of them, but each embeds faster.

**Prevention:** Use a server-side embedding engine for large document collections.

---

### Error: Agent says "OpenAI API key must be provided"

**Cause:** The workspace's agent LLM provider is set to OpenAI, but no API key is configured.

**Solution:**
Either:
- Set `OPEN_AI_KEY` in your `.env` or via the admin UI.
- Change the agent LLM provider to one you have configured (*Workspace Settings → Agent Configuration → Agent LLM Provider*).

**Prevention:** Configure agent LLM credentials before enabling agent skills.

---

### Error: Chat returns blank or empty responses

**Cause:** The LLM is returning empty output. Common reasons: wrong model name, exhausted API quota, network block to the provider, or the model crashed.

**Solution:**
1. Check *Settings → Event Logs* — LLM errors are logged with full traces.
2. Verify the model name matches what the provider expects.
3. Test the provider directly (e.g., `curl` Ollama's `/api/generate` endpoint).
4. Check your API key quota/billing dashboard for the cloud provider.

**Prevention:** Monitor Event Logs regularly and set up alerts for provider errors.

---

### Error: Docker container crashes on Webkit browsers

**Cause:** Known issue in v1.12.0 where certain Webkit-based browsers trigger a crash in the frontend rendering pipeline (GitHub issue #5433, #5435).

**Solution:**
Use Chrome, Edge, or Firefox instead of Safari or other Webkit browsers. Alternatively, downgrade to v1.11.1 or wait for the fix in a future release.

**Prevention:** Test on Chrome or Edge first when upgrading to new versions.

---

### Error: Desktop app fails to launch on Windows

**Cause:** Known issue (GitHub issue #5422) with the Electron wrapper on certain Windows builds.

**Solution:**
1. Try running the app as administrator.
2. Check Windows event logs for crash details.
3. Switch to the Docker installation method.

**Prevention:** The Docker path is more reliable across all platforms.

---

### Error: LM Studio integration returns errors

**Cause:** Known compatibility issue (GitHub issue #5421) where certain LM Studio versions return responses in an unexpected format.

**Solution:**
1. Ensure LM Studio is updated to the latest version.
2. Verify the base URL is correct (`http://host.docker.internal:1234` from Docker, `http://localhost:1234` on bare metal).
3. Try using the **Generic OpenAI** provider instead, pointing at LM Studio's OpenAI-compatible endpoint.

**Prevention:** Test the LM Studio endpoint with `curl` before configuring it in AnythingLLM.

---

### Error: LocalWhisper fails on Telegram voice messages

**Cause:** The local Whisper model fails to process certain audio formats from Telegram voice messages (GitHub issue #5420).

**Solution:**
1. Switch the Whisper provider from local to **OpenAI Whisper** in *Settings → Transcription Preference*.
2. Or ensure FFmpeg is installed and accessible in the container (the Docker image includes it).

**Prevention:** Use the OpenAI Whisper provider for reliable Telegram voice transcription.

---

### Error: Embedded Ollama server version mismatch

**Cause:** The bundled Ollama version in the desktop app does not match the expected API version (GitHub issue #5451).

**Solution:**
1. Update the desktop app to the latest version.
2. Or install Ollama separately and point AnythingLLM at it via *Settings → LLM Preference*.

**Prevention:** Use an externally managed Ollama installation for more control over versions.

---

### Error: `Invalid path name` in the collector

**Cause:** The uploaded filename contains characters that the collector rejects for security (e.g., `..`, null bytes, special Unicode).

**Solution:**
Rename the file to use only alphanumeric characters, hyphens, underscores, and dots. Re-upload.

**Prevention:** Use simple, ASCII-only filenames for uploads.

---

### Error: Uploaded PDF shows zero tokens / zero content

**Cause:** Either the PDF is encrypted/password-protected, or it is a scanned image PDF that requires OCR.

**Solution:**
1. For encrypted PDFs: remove the password using a PDF tool first, then re-upload.
2. For scanned PDFs: enable OCR in *Settings → Privacy & Data Handling*. Set `TARGET_OCR_LANG` to the appropriate language code if not English.

**Prevention:** Check PDF text-selectability before uploading. If you cannot select text, the PDF needs OCR.

---

### Error: Confluence connector fails with context path URLs

**Cause:** Confluence instances behind a custom context path (e.g., `https://wiki.company.com/confluence/`) are not handled correctly (GitHub issue #4678).

**Solution:**
Ensure the URL includes the full context path. If the connector still fails, use the **Website Depth Crawler** connector as a workaround — point it at your Confluence space URL.

**Prevention:** Use Confluence's direct page URLs when possible.

---

### Error: Agent interactions not persisted to thread history via API

**Cause:** When using the developer API to trigger agent conversations, the interactions may not be saved to the thread's chat history (GitHub issue #5060).

**Solution:**
This is a known limitation. As a workaround, use the web interface for agent conversations where history persistence is critical. For API usage, log the responses on your end.

**Prevention:** Monitor the GitHub issue for a fix in future releases.

---

### Error: Meeting assistant agent fails on Blackwell GPU

**Cause:** Certain CUDA operations for the meeting assistant agent are incompatible with NVIDIA Blackwell GPUs (GitHub issue #5409).

**Solution:**
Use a cloud LLM provider for the agent instead of a local GPU-based model. Or use a non-Blackwell GPU.

**Prevention:** Check GPU compatibility before deploying local models.

---

### Error: Mobile app cannot reach the server remotely

**Cause:** The server binds to `127.0.0.1` by default (or the network path is blocked).

**Solution:**
1. Make sure the server binds to `0.0.0.0` (it does by default in Docker).
2. Open firewall port 3001 on the host.
3. If behind a reverse proxy (nginx, Traefik), ensure WebSocket upgrade headers are proxied:
   ```nginx
   location / {
       proxy_pass http://localhost:3001;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_set_header Host $host;
   }
   ```

**Prevention:** Always configure WebSocket forwarding in your reverse proxy.

---

### Error: Chrome extension won't connect

**Cause:** Either the server URL is wrong or the API key type is incorrect.

**Solution:**
1. Verify the server URL is reachable from your browser (same URL you use for the web interface).
2. Ensure the API key starts with `brx-`. If it starts with something else, you generated a developer API key by mistake. Use *Settings → Browser Extension API Keys* instead of *Settings → Developer API*.
3. Check that the server's CORS settings allow requests from the extension origin.

**Prevention:** Always use the dedicated Browser Extension API Keys section.

---

### Error: `docker compose` build fails

**Cause:** Docker Compose version incompatibility or build context issues (GitHub issue #5433).

**Solution:**
1. Use Docker Compose v2 (`docker compose` without the hyphen).
2. Pull the pre-built image instead of building:
   ```yaml
   image: mintplexlabs/anythingllm
   ```
3. If you must build from source, ensure you have sufficient disk space and memory.

**Prevention:** Use the pre-built Docker image rather than building from the Dockerfile.

---

### Error: Vector store becomes corrupted or inconsistent

**Cause:** The container was killed during an embedding operation, leaving partial writes in LanceDB.

**Solution:**
1. Stop the container.
2. In your workspace settings, use **Reset Database** under the Vector Database tab to clear and re-embed.
3. Re-upload and re-embed your documents.

**Prevention:** Allow embedding operations to complete before stopping the container. Use `docker stop` (graceful) rather than `docker kill`.

> [!CAUTION]
> Resetting the vector database deletes all embedded vectors for that workspace. You will need to re-embed all documents.

---

### Error: TTS produces no audio

**Cause:** The selected TTS provider is misconfigured or the browser does not support the Web Speech API.

**Solution:**
1. If using **Browser native**: try a different browser (Chrome has the best support). Check that your OS has speech synthesis voices installed.
2. If using **OpenAI TTS** or **ElevenLabs**: verify the API key in *Settings → Audio Preference*.
3. If using **PiperTTS Local**: ensure WebAssembly is enabled in your browser.

**Prevention:** Test TTS with a short message after configuration changes.

---

### Error: SSO redirect loop

**Cause:** `SIMPLE_SSO_NO_LOGIN_REDIRECT` points to an IdP that redirects back to AnythingLLM, creating an infinite loop.

**Solution:**
1. Verify the redirect URL in your IdP matches the AnythingLLM callback URL.
2. Clear browser cookies and try again.
3. Temporarily disable SSO by removing the environment variables and restarting.

**Prevention:** Test SSO configuration in a private browser window first.

---

### Error: Webhook or API returns CORS errors

**Cause:** Cross-origin requests are blocked because the AnythingLLM server does not recognize the requesting domain.

**Solution:**
If you are accessing the API from a browser-based app on a different domain, put AnythingLLM behind a reverse proxy that adds the appropriate `Access-Control-Allow-Origin` headers.

**Prevention:** Deploy behind a reverse proxy with proper CORS configuration for production use.

---

### Error: Push notifications not working on mobile

**Cause:** VAPID keys are not generated, or the browser/mobile app does not support Web Push.

**Solution:**
1. VAPID keys are auto-generated on first use. If missing, restart the server.
2. Ensure the mobile app has notification permissions enabled.
3. For browsers, check that push notification permissions are granted in browser settings.

**Prevention:** Verify notification permissions after initial setup.

---

### Error: Workspace chat history not loading after upgrade

**Cause:** A database schema migration was not applied after updating AnythingLLM to a new version.

**Solution:**
1. Stop the container.
2. Start it again — Prisma migrations run automatically on boot.
3. If the issue persists, run the migration manually from inside the container:
   ```bash
   docker exec -it anythingllm npx prisma migrate deploy --schema=/app/server/prisma/schema.prisma
   ```
4. Restart the container.

**Prevention:** Always allow the container to complete its startup sequence after upgrades. Check the container logs for migration output.

---

### Error: Agent runs in an infinite loop

**Cause:** The agent keeps calling tools without reaching a conclusion, exhausting the tool-call limit.

**Solution:**
1. Type `/exit` to forcefully end the agent session.
2. In *Workspace Settings → Agent Configuration*, lower the **tool call limit** (e.g., to 10).
3. Use a stronger reasoning model for the agent LLM — weaker models are more prone to loops.

**Prevention:** Set conservative tool-call limits and use capable models (GPT-4, Claude 3) for agent tasks.

> [!WARNING]
> Infinite agent loops can consume significant LLM tokens. Always set a tool-call limit to protect against runaway costs.

---

## 7. FAQ

### General

**Q: What is AnythingLLM?**

AnythingLLM is an all-in-one, self-hosted AI application by Mintplex Labs. It provides a web-based chat interface with RAG (Retrieval-Augmented Generation), AI agents, embeddable widgets, and integrations with 35+ LLM providers, 10+ vector databases, and 14 embedding engines. Everything runs in a single Docker container or as a desktop app.

**Q: Is AnythingLLM free?**

Yes. AnythingLLM is open-source software released under a permissive license. You self-host it and bring your own LLM provider. There are no license fees. Your only costs are infrastructure (a server) and any cloud LLM API charges from providers you choose to use.

**Q: What is the current version?**

Version 1.11.1 (source commit `649c942`, April 2026).

**Q: What LLM providers does AnythingLLM support?**

Over 35 providers: OpenAI, Anthropic, Ollama, LM Studio, Groq, Together AI, Azure OpenAI, KoboldCPP, LocalAI, OpenRouter, Mistral, Generic OpenAI, Perplexity, AWS Bedrock, Fireworks AI, DeepSeek, LiteLLM, ApiPie, xAI, Novita, NVIDIA NIM, PPIO, Gemini, Moonshot AI, Z.AI, Gitee AI, Cohere, Docker Model Runner, SambaNova, Lemonade, Foundry, Dell Pro AI Studio, HuggingFace, TextGenWebUI, CometAPI, and Private Mode.

**Q: Can I use AnythingLLM completely offline?**

Yes. Use a local LLM provider (Ollama, LM Studio, KoboldCPP, LocalAI, or Private Mode), the native embedding engine, the built-in LanceDB vector database, and PiperTTS for text-to-speech. No internet connection is required after initial setup.

**Q: What does the `STORAGE_DIR` environment variable do?**

`STORAGE_DIR` tells AnythingLLM where to store all persistent data — the SQLite database, uploaded documents, vector embeddings, downloaded models, plugins, and configuration. In Docker, this should always be `/app/server/storage` (which you mount to a host directory). It is the single most important configuration variable.

**Q: Can I change my LLM provider after initial setup?**

Yes. Go to *Settings → LLM Preference* and switch at any time. Existing chats are preserved. The new provider will be used for all future messages.

**Q: How do I completely reset AnythingLLM?**

Stop the container. Delete the entire host storage directory. Restart the container. You return to the onboarding wizard with a clean slate.

### Documents and RAG

**Q: What document types can I upload?**

PDF, DOCX, PPTX, XLSX/XLS, TXT, Markdown, HTML, EPUB, MBOX, CSV, JSON, YAML, XML, most source code files, audio files (MP3, WAV, M4A, FLAC, OGG, WebM), and images (via OCR).

**Q: How does RAG work in AnythingLLM?**

When you embed documents into a workspace, AnythingLLM chunks them into segments, converts each segment to a vector embedding, and stores them in the vector database. When you ask a question, AnythingLLM searches for the most relevant chunks, includes them as context in the LLM prompt, and the LLM generates an answer based on that context. Citations show which chunks were used.

**Q: What is the difference between embedding and pinning a document?**

Embedding chunks the document and stores vectors for similarity search — only the top-N most relevant chunks are included per query. Pinning forces the full document text into every LLM request, regardless of the query. Pinning is best for short reference documents; embedding is better for large collections.

**Q: Can I embed the same document into multiple workspaces?**

Yes. Upload it once to Document Management, then move copies to as many workspaces as you want. Each workspace gets its own vector representations.

**Q: How do I process scanned/image PDFs?**

Enable OCR in *Settings → Privacy & Data Handling*. AnythingLLM uses Tesseract.js for optical character recognition. Set `TARGET_OCR_LANG` if your documents are not in English.

**Q: Can I import content from Confluence?**

Yes. Use the Confluence data connector in Document Management. Note that Confluence instances with custom context paths may require the full URL (see Troubleshooting for GitHub issue #4678).

**Q: How do I update a document that has already been embedded?**

Use the **Watch** feature to auto-sync web-based sources. For file uploads, delete the old version from the workspace, re-upload the new file, and re-embed. There is no automatic update for local files.

**Q: What is the similarity threshold setting?**

In *Workspace Settings → Vector Database*, the similarity threshold controls how closely a document chunk must match your query to be included as context. Lower values mean stricter matching (fewer but more relevant results); higher values include more results with looser relevance. The default works well for most use cases.

### Agents

**Q: How do I invoke an agent?**

Prefix your message with `@agent`:

```text
@agent search the web for the latest Python 3.13 release notes
```

In **automatic** chat mode, the agent is invoked automatically when the LLM detects a tool is needed.

**Q: What agent skills are available by default?**

Three skills are enabled by default: **rag-memory** (search workspace docs), **doc-summarizer** (summarize documents or URLs), and **web-scraping** (fetch and parse web pages). Additional skills (web-browsing, SQL, filesystem, email, calendar, file creation) require explicit activation.

**Q: Can I auto-approve agent tool calls?**

Yes. Set the `AGENT_AUTO_APPROVED_SKILLS` environment variable to a comma-separated list of skill names. This bypasses the approval prompt for those specific skills. Alternatively, in the UI, toggle the auto-approval setting per skill.

**Q: How do I configure web search for agents?**

Go to *Settings → Agents → Web Search* and select a provider: SerpAPI, SearchAPI, Serper, Bing, Serply, SearXNG, Tavily, Exa, or Perplexity. Each requires its own API key.

**Q: Can I create custom agent skills?**

Yes, in three ways: (1) Build no-code Agent Flows with the visual builder, (2) import skills from the Community Hub, or (3) connect external tools via MCP servers.

**Q: What is MCP and how does it work with AnythingLLM?**

MCP (Model Context Protocol) is a standard for connecting LLM applications with external tool servers. AnythingLLM acts as an MCP host — you configure MCP servers in `plugins/anythingllm_mcp_servers.json`, and their tools automatically appear as agent skills. AnythingLLM supports stdio, SSE, and streamableHTTP MCP transport types.

### Multi-User and Security

**Q: What is the difference between single-user and multi-user mode?**

Single-user mode (default) has no login — one anonymous user accesses everything. Optionally, set `AUTH_TOKEN` for a simple password gate. Multi-user mode adds full authentication with individual accounts, role-based access (Admin, Manager, Default), per-workspace membership, and invite codes.

**Q: What are the user roles?**

- **Admin**: Full access to all settings, workspaces, users, and system configuration.
- **Manager**: Can create/edit workspaces, manage membership and invites, view chat logs. Cannot change LLM, embedder, or vector DB settings.
- **Default**: Can only use workspaces they are explicitly added to. No settings access.

**Q: How do I add new users?**

Generate invite codes in *Settings → Invitations*. Share the code with the new user. They sign up at the `/accept-invite/<code>` URL. Invites are one-time use and never expire unless revoked.

**Q: Does AnythingLLM support SSO?**

Yes. Set `SIMPLE_SSO_ENABLED=true` and configure `SIMPLE_SSO_NO_LOGIN_REDIRECT` to point to your Identity Provider. See the Admin Guide for full SSO configuration.

**Q: How do I enforce password complexity?**

Set environment variables: `PASSWORDMINCHAR` (default 8), `PASSWORDMAXCHAR`, `PASSWORDLOWERCASE`, `PASSWORDUPPERCASE`, `PASSWORDNUMERIC`, `PASSWORDSYMBOL`, `PASSWORDREQUIREMENTS`.

**Q: Is my data private?**

- All documents and vectors live in your storage directory on your host.
- Chats are stored in SQLite at `<STORAGE_DIR>/anythingllm.db`.
- Nothing goes to Mintplex Labs by default. Telemetry is anonymous event counts (no content, no IPs) and can be disabled.
- Your LLM provider does see your prompts. Use a local provider (Ollama, LM Studio, LocalAI, Private Mode) for absolute privacy.

### Integrations

**Q: How do I expose a workspace as a Telegram bot?**

Create a bot with `@BotFather` on Telegram, copy the token, paste it in *Settings → External Connections → Telegram Bot*, select a workspace, and click Start Bot. The bot connects via long-polling.

**Q: How does the mobile app connect?**

Go to *Settings → Mobile Connections*, generate a pairing QR code, and scan it from the AnythingLLM mobile app. The device is added to your approved list.

**Q: What is the browser extension API key format?**

Browser extension keys start with `brx-`. Generate them in *Settings → Browser Extension API Keys*. Do not confuse them with developer API keys.

**Q: Can I use the developer API to automate tasks?**

Yes. Generate an API key in *Settings → Developer API*. Authenticate with `Authorization: Bearer <key>`. The API supports workspace management, document upload, chat, streaming, user management, and more. Interactive Swagger docs are at `/api/docs`.

**Q: Does AnythingLLM have an OpenAI-compatible API?**

Yes. Endpoint at `/api/v1/openai/*`. Point any OpenAI SDK at this base URL with your AnythingLLM API key. Workspace slugs act as "model" names.

### Backups and Maintenance

**Q: How do I back up my AnythingLLM instance?**

Copy the entire host storage directory. It contains everything:
- `anythingllm.db` — SQLite database (users, workspaces, chats, settings)
- `documents/` — parsed document JSON
- `lancedb/` or equivalent — vector store data
- `models/` — downloaded embedder/Whisper models
- `plugins/` — MCP configs, imported agent skills
- `.env` — configuration

Restore by placing the directory back and starting a fresh container with the same volume mount.

**Q: How do I update to a new version?**

For Docker: pull the latest image and recreate the container:

```bash
docker pull mintplexlabs/anythingllm
docker stop anythingllm && docker rm anythingllm
# Re-run your docker run command with the same volume mounts
```

Your data persists because it lives on the mounted host volume.

**Q: How do I reset the database without losing documents?**

Run Prisma reset via the development scripts:

```bash
yarn prisma:reset
```

This truncates the database and re-migrates the schema. Your uploaded documents remain on disk, but all workspace configurations, chat history, and user accounts are lost.

> [!CAUTION]
> Database reset is irreversible. Back up your storage directory first.

**Q: Can I run multiple AnythingLLM instances sharing the same vector database?**

Yes, if you use an external vector database (Pinecone, Chroma, Weaviate, Qdrant, Milvus, Zilliz, PGVector, or Astra). The built-in LanceDB stores data locally and cannot be shared across instances.

**Q: What ports does AnythingLLM use?**

- **3001**: Main server (web UI + API)
- **8888**: Collector service (document processing)

Both are configurable via `SERVER_PORT` and `COLLECTOR_PORT` environment variables.

### Performance

**Q: How can I speed up document embedding?**

1. Use a GPU-accelerated embedding engine (Ollama on GPU, OpenAI, or another cloud provider).
2. Increase `OLLAMA_EMBEDDING_BATCH_SIZE` if using Ollama.
3. Reduce chunk size in text splitter settings (smaller chunks embed faster individually, though you get more of them).

**Q: How many documents can a workspace handle?**

There is no hard-coded limit. Performance depends on your vector database backend and hardware. LanceDB (built-in) handles moderate collections well. For very large document sets (100K+ chunks), consider switching to a dedicated vector database like Pinecone, Weaviate, or Milvus.

**Q: Does AnythingLLM support GPU acceleration?**

AnythingLLM itself does not directly use the GPU, but the LLM and embedding providers it connects to can. If you run Ollama, LM Studio, or LocalAI on a machine with a GPU, those providers use it automatically.

---

### Keyboard shortcuts

| Shortcut | Action |
|---|---|
| `Ctrl/Cmd + K` | Open keyboard shortcuts help |
| `Ctrl/Cmd + /` | Focus the chat input |
| `Ctrl/Cmd + Enter` | Send message |
| `Esc` | Cancel active generation |
| `Ctrl/Cmd + B` | Toggle sidebar |
| `Ctrl/Cmd + N` | New thread in current workspace |

Press `Ctrl+K` (or `Cmd+K`) at any time to see the full, up-to-date shortcut list.

---

### Where to go next

- **Admin / devs / architects** — the **Admin Guide** covers architecture, the full 559-key environment variable reference, deployment patterns (Kubernetes, Helm, bare metal, reverse proxy), security hardening, and internals.
- **Project home** — https://anythingllm.com/
- **GitHub** — https://github.com/Mintplex-Labs/anything-llm
- **Community Discord** — invite link on the project GitHub page
- **Upstream docs** — https://docs.anythingllm.com/

---

_Generated May 2026 from Mintplex-Labs/anything-llm at 649c942. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._