diff --git a/docs/features/authentication-access/rbac/groups.md b/docs/features/authentication-access/rbac/groups.md index ce077c3de..e6db919e6 100644 --- a/docs/features/authentication-access/rbac/groups.md +++ b/docs/features/authentication-access/rbac/groups.md @@ -84,3 +84,18 @@ For example, granting the "Marketing" group read access and a specific editor us * **Read**: Users can view and use the resource. * **Write**: Users can update or delete the resource. + +### Previewing Access (Audit) + +When access grants span many groups and resources, it's easy to lose track of who can see what. Open WebUI ships an admin-only **Preview Access** view that resolves every access grant for a specific user or group and lists the result in one place — no need to crawl through individual resource pages. + +**For a user** — In **Admin Panel > Users**, hover over a non-admin user row and click the eye-style **Preview Access** button. The modal shows every model, knowledge base, and tool the user can read, aggregated across all of their group memberships and any direct user grants. + +**For a group** — In **Admin Panel > Users > Groups**, open the group editor and use the **Preview Group Access** panel. The output is the same shape (models, knowledge, tools), scoped to just that group's grants. + +Both views are admin-only and read-only — they reflect what the access-grant table currently says without modifying it. Use them after a permission change to confirm the result matches intent, or as part of a periodic RBAC audit. + +Programmatic equivalents: + +- `GET /api/v1/users/{user_id}/preview` — user view (admin auth required) +- `GET /api/v1/groups/id/{id}/preview` — group view (admin auth required) diff --git a/docs/features/extensibility/plugin/tools/index.mdx b/docs/features/extensibility/plugin/tools/index.mdx index 1b4b354cf..05d5426ca 100644 --- a/docs/features/extensibility/plugin/tools/index.mdx +++ b/docs/features/extensibility/plugin/tools/index.mdx @@ -229,8 +229,10 @@ Default Mode is **not** a supported workaround even for DeepSeek — it is legac | `search_knowledge_bases` | Text search over KB names/descriptions. | | `query_knowledge_files` | Search file contents via the RAG retrieval pipeline (hybrid + rerank when enabled). Main tool for finding answers in docs. | | `search_knowledge_files` | Search files by filename. | -| `view_file` | Read a user-accessible file by ID with pagination (`offset`, `max_chars`). | +| `grep_knowledge_files` | Exact text / regex search across knowledge file content. Returns matching lines with line numbers. Complements `query_knowledge_files` (semantic) when you need literal matches. | +| `view_file` | Read a user-accessible file by ID with character pagination (`offset`, `max_chars`) or line range (`start_line`, `end_line`, optional `line_numbers`). | | `view_knowledge_file` | Read a knowledge-base file by ID with pagination (`offset`, `max_chars`). | +| `kb_exec` *(opt-in)* | Filesystem-style command interface for knowledge bases (`ls`, `tree`, `cat`, `head`, `tail`, `sed`, `grep`, `find`, `wc`, `stat`, with pipe support). Directory-aware: `ls docs/`, `tree`, `grep "x" docs/`, and path-based file refs (`docs/api/auth.md`). Replaces the discovery/read tools above when [`ENABLE_KB_EXEC`](/reference/env-configuration#enable_kb_exec) is set. | | **Image Gen** | *Requires image generation enabled (per-tool) AND per-chat "Image Generation" toggle enabled.* | | `generate_image` | Generates a new image based on a prompt. Requires `ENABLE_IMAGE_GENERATION`. | | `edit_image` | Edits existing images based on a prompt and image URLs. Requires `ENABLE_IMAGE_EDIT`. | @@ -287,12 +289,17 @@ Use this quick matrix instead of memorizing per-row caveats. | `query_knowledge_bases` | ❌ | ✅ | | `search_knowledge_files` | ✅ (auto-scoped) | ✅ (all accessible KBs) | | `query_knowledge_files` | ✅ (auto-scoped) | ✅ | +| `grep_knowledge_files` | ✅ (auto-scoped) | ✅ | | `view_file` | ✅ (when attached items include files/collections) | ❌ | | `view_knowledge_file` | ✅ (when attached items include files/collections) | ✅ | | `view_note` | ✅ (when attached items include notes) | ❌ | Quick rule: `list_knowledge` and `list_knowledge_bases` are mutually exclusive. +:::info `kb_exec` replaces the matrix when enabled +When [`ENABLE_KB_EXEC`](/reference/env-configuration#enable_kb_exec) is set, Open WebUI injects `kb_exec` instead of the file-oriented tools listed above. Still injected alongside it: `query_knowledge_files` (always), `view_note` (when notes are attached), and `query_knowledge_bases` + `search_knowledge_bases` (when no KB is attached). The model interacts with files through familiar shell commands. See the [Knowledge feature page](/features/workspace/knowledge#filesystem-style-access-kb_exec) for details. +::: + #### Tool Reference | Tool | Parameters | Output | @@ -307,8 +314,10 @@ Quick rule: `list_knowledge` and `list_knowledge_bases` are mutually exclusive. | `search_knowledge_bases` | `query` (required), `count` (default: 5), `skip` (default: 0) | Array of `{id, name, description, file_count}` | | `query_knowledge_files` | `query` (required), `knowledge_ids` (optional), `count` (default: 5) | Array of chunks like `{content, source, file_id, distance?}`; note hits include `{note_id, type: "note"}` | | `search_knowledge_files` | `query` (required), `knowledge_id` (optional), `count` (default: 5), `skip` (default: 0) | Array of `{id, filename, knowledge_id, knowledge_name}` | -| `view_file` | `file_id` (required), `offset` (default: 0), `max_chars` (default: 10000, cap: 100000) | `{id, filename, content, updated_at, created_at}` — includes `truncated`, `total_chars`, `next_offset` when paginated | +| `grep_knowledge_files` | `pattern` (required; regex auto-detected), `file_id` (optional — single-file mode), `case_insensitive` (default: false), `count_only` (default: false) | Matching lines with file IDs, filenames, and 1-indexed line numbers (capped at 50 matches) | +| `view_file` | `file_id` (required), `offset` (default: 0), `max_chars` (default: 10000, cap: 100000), `line_numbers` (default: false), `start_line` / `end_line` (optional — line-based addressing overrides `offset`/`max_chars`) | `{id, filename, content, updated_at, created_at}` — includes `truncated`, `total_chars`, `next_offset` when paginated, or `total_lines`, `showing_lines`, `next_start_line` in line mode | | `view_knowledge_file` | `file_id` (required), `offset` (default: 0), `max_chars` (default: 10000, cap: 100000) | `{id, filename, content, knowledge_id, knowledge_name}` — includes pagination metadata when truncated | +| `kb_exec` | `command` (required) — filesystem-style command: `ls` (root) / `ls /` / `ls -a` (flat with paths), `tree` / `tree /`, `cat -n `, `head -N `, `tail -N `, `sed -n ',p' `, `grep [-i\|-l\|-c] "" [/\|\|*.ext]`, `find [/] ""`, `wc `, `stat `; supports pipes (`grep "auth" \| head -5`); files referenced by path (`docs/api/auth.md`), filename, or file ID | Plain text command output (matches/listing/tree/file content as appropriate) | | **Image Gen** | | | | `generate_image` | `prompt` (required) | `{status, message, images}` — auto-displayed | | `edit_image` | `prompt` (required), `image_urls` (required) | `{status, message, images}` — auto-displayed | @@ -443,7 +452,7 @@ When the **Builtin Tools** capability is enabled, you can further control which | **Memory** | `search_memories`, `add_memory`, `replace_memory_content`, `delete_memory`, `list_memories` | Search and manage user memories | | **Chat History** | `search_chats`, `view_chat` | Search and view user chat history | | **Notes** | `search_notes`, `view_note`, `write_note`, `replace_note_content` | Search, view, and manage user notes | -| **Knowledge Base** | `list_knowledge`, `list_knowledge_bases`, `search_knowledge_bases`, `query_knowledge_bases`, `search_knowledge_files`, `query_knowledge_files`, `view_file`, `view_knowledge_file` | Browse and query knowledge bases | +| **Knowledge Base** | `list_knowledge`, `list_knowledge_bases`, `search_knowledge_bases`, `query_knowledge_bases`, `search_knowledge_files`, `query_knowledge_files`, `grep_knowledge_files`, `view_file`, `view_knowledge_file` (or `kb_exec` + `query_knowledge_files` + `view_note`/`query_knowledge_bases`/`search_knowledge_bases` as applicable when [`ENABLE_KB_EXEC`](/reference/env-configuration#enable_kb_exec) is set) | Browse and query knowledge bases | | **Web Search** | `search_web`, `fetch_url` | Search the web and fetch URL content | | **Image Generation** | `generate_image`, `edit_image` | Generate and edit images | | **Code Interpreter** | `execute_code` | Execute code in a sandboxed environment | diff --git a/docs/features/workspace/knowledge.md b/docs/features/workspace/knowledge.md index 1ba316d90..05adb0dbd 100644 --- a/docs/features/workspace/knowledge.md +++ b/docs/features/workspace/knowledge.md @@ -42,6 +42,7 @@ Attach specific knowledge bases to a model so it only searches what's relevant. | 📑 **5 extraction engines** | Tika, Docling, Azure, Mistral OCR, custom loaders | | 🤖 **Agentic retrieval** | Models browse, search, and read your documents autonomously | | 📄 **Full context mode** | Inject entire documents with no chunking | +| 🗂️ **Nested directories** | Organize files into subdirectories with drag-and-drop reordering | | 📦 **Export and API** | Back up knowledge bases as zip files, manage via REST API | --- @@ -76,12 +77,93 @@ With [native function calling](/features/extensibility/plugin/tools#tool-calling | `query_knowledge_bases` | ❌ | ✅ | Search KB names/descriptions by semantic similarity | | `search_knowledge_files` | ✅ (scoped) | ✅ (all) | Search files by filename | | `query_knowledge_files` | ✅ (scoped) | ✅ | Search file contents using the RAG pipeline | -| `view_file` | ✅ | ❌ | Read file content with pagination (default 10K chars, cap 100K) | +| `grep_knowledge_files` | ✅ (scoped) | ✅ | Exact text / regex search across knowledge files (returns matching lines with line numbers; auto-detects regex like `error|warn`) | +| `view_file` | ✅ | ❌ | Read file content with pagination (`offset`/`max_chars`) or by line range (`start_line`/`end_line`, optional `line_numbers`) | | `view_knowledge_file` | ✅ | ✅ | Read file content from any accessible KB | | `view_note` | ✅ | ❌ | Read attached notes | The key split: `list_knowledge` and `list_knowledge_bases` are mutually exclusive. Attaching a KB scopes the model to only those documents. Leaving it unscoped lets the model discover everything the user has access to. +#### When to prefer `grep_knowledge_files` over `query_knowledge_files` + +The two search tools complement each other: + +| | `query_knowledge_files` | `grep_knowledge_files` | +|---|---|---| +| **How it matches** | Semantic / vector retrieval (with optional BM25 + rerank when [`ENABLE_RAG_HYBRID_SEARCH`](/reference/env-configuration#enable_rag_hybrid_search) is on) | Exact string match — regex auto-detected (e.g. `error\|warn`, `version \d+`) | +| **Returns** | Relevant chunks of content | Matching lines with file ID, filename, and 1-indexed line number | +| **Use when** | "What does the documentation say about X?" — paraphrased questions, conceptual lookups | "Find every place we mention `OPENAI_API_KEY`" — literal identifiers, error strings, version numbers | +| **Result cap** | Top K (default 5) | 50 matches | +| **Flags** | — | `case_insensitive`, `count_only`, `file_id` (single-file mode) | + +In agentic flows, a typical pattern is: `query_knowledge_files` to locate the relevant document, then `grep_knowledge_files` to pinpoint exact lines, then `view_file` (line-range mode below) to read the surrounding context. + +#### Reading with `view_file` + +`view_file` supports two addressing modes: + +- **Character pagination** — `offset` + `max_chars` (default `10000`, hard cap `100000`). Best for streaming through a long document; the response includes `next_offset` when the file is truncated. +- **Line range** — `start_line` + optional `end_line` (1-indexed, inclusive). Overrides `offset`/`max_chars` when set; pairs naturally with `grep_knowledge_files`' line numbers. Pass `line_numbers: true` to also get a `: ` prefix on each returned line. + +The line-range response includes `total_lines`, `showing_lines`, and `next_start_line` for follow-up reads. + +### Filesystem-style access (`kb_exec`) + +When [`ENABLE_KB_EXEC=True`](/reference/env-configuration#enable_kb_exec) is set, Open WebUI exposes a `kb_exec` tool that gives the model a filesystem-style interface over knowledge bases. + +**Tools that go away**, because their function is now covered by `kb_exec` commands: + +- `list_knowledge` — replaced by `ls` +- `search_knowledge_files` — replaced by `find ""` +- `grep_knowledge_files` — replaced by `grep ""` +- `view_file` and `view_knowledge_file` — replaced by `cat`, `head`, `tail`, `sed -n ',p'` + +**Tools that stay injected alongside `kb_exec`**, because they do something `kb_exec` can't: + +- **`query_knowledge_files`** — semantic / RAG search (always) +- **`view_note`** — when notes are attached to the model (`kb_exec` is file-only, so notes need a dedicated reader) +- **`query_knowledge_bases`** and **`search_knowledge_bases`** — when no KB is attached to the model, so the model can still discover and search across knowledge bases by name/description + +This is experimental and **off by default**. It targets frontier models that already "think in shell" — they tend to chain `ls`, `grep`, and `cat` more reliably than they orchestrate a fan-out of specialized tools. + +**Supported commands** + +| Command | Purpose | +|---------|---------| +| `ls`, `ls /`, `ls -a` | List the current level / a subdirectory / a flat view of every file with full paths | +| `tree`, `tree /` | Recursive directory tree | +| `cat -n ` | Read a file (optionally with line numbers) | +| `head -N ` / `tail -N ` | First or last N lines | +| `sed -n ',p' ` | Print lines `` through `` | +| `grep "" [/\|\|*.ext]` | Exact / regex search; flags `-i` (case-insensitive), `-l` (filenames only), `-c` (counts) | +| `find [/] ""` | Find files by glob | +| `wc ` | Line / word / char counts | +| `stat ` | File metadata | + +**Pipes** + +`kb_exec` parses a single pipeline, so commands compose: + +```text +grep "auth" | head -5 +grep -l "TODO" docs/ +find docs/ "*.md" | head -10 +``` + +**File references** + +Files can be addressed three ways — pick whichever is unambiguous: + +- **Path** — `docs/api/auth.md` (relative to the knowledge base root; resolves through the directory tree) +- **Filename** — `auth.md` (errors with an "ambiguous filename" hint when the same name exists in multiple directories or KBs) +- **File ID** — the UUID returned by `ls`, `find`, or `grep` + +**Behavior notes** + +- `kb_exec` respects the same access control as the other knowledge tools — files the user can't read are silently excluded from results. +- The model still has `query_knowledge_files` for semantic search; reach for it when literal commands won't find a paraphrased concept. +- Built on top of the directory model — `kb_exec` is the only tool that fully reflects the directory structure created in the UI. + Autonomous exploration works best with frontier models that can intelligently chain search, browse, and synthesize. Smaller models may struggle with multi-step retrieval. Administrators can disable the **Knowledge Base** tool category per-model in **Workspace > Models > Edit > Builtin Tools**. For the full list of built-in agentic tools, see the [Native/Agentic Mode Tools Guide](/features/extensibility/plugin/tools#built-in-system-tools-nativeagentic-mode). @@ -104,6 +186,37 @@ When native function calling is enabled, attached knowledge is **not automatical 3. Upload files or add existing documents. 4. Attach the knowledge base to a model in **Workspace > Models > Edit**, or reference it in chat with `#`. +### Organizing into directories + +Knowledge bases support nested **directories** so larger document sets stay navigable. Create them from the **Add Content** menu (**+ New Directory**), then reorganize freely. + +**Creating and navigating** + +- **+ New Directory** lives next to file upload in the **Add Content** menu. Name uniqueness is enforced per parent — two siblings can't share a name, but you can reuse names in different parents. +- Click a directory to descend into it; the **breadcrumb trail** at the top of the view always reflects the current path and lets you jump back to any ancestor in one click. +- Directories can be **renamed** or **moved to a different parent** without affecting the files inside them. + +**Drag-and-drop** + +You can move items by dragging: + +- **Files** onto a directory row, into the empty area of an open directory, or onto any breadcrumb crumb (including the root crumb to send a file back to the top level). +- **Directories** onto another directory to nest them, or onto a breadcrumb crumb to move them up the tree. Moving a directory into itself or one of its descendants is blocked server-side. + +**Deletion semantics** + +Deleting a non-empty directory prompts for the action to take with its contents: + +- **Move files to parent** (default) — the directory is removed but its files and subdirectories are re-parented one level up. +- **Delete everything** — the directory and all files/subdirectories underneath it are permanently removed. + +**Effect on retrieval and tools** + +- **Retrieval and standard RAG** still span the entire knowledge base. Directories don't shard the vector index; chunks from any subdirectory remain reachable in a single search. +- **Agentic tools** are directory-aware: + - `kb_exec` (when enabled) treats subdirectories like a filesystem: `ls docs/`, `tree`, `grep "x" docs/`, and path-style refs (`docs/api/auth.md`) all work — see [Filesystem-Style Access (`kb_exec`)](#filesystem-style-access-kb_exec) below. + - The other knowledge tools (`query_knowledge_files`, `grep_knowledge_files`, `search_knowledge_files`) ignore directory boundaries and return matches from the whole KB. + ### Exporting Admins can export an entire knowledge base as a zip file via the item menu (three dots) > **Export**. Files are converted to `.txt` for universal compatibility. Regular users will not see the Export option. @@ -112,9 +225,19 @@ Admins can export an entire knowledge base as a zip file via the item menu (thre Knowledge bases can be managed programmatically: -- `POST /api/v1/files/` - Upload files -- `GET /api/v1/files/{id}/process/status` - Check processing status -- `POST /api/v1/knowledge/{id}/file/add` - Add files to a knowledge base +**Files** + +- `POST /api/v1/files/` — Upload files +- `GET /api/v1/files/{id}/process/status` — Check processing status +- `POST /api/v1/files/{id}/rename` — Rename a file +- `POST /api/v1/knowledge/{id}/file/add` — Add files to a knowledge base +- `POST /api/v1/knowledge/{id}/file/move` — Move a file between directories within the same KB (body: `file_id`, `directory_id` — `null` moves to the KB root) + +**Directories** + +- `POST /api/v1/knowledge/{id}/dirs/create` — Create a directory (body: `name`, optional `parent_id`) +- `POST /api/v1/knowledge/{id}/dirs/{dir_id}/update` — Rename or re-parent a directory (body: `name` and/or `parent_id`) +- `DELETE /api/v1/knowledge/{id}/dirs/{dir_id}/delete?move_files=true` — Delete a directory. With `move_files=true` (default), contained files are re-parented; with `move_files=false`, they're deleted along with the directory. File processing happens asynchronously. You must poll the status endpoint until processing completes before adding files to a knowledge base, or you'll get an "empty content" error. See [API Endpoints](/reference/api-endpoints#-retrieval-augmented-generation-rag) for workflow examples. diff --git a/docs/getting-started/quick-start/tab-docker/DockerCompose.md b/docs/getting-started/quick-start/tab-docker/DockerCompose.md index 8b88d3ac4..b7bd492f3 100644 --- a/docs/getting-started/quick-start/tab-docker/DockerCompose.md +++ b/docs/getting-started/quick-start/tab-docker/DockerCompose.md @@ -56,9 +56,15 @@ To start your services, run the following command: docker compose up -d ``` -## Helper Script +## Helper Scripts -A useful helper script called `run-compose.sh` is included with the codebase. This script assists in choosing which Docker Compose files to include in your deployment, streamlining the setup process. +A set of helper scripts is included with the codebase to streamline common Docker workflows: + +- `docker-compose-launcher.sh` — Interactive Compose launcher with GPU auto-detection, configurable WebUI/API ports, host data mounts, and optional Playwright support. Run `./docker-compose-launcher.sh --help` for the full list of flags. Use `--drop` to tear down the project. +- `docker-cleanup.sh` — Stops the Compose project and **deletes all volumes**, including persistent data. Prompts for confirmation before destroying data. +- `docker-run.sh` — Builds the Open WebUI image and runs a single container, exposing it on `OPEN_WEBUI_PORT` (default `3000`). +- `docker-ollama.sh` — Pulls and runs the official Ollama container with optional GPU passthrough, exposing it on `OLLAMA_PORT` (default `11434`). +- `docker-update-models.sh` — Iterates through every model installed in the Ollama container and pulls the latest version. --- diff --git a/docs/getting-started/quick-start/tab-docker/ManualDocker.md b/docs/getting-started/quick-start/tab-docker/ManualDocker.md index b944625d4..8825dedf2 100644 --- a/docs/getting-started/quick-start/tab-docker/ManualDocker.md +++ b/docs/getting-started/quick-start/tab-docker/ManualDocker.md @@ -49,9 +49,9 @@ Visit [http://localhost:3000](http://localhost:3000). For production environments, pin a specific version instead of using floating tags: ```bash -docker pull ghcr.io/open-webui/open-webui:v0.9.5 -docker pull ghcr.io/open-webui/open-webui:v0.9.5-cuda -docker pull ghcr.io/open-webui/open-webui:v0.9.5-ollama +docker pull ghcr.io/open-webui/open-webui:v0.9.6 +docker pull ghcr.io/open-webui/open-webui:v0.9.6-cuda +docker pull ghcr.io/open-webui/open-webui:v0.9.6-ollama ``` --- diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index 68a118ccd..7b9000e04 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -31,9 +31,9 @@ The `:main` tag always points to the **latest build**. It's convenient but can i For stability, pin a specific release tag: ``` -ghcr.io/open-webui/open-webui:v0.9.5 -ghcr.io/open-webui/open-webui:v0.9.5-cuda -ghcr.io/open-webui/open-webui:v0.9.5-ollama +ghcr.io/open-webui/open-webui:v0.9.6 +ghcr.io/open-webui/open-webui:v0.9.6-cuda +ghcr.io/open-webui/open-webui:v0.9.6-ollama ``` Browse all available tags on the [GitHub releases page](https://github.com/open-webui/open-webui/releases). diff --git a/docs/reference/database-schema.md b/docs/reference/database-schema.md index 8b5ab256e..464ba831a 100644 --- a/docs/reference/database-schema.md +++ b/docs/reference/database-schema.md @@ -10,7 +10,7 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: > [!WARNING] -> This documentation reflects schema changes up to Open WebUI v0.9.5. +> This documentation reflects schema changes up to Open WebUI v0.9.6. ## Open-WebUI Internal SQLite Database diff --git a/docs/reference/env-configuration.mdx b/docs/reference/env-configuration.mdx index 8b1da35e9..5842e41b8 100644 --- a/docs/reference/env-configuration.mdx +++ b/docs/reference/env-configuration.mdx @@ -12,23 +12,23 @@ As new variables are introduced, this page will be updated to reflect the growin :::info -This page is up-to-date with Open WebUI release version [v0.9.5](https://github.com/open-webui/open-webui/releases/tag/v0.9.5), but is still a work in progress to later include more accurate descriptions, listing out options available for environment variables, defaults, and improving descriptions. +This page is up-to-date with Open WebUI release version [v0.9.6](https://github.com/open-webui/open-webui/releases/tag/v0.9.6), but is still a work in progress to later include more accurate descriptions, listing out options available for environment variables, defaults, and improving descriptions. ::: -### Important Note on `PersistentConfig` Environment Variables +### Important Note on `ConfigVar` Environment Variables :::note -When launching Open WebUI for the first time, all environment variables are treated equally and can be used to configure the application. However, for environment variables marked as `PersistentConfig`, their values are persisted and stored internally. +When launching Open WebUI for the first time, all environment variables are treated equally and can be used to configure the application. However, for environment variables marked as `ConfigVar`, their values are persisted and stored internally. -After the initial launch, if you restart the container, `PersistentConfig` environment variables will no longer use the external environment variable values. Instead, they will use the internally stored values. +After the initial launch, if you restart the container, `ConfigVar` environment variables will no longer use the external environment variable values. Instead, they will use the internally stored values. In contrast, regular environment variables will continue to be updated and applied on each subsequent restart. -You can update the values of `PersistentConfig` environment variables directly from within Open WebUI, and these changes will be stored internally. This allows you to manage these configuration settings independently of the external environment variables. +You can update the values of `ConfigVar` environment variables directly from within Open WebUI, and these changes will be stored internally. This allows you to manage these configuration settings independently of the external environment variables. -Please note that `PersistentConfig` environment variables are clearly marked as such in the documentation below, so you can be aware of how they will behave. +Please note that `ConfigVar` environment variables are clearly marked as such in the documentation below, so you can be aware of how they will behave. To disable this behavior and force Open WebUI to always use your environment variables (ignoring the database), set `ENABLE_PERSISTENT_CONFIG` to `False`. @@ -44,7 +44,7 @@ If you change an environment variable (like `ENABLE_SIGNUP=True`) but don't see Set `ENABLE_PERSISTENT_CONFIG=False` in your environment. This forces Open WebUI to read your variables directly. Note that UI-based settings changes will not persist across restarts in this mode. #### Option 2: Update via Admin UI (Recommended) -The simplest and safest way to change `PersistentConfig` settings is directly through the **Admin Panel** within Open WebUI. Even if an environment variable is set, changes made in the UI will take precedence and be saved to the database. +The simplest and safest way to change `ConfigVar` settings is directly through the **Admin Panel** within Open WebUI. Even if an environment variable is set, changes made in the UI will take precedence and be saved to the database. #### Option 3: Manual Database Update (Last Resort / Lock-out Recovery) If you are locked out or cannot access the UI, you can manually update the SQLite database via Docker: @@ -78,7 +78,7 @@ environment variables, see our [logging documentation](https://docs.openwebui.co - Type: `str` - Default: `http://localhost:3000` - Description: Specifies the URL where your Open WebUI installation is reachable. Needed for search engine support and OAuth/SSO. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. :::warning @@ -97,7 +97,7 @@ Failure to set WEBUI_URL before using OAuth/SSO will result in failure to log in - Type: `bool` - Default: `True` - Description: Toggles user account creation. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_SIGNUP_PASSWORD_CONFIRMATION` @@ -148,14 +148,14 @@ After the admin account is created, sign-up is automatically disabled for securi - Type: `bool` - Default: `True` - Description: Toggles email, password, sign-in and "or" (only when `ENABLE_OAUTH_SIGNUP` is set to True) elements. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_PASSWORD_CHANGE_FORM` - Type: `bool` - Default: `True` - Description: Controls visibility of the password change UI in **Settings > Account**. When set to `False`, users do not see the password update form, which is useful for SSO-focused deployments where password changes should not be presented in the UI. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_PASSWORD_AUTH` @@ -181,14 +181,14 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - Type: `str` - Default: `en` - Description: Sets the default locale for the application. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `DEFAULT_MODELS` - Type: `str` - Default: Empty string (' '), since `None`. - Description: Sets a default Language Model. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `DEFAULT_PINNED_MODELS` @@ -196,14 +196,14 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - Default: Empty string (' ') - Description: Comma-separated list of model IDs to pin by default for new users who haven't customized their pinned models. This provides a pre-selected set of frequently used models in the model selector for new accounts. - Example: `gpt-4,claude-3-opus,llama-3-70b` -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `DEFAULT_MODEL_METADATA` - Type: `dict` (JSON object) - Default: `{}` - Description: Sets global default metadata (capabilities and other model info) for all models. These defaults act as a baseline — per-model overrides always take precedence. For capabilities, the defaults and per-model values are merged (per-model wins on conflicts). For other metadata fields, the default is only applied if the model has no value set. Configurable via **Admin Settings → Models**. -- Persistence: This environment variable is a `PersistentConfig` variable. Stored at config key `models.default_metadata`. +- Persistence: This environment variable is a `ConfigVar` variable. Stored at config key `models.default_metadata`. :::info @@ -220,7 +220,7 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - Type: `dict` (JSON object) - Default: `{}` - Description: Sets global default parameters (temperature, top_p, max_tokens, seed, etc.) for all models. These defaults are applied as a baseline at chat completion time — per-model parameter overrides always take precedence. Configurable via **Admin Settings → Models**. -- Persistence: This environment variable is a `PersistentConfig` variable. Stored at config key `models.default_params`. +- Persistence: This environment variable is a `ConfigVar` variable. Stored at config key `models.default_params`. :::info @@ -240,14 +240,14 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - `admin` - New users are automatically activated with administrator permissions. - Default: `pending` - Description: Sets the default role assigned to new users. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `DEFAULT_GROUP_ID` - Type: `str` - Default: Empty string (' ') - Description: Sets the default group ID to assign to new users upon registration. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `DEFAULT_GROUP_SHARE_PERMISSION` @@ -261,63 +261,63 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - Type: `str` - Default: Empty string (' ') - Description: Sets a custom title for the pending user overlay. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `PENDING_USER_OVERLAY_CONTENT` - Type: `str` - Default: Empty string (' ') - Description: Sets a custom text content for the pending user overlay. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_CALENDAR` - Type: `bool` - Default: `True` - Description: Enables or disables the Calendar feature. When enabled, users can create calendars, manage events, and share calendars with other users or groups via access grants. Active automations are automatically surfaced as virtual events on a dedicated "Scheduled Tasks" calendar. Requires the `features.calendar` user permission (admins always pass). -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_CHANNELS` - Type: `bool` - Default: `False` - Description: Enables or disables channel support. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_FOLDERS` - Type: `bool` - Default: `True` - Description: Enables or disables the folders feature, allowing users to organize their chats into folders in the sidebar. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `FOLDER_MAX_FILE_COUNT` - Type: `int` - Default: `("") empty string` - Description: Sets the maximum number of files processing allowed per folder. -- Persistence: This environment variable is a `PersistentConfig` variable. It can be configured in the **Admin Panel > Settings > General > Folder Max File Count**. Default is none (empty string) which is unlimited. +- Persistence: This environment variable is a `ConfigVar` variable. It can be configured in the **Admin Panel > Settings > General > Folder Max File Count**. Default is none (empty string) which is unlimited. #### `ENABLE_AUTOMATIONS` - Type: `bool` - Default: `True` - Description: Enables or disables the Automations feature globally. When disabled, the scheduler skips automation processing, the automation API endpoints return `403 Forbidden`, automation builtin tools are not injected, and the Automations entry is hidden from the sidebar. Requires the `features.automations` user permission (admins always pass). -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `AUTOMATION_MAX_COUNT` - Type: `int` - Default: `("") empty string` (unlimited) - Description: Sets the maximum number of automations a non-admin user can create. When set to a positive integer, users who reach this limit will receive a `403 Forbidden` error when attempting to create additional automations. Admins bypass this limit. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `AUTOMATION_MIN_INTERVAL` - Type: `int` (seconds) - Default: `("") empty string` (no minimum) - Description: Sets the minimum allowed interval in seconds between automation recurrences for non-admin users. When set, any automation schedule that recurs more frequently than this value will be rejected with a `400 Bad Request` error. One-time automations (`COUNT=1`) are exempt from this check. Admins bypass this limit. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. :::tip Common values for AUTOMATION_MIN_INTERVAL @@ -347,20 +347,20 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - Type: `bool` - Default: `True` - Description: Enables or disables the notes feature, allowing users to create and manage personal notes within Open WebUI. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_MEMORIES` - Type: `bool` - Default: `True` - Description: Enables or disables the [memory feature](/features/chat-conversations/memory), allowing models to store and retrieve long-term information about users. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `WEBHOOK_URL` - Type: `str` - Description: Sets a webhook for integration with Discord/Slack/Microsoft Teams. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. :::note Admin posture toggles vs. security boundaries @@ -416,14 +416,14 @@ Treat anything in this cluster as *what the admin sees and does in the product U - Type: `bool` - Default: `False` - Description: Enables or disables user webhooks. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `RESPONSE_WATERMARK` - Type: `str` - Default: Empty string (' ') - Description: Sets a custom text that will be included when you copy a message in the chat. e.g., `"This text is AI generated"` -> will add "This text is AI generated" to every message, when copied. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `IFRAME_CSP` @@ -454,21 +454,21 @@ If you are running larger instances, you WILL NEED to set this to a higher value - Type: `bool` - Default: `True` - Description: Toggles whether to show admin user details in the interface. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_PUBLIC_ACTIVE_USERS_COUNT` - Type: `bool` - Default: `True` - Description: Controls whether the active user count is visible to all users or restricted to administrators only. When set to `False`, only admin users can see how many users are currently active, reducing backend load and addressing privacy concerns in large deployments. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENABLE_USER_STATUS` - Type: `bool` - Default: `True` - Description: Globally enables or disables user status functionality. When disabled, the status UI (including blinking active/away indicators and status messages) is hidden across the application, and user status API endpoints are restricted. -- Persistence: This environment variable is a `PersistentConfig` variable. It can be toggled in the **Admin Panel > Settings > General > User Status**. +- Persistence: This environment variable is a `ConfigVar` variable. It can be toggled in the **Admin Panel > Settings > General > User Status**. #### `ENABLE_EASTER_EGGS` @@ -480,7 +480,7 @@ If you are running larger instances, you WILL NEED to set this to a higher value - Type: `str` - Description: Sets the admin email shown by `SHOW_ADMIN_DETAILS` -- Persistence: This environment variable is a `PersistentConfig` variable. +- Persistence: This environment variable is a `ConfigVar` variable. #### `ENV` @@ -566,13 +566,13 @@ Enabling `ENABLE_REALTIME_CHAT_SAVE` causes every single token generated by the - Type: `bool` - Default: `True` -- Description: Controls whether the user and model profile-image endpoints honor an external `http(s)://` URL stored in `profile_image_url` by issuing a `302 Found` redirect to the original origin. When `False`, the redirect is suppressed and the endpoint falls through to the bundled default image instead. Set to `False` to prevent client-side IP, User-Agent, and Referer leaks to attacker-controlled origins via attacker-stored profile URLs (data URIs and same-origin/static images continue to load normally). Existing deployments that legitimately rely on external profile image URLs (e.g. Gravatar redirects served by upstream identity providers) should keep the default. **This variable is read once at startup — it is not a `PersistentConfig` and cannot be changed from the Admin UI.** +- Description: Controls whether the user and model profile-image endpoints honor an external `http(s)://` URL stored in `profile_image_url` by issuing a `302 Found` redirect to the original origin. When `False`, the redirect is suppressed and the endpoint falls through to the bundled default image instead. Set to `False` to prevent client-side IP, User-Agent, and Referer leaks to attacker-controlled origins via attacker-stored profile URLs (data URIs and same-origin/static images continue to load normally). Existing deployments that legitimately rely on external profile image URLs (e.g. Gravatar redirects served by upstream identity providers) should keep the default. **This variable is read once at startup — it is not a `ConfigVar` and cannot be changed from the Admin UI.** #### `PROFILE_IMAGE_ALLOWED_MIME_TYPES` - Type: `str` (comma-separated MIME types) - Default: `image/png,image/jpeg,image/gif,image/webp` -- Description: Allowlist of MIME types accepted when serving a base64 `data:` URI as a profile image. The MIME type is parsed from the data URI prefix and checked against this list before the response is streamed; non-allowlisted types fall through to the bundled default image. Responses also set `X-Content-Type-Options: nosniff` to prevent the browser from sniffing the body into an executable type. SVG is intentionally not in the default list because it can carry inline `