centersl/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-03-27 13:28:37 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1058 from Classic298/dev

Browse Source
This commit is contained in:
Classic298
2026-02-13 00:51:27 +01:00
committed by GitHub
parent 05cef7d75d 1e543ab28d
commit ce0db239b2
25 changed files with 900 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/features/auth/sso/index.mdx
View File

@@ -104,6 +104,39 @@ The following environment variables are required:
1. `MICROSOFT_REDIRECT_URI` - The redirect URI configured in your Microsoft OAuth application. This must be set to `<open-webui>/oauth/microsoft/callback`.
1. `OPENID_PROVIDER_URL` - Must be set for logout to work properly.
#### Token Refresh (`offline_access`)
By default, Microsoft's identity platform only returns an `access_token`, which expires after approximately 1 hour. To enable automatic token refresh — preventing users from needing to re-authenticate — add the `offline_access` scope:
```
MICROSOFT_OAUTH_SCOPE=openid email profile offline_access
```
The `offline_access` scope instructs Microsoft to also return a **refresh token**, which Open WebUI's server-side session middleware uses to automatically obtain new access tokens before they expire.
:::warning Symptoms of Missing `offline_access`
Without `offline_access`, you may see repeated log warnings after users have been logged in for more than 1 hour:
```
WARNING | No refresh token available for session xxx
WARNING | Token refresh failed for user xxx, deleting session
```
Basic chat functionality (which uses Open WebUI's JWT) is **not** affected, but the following features **will** fail:
- MCP tool servers using `auth_type: "system_oauth"`
- OneDrive / SharePoint file access
- Automatic profile picture refresh from Microsoft
:::
:::tip
No additional configuration is required in Microsoft Entra ID. The `offline_access` scope is [available by default](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc#openid-connect-scopes) for web applications with client secrets.
:::
### Github
To configure a Github OAuth Client, please refer to [Github's documentation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps) on how to create a OAuth App or Github App for a **web application**.

75
docs/features/chat-features/code-execution/index.md
View File

@@ -15,4 +15,79 @@ Open WebUI offers powerful code execution capabilities directly within your chat
- **Interactive Artifacts**: Generate and interact with rich content like HTML websites, SVG graphics, and JavaScript visualizations directly within your conversations.
- **Open Terminal**: Connect a remote shell execution API as a tool for full OS-level access — run any command, install packages, and manage files inside an isolated Docker container.
These execution capabilities bridge the gap between conversation and implementation, allowing you to explore ideas, analyze data, and create visual content seamlessly while chatting with AI models.
## Choosing a Code Execution Backend
Open WebUI supports multiple code execution backends, each suited to different use cases. The right choice depends on what you need — lightweight browser-based execution, a full Python environment, or unrestricted shell access.
### Pyodide (Default)
Pyodide runs Python in the browser via WebAssembly. It is sandboxed and safe for multi-user environments, but comes with constraints:
- **No persistent storage** — the filesystem resets between executions.
- **Limited library support** — only a subset of Python packages are available. Libraries that rely on C extensions or system calls may not work.
- **No shell access** — cannot run shell commands, install packages, or interact with the OS.
:::tip
Pyodide works well for **text analysis, hash computation, chart generation**, and other self-contained tasks. Chart libraries like matplotlib produce base64-encoded images that Open WebUI automatically captures, uploads as files, and injects direct image links into the output — so models can display charts directly in chat without any extra setup.
:::
### Jupyter
Jupyter provides a full Python environment and can handle virtually any task — file creation, package installation, and complex library usage. However, it has significant drawbacks in shared deployments:
- **Shared environment** — all users share the same Python runtime and filesystem.
- **Not sandboxed by default** — without careful configuration, users can access system resources or read other users' data.
- **Not designed for multi-tenant use** — Jupyter was built for single-user workflows.
:::warning
If you are running a multi-user or organizational deployment, **Jupyter is not recommended** as the code execution backend. Open WebUI's Jupyter integration connects to a single shared instance with no per-user isolation. Jupyter is best suited for **single-user, development, or trusted-user setups** only.
:::
### Open Terminal
[Open Terminal](/features/open-terminal) is a lightweight API for running shell commands remotely inside a Docker container. It provides full OS-level access — any language, any tool, any shell command — with container-level isolation.
- **Full shell access** — models can install packages, run scripts in any language, use system tools like ffmpeg, git, curl, etc.
- **Container isolation** — runs in its own Docker container, separate from Open WebUI and other services.
- **Rich pre-installed toolset** — the Docker image comes with Python 3.12, data science libraries, build tools, networking utilities, and more.
Open Terminal is connected to Open WebUI as an easy to connect [OpenAPI Tool Server](/features/plugin/tools/openapi-servers/open-webui), not as a built-in code execution engine.
:::note
Open Terminal currently operates as a **single shared instance** — there is no automatic per-user container provisioning yet. Each user connects to the same container unless separate instances are deployed manually.
:::
### Comparison
| Consideration | Pyodide | Jupyter | Open Terminal |
| :--- | :--- | :--- | :--- |
| **Runs in** | Browser (WebAssembly) | Server (Python kernel) | Server (Docker container) |
| **Library support** | Limited subset | Full Python ecosystem | Full OS — any language, any tool |
| **Shell access** | ❌ None | ⚠️ Limited | ✅ Full shell |
| **File persistence** | ❌ Resets each execution | ✅ Shared filesystem | ✅ Container filesystem (until removal) |
| **Isolation** | ✅ Browser sandbox | ❌ Shared environment | ✅ Container-level (when using Docker) |
| **Multi-user safety** | ✅ Per-user by design | ⚠️ Not isolated | ⚠️ Single instance (per-user containers planned) |
| **File generation** | ❌ Very limited | ✅ Full support | ✅ Full support with upload/download |
| **Setup** | None (built-in) | Admin configures globally | Each user adds as a Tool Server |
| **Recommended for orgs** | ✅ Safe default | ❌ Not without isolation | ✅ Per-user by design |
| **Enterprise scalability** | ✅ Client-side, no server load | ❌ Single shared instance | ⚠️ Manual per-user instances |
:::tip On the Roadmap: Terminal Manager for Multi-Tenant Deployments
For organizational and enterprise deployments, a **Terminal Manager** service is being explored that could automatically provision and manage per-user Docker containers. This would potentially:
- Spin up isolated Open Terminal containers on demand, one per user
- Route requests to the correct container based on user identity
- Enforce resource limits (CPU, memory) per container
- Automatically shut down idle containers (e.g., after 30 minutes of inactivity)
- Clean up containers that haven't been used for a configurable period (e.g., 1 week)
The idea is to configure this in the admin panel by adding a connection to a Terminal Manager (URL + API key), similar to how Jupyter is configured today. Individual users and self-hosters would continue using Open Terminal directly as a tool without needing the manager.
This feature is on the roadmap but no timeline has been announced. Follow the [Open Terminal repository](https://github.com/open-webui/open-terminal) for updates.
:::

2
docs/features/chat-features/code-execution/python.md
View File

@@ -52,7 +52,7 @@ For Jupyter configuration, see the [Jupyter Notebook Integration](/tutorials/int
### Native Function Calling (Native Mode)
When using **Native function calling mode** with a capable model (e.g., GPT-5, Claude 4.5, MiniMax M2.1), the code interpreter is available as a builtin tool called `execute_code`. This provides a more integrated experience:
When using **Native function calling mode** with a capable model (e.g., GPT-5, Claude 4.5, MiniMax M2.5), the code interpreter is available as a builtin tool called `execute_code`. This provides a more integrated experience:
- **No XML tags required**: The model calls `execute_code(code)` directly
- **Same image handling**: Base64 image URLs in output are replaced with file URLs; model embeds via markdown

1
docs/features/chat-features/index.mdx
View File

@@ -26,3 +26,4 @@ Open WebUI provides a comprehensive set of chat features designed to enhance you
- **[🧠 Reasoning & Thinking Models](./reasoning-models.mdx)**: Specialized support for models that generate internal chains of thought using thinking tags.
- **[💬 Follow-Up Prompts](./follow-up-prompts.md)**: Automatic generation of suggested follow-up questions after model responses.
- **Skill Mentions**: Use `$` in the chat input to mention and activate [Skills](/features/workspace/skills) on-the-fly, injecting their manifests into the conversation.

2
docs/features/memory.mdx
View File

@@ -44,7 +44,7 @@ Autonomous memory management works best with frontier models (GPT-5, Claude 4.5+
1. **Administrative Enablement**: Ensure the Memory feature is [enabled globally](#administrative-controls) by an administrator and that you have the required permissions.
2. **Native Mode (Agentic Mode)**: Enable **Native Function Calling** in the model's advanced parameters (**Admin Panel > Settings > Models > Model Specific Settings > Advanced Parameters**).
3. **Quality Models Required**: To unlock these features effectively, use frontier models with strong reasoning capabilities (e.g., GPT-5, Claude 4.5 Sonnet, Gemini 3 Flash, MiniMax M2.1) for the best experience. Small local models may not effectively manage memories autonomously.
3. **Quality Models Required**: To unlock these features effectively, use frontier models with strong reasoning capabilities (e.g., GPT-5, Claude 4.5 Sonnet, Gemini 3 Flash, MiniMax M2.5) for the best experience. Small local models may not effectively manage memories autonomously.
4. **Per-Model Category Toggle**: Ensure the **Memory** category is enabled for the model in **Workspace > Models > Edit > Builtin Tools** (enabled by default).
:::info Central Tool Documentation

256
docs/features/open-terminal/index.md Normal file
View File

@@ -0,0 +1,256 @@
---
sidebar_position: 5
title: "Open Terminal"
---
# ⚡ Open Terminal
:::info
This page is up-to-date with Open Terminal release version [v0.1.10](https://github.com/open-webui/open-terminal).
:::
## Overview
[Open Terminal](https://github.com/open-webui/open-terminal) is a lightweight API for running shell commands remotely — with real-time streaming and secure access. When connected to Open WebUI as a [Tool](/features/plugin/tools), it gives models full shell access, file management, and the ability to execute arbitrary commands in an isolated environment.
Unlike Pyodide (browser-based, limited libraries) or Jupyter (shared environment, no per-user isolation), Open Terminal runs in its own Docker container with full OS-level capabilities. This makes it ideal for tasks that require:
- Installing and running any software package or language
- Working with system tools like ffmpeg, pandoc, git, etc.
- Running multi-step build, analysis, or data processing pipelines
- Managing files with upload and download support
:::warning
Open Terminal provides **unrestricted shell access** to the environment it runs in. In production deployments, always run it inside a Docker container with appropriate resource limits. Never run it on bare metal in a shared or untrusted environment.
:::
## Getting Started
### Docker (Recommended)
```bash
docker run -d --name open-terminal --restart unless-stopped -p 8000:8000 -e OPEN_TERMINAL_API_KEY=your-secret-key ghcr.io/open-webui/open-terminal
```
If no API key is provided, one is auto-generated and printed on startup (`docker logs open-terminal`).
The Docker image is based on Python 3.12 and comes pre-installed with a rich set of tools:
| Category | Included |
| :--- | :--- |
| **Core utilities** | coreutils, findutils, grep, sed, gawk, diffutils, patch, less, file, tree, bc |
| **Networking** | curl, wget, net-tools, iputils-ping, dnsutils, netcat, socat, telnet, openssh-client, rsync |
| **Editors** | vim, nano |
| **Version control** | git |
| **Build tools** | build-essential, cmake, make |
| **Languages** | Python 3.12, Perl, Ruby, Lua 5.4 |
| **Data processing** | jq, xmlstarlet, sqlite3 |
| **Compression** | zip, unzip, tar, gzip, bzip2, xz, zstd, p7zip |
| **System** | procps, htop, lsof, strace, sysstat, sudo, tmux, screen |
| **Python libraries** | numpy, pandas, scipy, scikit-learn, matplotlib, seaborn, plotly, jupyter, ipython, requests, beautifulsoup4, lxml, sqlalchemy, psycopg2, pyyaml, toml, jsonlines, tqdm, rich |
### Build from Source
```bash
docker build -t open-terminal .
docker run -p 8000:8000 open-terminal
```
### pip Install (Bare Metal)
```bash
pip install open-terminal
open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key
```
:::warning
Running bare metal gives the model shell access to your actual machine. Only use this for local development or testing.
:::
### Docker Compose (with Open WebUI)
```yaml title="docker-compose.yml"
services:
open-webui:
image: ghcr.io/open-webui/open-webui:latest
container_name: open-webui
ports:
- "3000:8080"
volumes:
- open-webui:/app/backend/data
open-terminal:
image: ghcr.io/open-webui/open-terminal
container_name: open-terminal
ports:
- "8000:8000"
environment:
- OPEN_TERMINAL_API_KEY=your-secret-key
deploy:
resources:
limits:
memory: 2G
cpus: "2.0"
volumes:
open-webui:
```
## Configuration
| CLI Option | Default | Environment Variable | Description |
| :--- | :--- | :--- | :--- |
| `--host` | `0.0.0.0` | — | Bind address |
| `--port` | `8000` | — | Bind port |
| `--api-key` | Auto-generated | `OPEN_TERMINAL_API_KEY` | Bearer API key for authentication |
When no API key is provided, Open Terminal generates a random key using a cryptographically secure token and prints it to the console on startup.
## Connecting to Open WebUI
Open Terminal is a FastAPI application and automatically exposes an OpenAPI specification at `/openapi.json`. This means it works out of the box as an [OpenAPI Tool Server](/features/plugin/tools/openapi-servers/open-webui) — no manual tool creation required.
- **As a User Tool Server**: Add it in **Settings → Tools** to connect directly from your browser. Ideal for personal or local instances.
- **As a Global Tool Server**: Add it in **Admin Settings → Tools** to make it available to all users across the deployment.
For step-by-step instructions with screenshots, see the [OpenAPI Tool Server Integration Guide](/features/plugin/tools/openapi-servers/open-webui).
## API Reference
All endpoints except `/health` and temporary download/upload links require Bearer token authentication.
Interactive API documentation (Swagger UI) is available at `http://localhost:8000/docs` when the server is running.
### Execute a Command
**`POST /execute`**
Runs a shell command and returns the result. Supports pipes, chaining (`&&`, `||`, `;`), and redirections.
:::tip
The `/execute` endpoint description in the OpenAPI spec automatically includes live system metadata — OS, hostname, current user, default shell, Python version, and working directory. When Open WebUI discovers this tool via the OpenAPI spec, models see this context in the tool description and can adapt their commands accordingly.
:::
**Request body:**
| Field | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `command` | string | (required) | Shell command to execute |
| `timeout` | number | `30` | Max execution time in seconds. Process is killed if exceeded. Set to `null` to disable. |
**Query parameter:**
| Parameter | Default | Description |
| :--- | :--- | :--- |
| `stream` | `false` | If `true`, stream output as JSONL instead of waiting for completion |
**Synchronous response:**
```bash
curl -X POST http://localhost:8000/execute \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-d '{"command": "echo hello"}'
```
```json
{"exit_code": 0, "stdout": "hello\n", "stderr": ""}
```
Exit code `-1` indicates the command was killed due to timeout.
**Streaming response:**
```bash
curl -X POST "http://localhost:8000/execute?stream=true" \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-d '{"command": "for i in 1 2 3; do echo $i; sleep 1; done"}'
```
Streams as JSONL (`application/x-ndjson`):
```jsonl
{"type": "stdout", "data": "1\n"}
{"type": "stdout", "data": "2\n"}
{"type": "stdout", "data": "3\n"}
{"type": "exit", "data": 0}
```
### Upload a File
**`POST /files/upload`**
Save a file to the container filesystem. Provide either a `url` to fetch remotely, or send the file directly via multipart form data.
**From URL:**
```bash
curl -X POST "http://localhost:8000/files/upload?url=https://example.com/data.csv&dir=/tmp" \
-H "Authorization: Bearer <api-key>"
```
**Direct upload:**
```bash
curl -X POST "http://localhost:8000/files/upload?dir=/tmp" \
-H "Authorization: Bearer <api-key>" \
-F "file=@local_file.csv"
```
**Via temporary upload link (no auth needed to upload):**
```bash
# 1. Generate an upload link
curl -X POST "http://localhost:8000/files/upload/link?dir=/tmp" \
-H "Authorization: Bearer <api-key>"
# → {"url": "http://localhost:8000/files/upload/a1b2c3d4..."}
# 2. Upload to the link (no auth required)
curl -X POST "http://localhost:8000/files/upload/a1b2c3d4..." \
-F "file=@local_file.csv"
```
Opening a temporary upload link in a browser shows a simple file picker form — useful for manual uploads without curl.
The filename is automatically derived from the uploaded file or the URL.
### Download a File
**`GET /files/download/link`**
Returns a temporary download URL for a file. The link expires after 5 minutes and requires no authentication to use.
```bash
curl "http://localhost:8000/files/download/link?path=/tmp/output.csv" \
-H "Authorization: Bearer <api-key>"
```
```json
{"url": "http://localhost:8000/files/download/a1b2c3d4..."}
```
### Health Check
**`GET /health`**
Returns service status. No authentication required.
```json
{"status": "ok"}
```
## Security Considerations
- **Always use Docker** in production. Running Open Terminal on bare metal exposes the host system to any command the model generates.
- **Set an API key**. Without one, anyone who can reach the port has full shell access. If you don't provide one, the auto-generated key is printed once at startup — save it.
- **Use resource limits**. Apply `--memory` and `--cpus` flags in Docker to prevent runaway processes from consuming host resources.
- **Network isolation**. Place the Open Terminal container on an internal Docker network that only Open WebUI can reach, rather than exposing it to the public internet.
- **Container is ephemeral**. Files inside the container are lost when the container is removed. Mount a volume if you need persistence.
## Further Reading
- [Open Terminal GitHub Repository](https://github.com/open-webui/open-terminal)
- [Interactive API Documentation](http://localhost:8000/docs) (available when running locally)
- [Python Code Execution](/features/chat-features/code-execution/python) — Pyodide and Jupyter backends
- [Jupyter Integration Tutorial](/tutorials/integrations/jupyter) — Setting up Jupyter as a code execution backend
- [Skills](/features/workspace/skills) — Using skills with code execution

22
docs/features/plugin/development/events.mdx
View File

@@ -30,7 +30,7 @@ Events are **fully available** for native Python Tools and Functions defined dir
### External Tools (OpenAPI & MCP)
External tools can emit events via a **dedicated REST endpoint**. Open WebUI passes the following headers to all external tool requests:
External tools can emit events via a **dedicated REST endpoint**. Open WebUI passes the following headers to all external tool requests when `ENABLE_FORWARD_USER_INFO_HEADERS=True` is set:
| Header | Description |
|--------|-------------|
@@ -467,14 +467,24 @@ Yes—emit `"chat:message:delta"` events in a loop, then finish with `"chat:mess
External tools (OpenAPI and MCP servers) can emit events to the Open WebUI UI via a REST endpoint. This enables features like status updates, notifications, and streaming content from tools running on external servers.
### Prerequisites
To receive the chat and message ID headers, you must enable header forwarding by setting the following environment variable on your Open WebUI instance:
```
ENABLE_FORWARD_USER_INFO_HEADERS=True
```
Without this, Open WebUI will not include the identification headers in requests to external tools, and event emitting will not work.
### Headers Provided by Open WebUI
When Open WebUI calls your external tool, it includes these headers:
When Open WebUI calls your external tool (with header forwarding enabled), it includes these headers:
| Header | Description |
|--------|-------------|
| `X-Open-WebUI-Chat-Id` | The chat ID where the tool was invoked |
| `X-Open-WebUI-Message-Id` | The message ID associated with the tool call |
| Header | Description | Env Var Override |
|--------|-------------|------------------|
| `X-Open-WebUI-Chat-Id` | The chat ID where the tool was invoked | `FORWARD_SESSION_INFO_HEADER_CHAT_ID` |
| `X-Open-WebUI-Message-Id` | The message ID associated with the tool call | `FORWARD_SESSION_INFO_HEADER_MESSAGE_ID` |
### Event Endpoint

164
docs/features/plugin/development/rich-ui.mdx Normal file
View File

@@ -0,0 +1,164 @@
---
sidebar_position: 4
title: "Rich UI Embedding"
---
# Rich UI Element Embedding
Tools and Actions both support rich UI element embedding, allowing them to return HTML content and interactive iframes that display directly within chat conversations. This feature enables sophisticated visual interfaces, interactive widgets, charts, dashboards, and other rich web content — regardless of whether the function was triggered by the model (Tool) or by the user (Action).
When a function returns an `HTMLResponse` with the appropriate headers, the content will be embedded as an interactive iframe in the chat interface rather than displayed as plain text.
## Tool Usage
To embed HTML content, your tool should return an `HTMLResponse` with the `Content-Disposition: inline` header:
```python
from fastapi.responses import HTMLResponse
def create_visualization_tool(self, data: str) -> HTMLResponse:
"""
Creates an interactive data visualization that embeds in the chat.
:param data: The data to visualize
"""
html_content = """
<!DOCTYPE html>
<html>
<head>
<title>Data Visualization</title>
<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
</head>
<body>
<div id="chart" style="width:100%;height:400px;"></div>
<script>
// Your interactive chart code here
Plotly.newPlot('chart', [{
y: [1, 2, 3, 4],
type: 'scatter'
}]);
</script>
</body>
</html>
"""
headers = {"Content-Disposition": "inline"}
return HTMLResponse(content=html_content, headers=headers)
```
## Action Usage
Actions work exactly the same way. The rich UI embed is delivered to the chat via the event emitter:
**Option A — HTMLResponse:**
```python
from fastapi.responses import HTMLResponse
async def action(self, body, __event_emitter__=None):
html = "<html><body><h1>Dashboard</h1></body></html>"
return HTMLResponse(content=html, headers={"Content-Disposition": "inline"})
```
**Option B — Tuple with headers:**
```python
async def action(self, body, __event_emitter__=None):
html = "<h1>Interactive Chart</h1><script>...</script>"
return (html, {"Content-Disposition": "inline", "Content-Type": "text/html"})
```
## Advanced Features
The embedded iframes support auto-resizing and include configurable security settings. The system automatically handles:
- **Auto-resizing**: Embedded content automatically adjusts height based on its content
- **Cross-origin communication**: Safe message passing between the iframe and parent window
- **Security sandbox**: Configurable security restrictions for embedded content
## Security Considerations
When embedding external content, several security options can be configured through the UI settings:
- `iframeSandboxAllowForms`: Allow form submissions within embedded content
- `iframeSandboxAllowSameOrigin`: Allow same-origin requests (use with caution)
## Use Cases
Rich UI embedding is perfect for:
- **Interactive dashboards**: Real-time data visualization and controls
- **Form interfaces**: Complex input forms with validation and dynamic behavior
- **Charts and graphs**: Interactive plotting with libraries like Plotly, D3.js, or Chart.js
- **Media players**: Video, audio, or interactive media content
- **Custom widgets**: Specialized UI components for specific tool functionality
- **External integrations**: Embedding content from external services or APIs
- **Human-triggered visualizations**: Actions that display results when a user clicks a button, e.g. generating a report or triggering a download
## External Tool Example
For external tools served via HTTP endpoints:
```python
@app.post("/tools/dashboard")
async def create_dashboard():
html = """
<div style="padding: 20px;">
<h2>System Dashboard</h2>
<canvas id="myChart" width="400" height="200"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
const ctx = document.getElementById('myChart').getContext('2d');
new Chart(ctx, {
type: 'line',
data: { /* your chart data */ }
});
</script>
</div>
"""
return HTMLResponse(
content=html,
headers={"Content-Disposition": "inline"}
)
```
The embedded content automatically inherits responsive design and integrates seamlessly with the chat interface, providing a native-feeling experience for users interacting with your tools.
## CORS and Direct Tools
Direct external tools are tools that run directly from the browser. In this case, the tool is called by JavaScript in the user's browser.
Because we depend on the Content-Disposition header, when using CORS on a remote tool server, the Open WebUI cannot read that header due to Access-Control-Expose-Headers, which prevents certain headers from being read from the fetch result.
To prevent this, you must set Access-Control-Expose-Headers to Content-Disposition. Check the example below of a tool using Node.js:
```javascript
const app = express();
const cors = require('cors');
app.use(cors())
app.get('/tools/dashboard', (req,res) => {
let html = `
<div style="padding: 20px;">
<h2>System Dashboard</h2>
<canvas id="myChart" width="400" height="200"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
const ctx = document.getElementById('myChart').getContext('2d');
new Chart(ctx, {
type: 'line',
data: { /* your chart data */ }
});
</script>
</div>
`
res.set({
'Content-Disposition': 'inline'
,'Access-Control-Expose-Headers':'Content-Disposition'
})
res.send(html)
})
```
More info about the header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Expose-Headers

1
docs/features/plugin/functions/action.mdx
View File

@@ -316,5 +316,6 @@ Actions integrate seamlessly with other Open WebUI features:
- **Files** - Actions can process uploaded files and generate new ones
- **Memory** - Actions can access conversation history and context
- **Permissions** - Actions respect user roles and access controls
- **[Rich UI Embedding](/features/plugin/development/rich-ui)** - Actions can return HTML content that renders as interactive iframes in the chat
For more examples and community-contributed actions, visit [https://openwebui.com/search](https://openwebui.com/search) where you can discover, download, and explore custom functions built by the Open WebUI community.

135
docs/features/plugin/tools/development.mdx
View File

@@ -1498,140 +1498,7 @@ from typing import Optional, Callable, Awaitable
### Rich UI Element Embedding
Both External and Built-In Tools now support rich UI element embedding, allowing tools to return HTML content and interactive iframes that display directly within chat conversations. This feature enables tools to provide sophisticated visual interfaces, interactive widgets, charts, dashboards, and other rich web content.
When a tool returns an `HTMLResponse` with the appropriate headers, the content will be embedded as an interactive iframe in the chat interface rather than displayed as plain text.
#### Basic Usage
To embed HTML content, your tool should return an `HTMLResponse` with the `Content-Disposition: inline` header:
```python
from fastapi.responses import HTMLResponse
def create_visualization_tool(self, data: str) -> HTMLResponse:
"""
Creates an interactive data visualization that embeds in the chat.
:param data: The data to visualize
"""
html_content = """
<!DOCTYPE html>
<html>
<head>
<title>Data Visualization</title>
<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
</head>
<body>
<div id="chart" style="width:100%;height:400px;"></div>
<script>
// Your interactive chart code here
Plotly.newPlot('chart', [{
y: [1, 2, 3, 4],
type: 'scatter'
}]);
</script>
</body>
</html>
"""
headers = {"Content-Disposition": "inline"}
return HTMLResponse(content=html_content, headers=headers)
```
#### Advanced Features
The embedded iframes support auto-resizing and include configurable security settings. The system automatically handles:
- **Auto-resizing**: Embedded content automatically adjusts height based on its content
- **Cross-origin communication**: Safe message passing between the iframe and parent window
- **Security sandbox**: Configurable security restrictions for embedded content
#### Security Considerations
When embedding external content, several security options can be configured through the UI settings:
- `iframeSandboxAllowForms`: Allow form submissions within embedded content
- `iframeSandboxAllowSameOrigin`: Allow same-origin requests (use with caution)
#### Use Cases
Rich UI embedding is perfect for:
- **Interactive dashboards**: Real-time data visualization and controls
- **Form interfaces**: Complex input forms with validation and dynamic behavior
- **Charts and graphs**: Interactive plotting with libraries like Plotly, D3.js, or Chart.js
- **Media players**: Video, audio, or interactive media content
- **Custom widgets**: Specialized UI components for specific tool functionality
- **External integrations**: Embedding content from external services or APIs
#### External Tool Example
For external tools served via HTTP endpoints:
```python
@app.post("/tools/dashboard")
async def create_dashboard():
html = """
<div style="padding: 20px;">
<h2>System Dashboard</h2>
<canvas id="myChart" width="400" height="200"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
const ctx = document.getElementById('myChart').getContext('2d');
new Chart(ctx, {
type: 'line',
data: { /* your chart data */ }
});
</script>
</div>
"""
return HTMLResponse(
content=html,
headers={"Content-Disposition": "inline"}
)
```
The embedded content automatically inherits responsive design and integrates seamlessly with the chat interface, providing a native-feeling experience for users interacting with your tools.
#### CORS and Direct Tools
Direct external tools are tools that run directly from the browser. In this case, the tool is called by JavaScript in the user's browser.
Because we depend on the Content-Disposition header, when using CORS on a remote tool server, the Open WebUI cannot read that header due to Access-Control-Expose-Headers, which prevents certain headers from being read from the fetch result.
To prevent this, you must set Access-Control-Expose-Headers to Content-Disposition. Check the example below of a tool using Node.js:
```javascript
const app = express();
const cors = require('cors');
app.use(cors())
app.get('/tools/dashboard', (req,res) => {
let html = `
<div style="padding: 20px;">
<h2>System Dashboard</h2>
<canvas id="myChart" width="400" height="200"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
const ctx = document.getElementById('myChart').getContext('2d');
new Chart(ctx, {
type: 'line',
data: { /* your chart data */ }
});
</script>
</div>
`
res.set({
'Content-Disposition': 'inline'
,'Access-Control-Expose-Headers':'Content-Disposition'
})
res.send(html)
})
```
More info about the header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Expose-Headers
Tools and Actions can return HTML content that renders as interactive iframes directly in the chat. For full documentation, examples, security considerations, and CORS configuration, see the dedicated **[Rich UI Embedding](/features/plugin/development/rich-ui)** guide.
## External packages

11
docs/features/plugin/tools/index.mdx
View File

@@ -98,7 +98,7 @@ In Default Mode, Open WebUI manages tool selection by injecting a specific promp
Native Mode (also called **Agentic Mode**) leverages the model's built-in capability to handle tool definitions and return structured tool calls (JSON). This is the **recommended mode** for high-performance agentic workflows.
:::warning Model Quality Matters
**Agentic tool calling requires high-quality models to work reliably.** While small local models may technically support function calling, they often struggle with the complex reasoning required for multi-step tool usage. For best results, use frontier models like **GPT-5**, **Claude 4.5 Sonnet**, **Gemini 3 Flash**, or **MiniMax M2.1**. Small local models may produce malformed JSON or fail to follow the strict state management required for agentic behavior.
**Agentic tool calling requires high-quality models to work reliably.** While small local models may technically support function calling, they often struggle with the complex reasoning required for multi-step tool usage. For best results, use frontier models like **GPT-5**, **Claude 4.5 Sonnet**, **Gemini 3 Flash**, or **MiniMax M2.5**. Small local models may produce malformed JSON or fail to follow the strict state management required for agentic behavior.
:::
#### Why use Native Mode (Agentic Mode)?
@@ -129,7 +129,7 @@ For reliable agentic tool calling, use high-tier frontier models:
- **GPT-5** (OpenAI)
- **Claude 4.5 Sonnet** (Anthropic)
- **Gemini 3 Flash** (Google)
- **MiniMax M2.1**
- **MiniMax M2.5**
These models excel at multi-step reasoning, proper JSON formatting, and autonomous tool selection.
:::
@@ -172,7 +172,7 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo
### Built-in System Tools (Native/Agentic Mode)
🛠️ When **Native Mode (Agentic Mode)** is enabled, Open WebUI automatically injects powerful system tools. This unlocks truly agentic behaviors where capable models (like GPT-5, Claude 4.5 Sonnet, Gemini 3 Flash, or MiniMax M2.1) can perform multi-step research, explore knowledge bases, or manage user memory autonomously.
🛠️ When **Native Mode (Agentic Mode)** is enabled, Open WebUI automatically injects powerful system tools. This unlocks truly agentic behaviors where capable models (like GPT-5, Claude 4.5 Sonnet, Gemini 3 Flash, or MiniMax M2.5) can perform multi-step research, explore knowledge bases, or manage user memory autonomously.
| Tool | Purpose |
|------|---------|
@@ -206,6 +206,8 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo
| `search_channel_messages` | Search for specific messages inside accessible channels. |
| `view_channel_message` | View a specific message or its details in a channel. |
| `view_channel_thread` | View a full message thread/replies in a channel. |
| **Skills** | *Requires per-model "Skills" category enabled (default: on).* |
| `view_skill` | Load the full instructions of a skill from the available skills manifest. |
| **Time Tools** | *Requires per-model "Time & Calculation" category enabled (default: on).* |
| `get_current_timestamp` | Get the current UTC Unix timestamp and ISO date. |
| `calculate_timestamp` | Calculate relative timestamps (e.g., "3 days ago"). |
@@ -244,6 +246,8 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo
| `search_channel_messages` | `query` (required), `count` (default: 10), `start_timestamp`, `end_timestamp` | Array of `{id, channel_id, content, user_name, created_at}` |
| `view_channel_message` | `message_id` (required) | `{id, content, user_name, created_at, reply_count}` |
| `view_channel_thread` | `parent_message_id` (required) | Array of `{id, content, user_name, created_at}` |
| **Skills** | | |
| `view_skill` | `name` (required) | `{name, content}` |
| **Time Tools** | | |
| `get_current_timestamp` | None | `{current_timestamp, current_iso}` |
| `calculate_timestamp` | `days_ago`, `weeks_ago`, `months_ago`, `years_ago` (all default: 0) | `{current_timestamp, current_iso, calculated_timestamp, calculated_iso}` |
@@ -314,6 +318,7 @@ When the **Builtin Tools** capability is enabled, you can further control which
| **Notes** | `search_notes`, `view_note`, `write_note`, `replace_note_content` | Search, view, and manage user notes |
| **Knowledge Base** | `list_knowledge_bases`, `search_knowledge_bases`, `query_knowledge_bases`, `search_knowledge_files`, `query_knowledge_files`, `view_knowledge_file` | Browse and query knowledge bases |
| **Channels** | `search_channels`, `search_channel_messages`, `view_channel_message`, `view_channel_thread` | Search channels and channel messages |
| **Skills** | `view_skill` | Load skill instructions on-demand from the manifest |
All categories are **enabled by default**. Disabling a category prevents those specific tools from being injected, while keeping other categories active.

26
docs/features/rbac/groups.md
View File

@@ -64,29 +64,23 @@ When editing a group, you can toggle specific permissions.
## Resource Access (RBAC)
You can restrict access to specific objects (like a proprietary Model or sensitive Knowledge Base) using Groups.
You can restrict access to specific objects (like a proprietary Model or sensitive Knowledge Base) using Groups or individual user grants.
1. **Tag the Resource**: When creating/editing a Model or Knowledge Base, set its visibility to **Private** or **Restricted**.
2. **Grant Access**: Select the specific **Groups** (or individual users) that should have "Read" or "Write" access.
2. **Grant Access**: Select the specific **Groups** or **individual users** that should have "Read" or "Write" access. The redesigned access control UI makes it easy to add multiple groups or users at once.
:::tip Knowledge Scoping for Models
Beyond visibility, knowledge access is also scoped by model configuration. When a model has **attached knowledge bases**, it can only access those specific KBs (not all user-accessible KBs). See [Knowledge Scoping with Native Function Calling](/features/workspace/knowledge#knowledge-scoping-with-native-function-calling) for details.
:::
### Access Control Object
At a deeper level, resources store an access control list (ACL) looking like this:
### Access Grant System
At a deeper level, resource access is managed through normalized **access grants** stored in the database. Each grant specifies:
* **Resource**: The type and ID of the resource (e.g., a specific model or knowledge base).
* **Principal**: Who receives access — either a **group** or an **individual user**.
* **Permission**: The level of access — `read` or `write`.
For example, granting the "Marketing" group read access and a specific editor user write access to a model would create two separate grant entries. Public access is represented by a user grant with a wildcard (`*`) principal.
```json
{
"read": {
"group_ids": ["marketing-team-id", "admins-id"],
"user_ids": []
},
"write": {
"group_ids": ["admins-id"],
"user_ids": ["editor-user-id"]
}
}
```
* **Read**: Users can view and use the resource.
* **Write**: Users can update or delete the resource.

4
docs/features/rbac/index.mdx
View File

@@ -7,7 +7,7 @@ Open WebUI implements a flexible and secure **Role-Based Access Control (RBAC)**
1. [**Roles**](./roles.md): The high-level user type (Admin, User, Pending). This defines the baseline trust level.
2. [**Permissions**](./permissions.md): Granular feature flags (e.g., "Can Delete Chats", "Can Use Web Search").
3. [**Groups**](./groups.md): The mechanism for organizing users, granting additional permissions, and managing shared access to resources (ACLs).
3. [**Groups**](./groups.md): The mechanism for organizing users, granting additional permissions, and managing shared access to resources (ACLs). Resources can also be shared directly to individual users.
:::info Key Concept: Additive Permissions
The security model is **Additive**. Users start with their default rights, and Group memberships **add** capabilities. A user effectively has the *union* of all rights granted by their Roles and Groups.
@@ -27,4 +27,4 @@ The security model is **Additive**. Users start with their default rights, and G
* [‍🔐 **Groups**](./groups.md)
* Learn how to structure teams and projects.
* **Strategy**: Distinguish between "Permission Groups" (for rights) and "Sharing Groups" (for access).
* Manage Access Control Lists (ACLs) for private Models and Knowledge.
* Manage Access Control Lists (ACLs) for private Models and Knowledge — share with groups or individual users.

3
docs/features/rbac/permissions.md
View File

@@ -47,6 +47,7 @@ Some permissions are **dependent** on others (e.g., you cannot import models if
| **Tools Access** | **(Parent)** Access the **Tools** workspace to manage functions/tools. |
| **Tools Import** | *(Requires Tools Access)* Ability to import tools. |
| **Tools Export** | *(Requires Tools Access)* Ability to export tools. |
| **Skills Access** | Access the **Skills** workspace to create and manage reusable instruction sets. |
### 2. Sharing Permissions
Controls what users can share with the community or make public.
@@ -61,6 +62,8 @@ Controls what users can share with the community or make public.
| **Public Prompts** | *(Requires Share Prompts)* Ability to make prompts public. |
| **Share Tools** | **(Parent)** Ability to share tools. |
| **Public Tools** | *(Requires Share Tools)* Ability to make tools public. |
| **Share Skills** | **(Parent)** Ability to share skills. |
| **Public Skills** | *(Requires Share Skills)* Ability to make skills public. |
| **Share Notes** | **(Parent)** Ability to share Notes. |
| **Public Notes** | *(Requires Share Notes)* Ability to make Notes public. |

4
docs/features/web-search/agentic-search.mdx
View File

@@ -8,7 +8,7 @@ title: "Agentic Search & URL Fetching"
Open WebUI's web search has evolved from simple result injection to a fully **agentic research system**. By enabling **Native Function Calling (Agentic Mode)**, you allow quality models to independently explore the web, verify facts, and follow links autonomously.
:::tip Quality Models Required
Agentic web search works best with frontier models like **GPT-5**, **Claude 4.5+**, **Gemini 3+**, or **MiniMax M2.1** that can reason about search results and decide when to dig deeper. Small local models may struggle with the multi-step reasoning required.
Agentic web search works best with frontier models like **GPT-5**, **Claude 4.5+**, **Gemini 3+**, or **MiniMax M2.5** that can reason about search results and decide when to dig deeper. Small local models may struggle with the multi-step reasoning required.
:::
:::info Central Tool Documentation
@@ -27,7 +27,7 @@ For comprehensive information about all built-in agentic tools (including web se
## How to Enable Agentic Behavior
To unlock these features, your model must support native tool calling and have strong reasoning capabilities (e.g., GPT-5, Claude 4.5 Sonnet, Gemini 3 Flash, MiniMax M2.1). Administrator-level configuration for these built-in system tools is handled via the [**Central Tool Calling Guide**](/features/plugin/tools#tool-calling-modes-default-vs-native).
To unlock these features, your model must support native tool calling and have strong reasoning capabilities (e.g., GPT-5, Claude 4.5 Sonnet, Gemini 3 Flash, MiniMax M2.5). Administrator-level configuration for these built-in system tools is handled via the [**Central Tool Calling Guide**](/features/plugin/tools#tool-calling-modes-default-vs-native).
1. **Enable Web Search Globally**: Ensure a search engine is configured in **Admin Panel → Settings → Web Search**.
2. **Enable Model Capability**: In **Admin Panel → Settings → Models**, select your model and enable the **Web Search** capability.

1
docs/features/workspace/index.mdx
View File

@@ -11,5 +11,6 @@ The Workspace in Open WebUI provides a comprehensive environment for managing yo
- [🧠 Knowledge](./knowledge.md) - Manage your knowledge bases for retrieval augmented generation
- [📚 Prompts](./prompts.md) - Create and organize reusable prompts
- [📁 Files](./files.md) - Centralized management for all your uploaded documents
- [📝 Skills](./skills.md) - Reusable markdown instruction sets for guiding model behavior
Each section of the Workspace is designed to give you fine-grained control over your Open WebUI experience, allowing for customization and optimization of your AI interactions.

3
docs/features/workspace/models.md
View File

@@ -30,7 +30,7 @@ Both actions lead to the same Model Builder interface, where you can configure t
- **Tags**: Add tags to organize models in the selector dropdown.
- **Visibility & Groups**:
- **Private**: Restricts access to specific users or groups.
- **Groups Selector**: Use the dropdown to grant access to specific teams (e.g., "Admins", "Developers") without making the model public to everyone.
- **Access Control Selector**: Use the access control panel to grant access to specific groups (e.g., "Admins", "Developers") or individual users without making the model public to everyone. The redesigned interface makes it easy to add multiple groups and users at once.
### System Prompt & Dynamic Variables
@@ -74,6 +74,7 @@ You can transform a generic model into a specialized agent by toggling specific
- **Knowledge**: Instead of manually selecting documents for every chat, you can bind a specific knowledgebase **Collection** or **File** to this model. Whenever this model is selected, RAG (Retrieval Augmented Generation) is automatically active for those specific files. Click on attached items to toggle between **Focused Retrieval** (RAG chunks) and **Using Entire Document** (full content injection). See [Full Context vs Focused Retrieval](/features/workspace/knowledge#full-context-vs-focused-retrieval) for details.
- **Tools**: Force specific tools to be enabled by default (e.g., always enable the **Calculator** tool for a "Math Bot").
- **Skills**: Bind [Skills](/features/workspace/skills) to this model so their manifests are always injected. The model can load full skill instructions on-demand via the `view_skill` builtin tool.
- **Filters**: Attach specific Pipelines/Filters (e.g., a Profanity Filter or PII Redaction script) to run exclusively on this model.
- **Actions**: Attach actionable scripts like `Add to Memories` or `Button` triggers.
- **Capabilities**: Granularly control what the model is allowed to do:

130
docs/features/workspace/skills.md Normal file
View File

@@ -0,0 +1,130 @@
---
sidebar_position: 6
title: "Skills"
sidebar_label: "Skills"
---
Skills are reusable, markdown-based instruction sets that you can attach to models or invoke on-the-fly in chat. Unlike [Tools](/features/plugin/tools) (which are executable Python scripts), Skills are **plain-text instructions** that teach a model *how* to approach a task — such as code review guidelines, writing style rules, or troubleshooting playbooks.
## How Skills Work
Skills use a **lazy-loading** architecture to keep the model's context window efficient:
1. **Manifest injection** — When a skill is active (either bound to a model or mentioned in chat), only a lightweight manifest containing the skill's **name** and **description** is injected into the system prompt.
2. **On-demand loading** — The model receives a `view_skill` builtin tool. When it determines it needs a skill's full instructions, it calls `view_skill` with the skill name to load the complete content.
This design means that even if dozens of skills are available, only the ones the model actually needs are loaded into context.
## Creating a Skill
Navigate to **Workspace → Skills** and click **+ New Skill**.
| Field | Description |
| :--- | :--- |
| **Name** | A human-readable display name (e.g., "Code Review Guidelines"). |
| **Skill ID** | A unique slug identifier, auto-generated from the name (e.g., `code-review-guidelines`). Editable during creation, read-only afterwards. |
| **Description** | A short summary shown in the manifest. The model uses this to decide whether to load the full instructions. |
| **Content** | The full skill instructions in **Markdown**. This is the content loaded by `view_skill`. |
Click **Save & Create** to finalize.
## Using Skills
### In Chat ($ Mention)
Type `$` in the chat input to open the skill picker. Select a skill, and it will be attached to the message as a **skill mention** (similar to `@` for models or `#` for knowledge). The skill manifest is injected for that conversation, and the model can call `view_skill` to load the full instructions when needed.
### Bound to a Model
You can permanently attach skills to a model so they are always available:
1. Go to **Workspace → Models**.
2. Edit a model and scroll to the **Skills** section.
3. Check the skills you want this model to always have access to.
4. Click **Save**.
When a user chats with that model, the selected skills' manifests are automatically injected.
## Import and Export
### Importing from Markdown
Click **Import** on the Skills workspace page and select a `.md` file. If the file contains YAML frontmatter with `name` and/or `description` fields, those values are auto-populated into the creation form.
Example frontmatter:
```yaml
---
name: code-review-guidelines
description: Step-by-step instructions for thorough code reviews
---
# Code Review Guidelines
1. Check for correctness...
```
### Exporting
- **Single skill**: Click the ellipsis menu (**...**) on a skill and select **Export** to download it as a JSON file.
- **Bulk export**: Click the **Export** button at the top of the Skills page to export all accessible skills as a single JSON file.
## Skill Management
From the Skills workspace list, you can perform the following actions via the ellipsis menu (**...**) on each skill:
| Action | Description |
| :--- | :--- |
| **Edit** | Open the skill editor to modify content, name, or description. |
| **Clone** | Create a copy with `-clone` appended to the ID and "(Clone)" to the name. |
| **Export** | Download the skill as a JSON file. |
| **Delete** | Permanently remove the skill. Also available via Shift+Click on the delete icon for quick deletion. |
### Active / Inactive Toggle
Each skill has an **active/inactive toggle** visible on the list page. Inactive skills are excluded from manifests and cannot be loaded by the model, even if they are bound to one or mentioned in chat.
## Code Execution Backends
The backend you choose affects what your skills can do — from simple text transformations (Pyodide) to full OS-level shell access (Open Terminal). Each has different trade-offs in library support, isolation, persistence, and multi-user safety.
See the [Code Execution overview](/features/chat-features/code-execution) for a detailed comparison of all available backends and guidance on choosing the right one for your deployment.
### Setting Up Open Terminal
Open Terminal is a FastAPI application that automatically exposes an [OpenAPI specification](https://swagger.io/specification/). This means it works out of the box as an OpenAPI Tool Server — Open WebUI auto-discovers its endpoints and registers them as tools. No manual tool creation needed.
**1. Start an Open Terminal instance**
Follow the [Open Terminal setup guide](/features/open-terminal#getting-started) to launch an instance using Docker or pip.
**2. Connect to Open WebUI**
Add your Open Terminal instance as a Tool Server by following the [OpenAPI Tool Server Integration Guide](/features/plugin/tools/openapi-servers/open-webui). You can connect it as:
- A **User Tool Server** (in **Settings → Tools**) — connects from your browser, ideal for personal or local instances
- A **Global Tool Server** (in **Admin Settings → Tools**) — connects from the backend, available to all users
Once connected, the Open Terminal tools (execute, file upload, file download) appear automatically in the chat interface.
:::tip
For the best experience, pair Open Terminal with a [Skill](/features/workspace/skills) that teaches the model how to use the tool effectively — for example, instructing it to always check exit codes, handle errors gracefully, and use streaming for long-running commands.
:::
See the [Open Terminal documentation](/features/open-terminal) for the full API reference and detailed setup instructions.
## Access Control
Skills use the same [Access Control](/features/rbac) system as other workspace resources:
- **Private by default**: Only the creator can see and edit a new skill.
- **Share with users or groups**: Use the **Access** button in the skill editor to grant `read` or `write` access to specific users or groups.
- **Read-only access**: Users with only read access can view the skill content but cannot edit it. The editor displays a "Read Only" badge.
### Required Permissions
- **Workspace → Skills Access**: Required to access the Skills workspace and create/manage skills.
- **Sharing → Share Skills**: Required to share skills with individual users or groups.
- **Sharing → Public Skills**: Required to make skills publicly accessible.
See [Permissions](/features/rbac/permissions) for details on how to configure these.

45
docs/getting-started/env-configuration.mdx
View File

@@ -12,7 +12,7 @@ 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.7.1](https://github.com/open-webui/open-webui/releases/tag/v0.7.1), 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.8.0](https://github.com/open-webui/open-webui/releases/tag/v0.8.0), but is still a work in progress to later include more accurate descriptions, listing out options available for environment variables, defaults, and improving descriptions.
:::
@@ -1357,8 +1357,9 @@ If enabled, the following headers are forwarded:
- `X-OpenWebUI-User-Email`
- `X-OpenWebUI-User-Role`
- `X-OpenWebUI-Chat-Id`
- `X-OpenWebUI-Message-Id`
This enables per-user authorization, auditing, rate limiting, and request tracing on external services.
This enables per-user authorization, auditing, rate limiting, and request tracing on external services. The chat and message ID headers are also required for [external tool event emitting](/features/plugin/development/events#-external-tool-events).
#### `FORWARD_USER_INFO_HEADER_USER_NAME`
@@ -1390,6 +1391,12 @@ This enables per-user authorization, auditing, rate limiting, and request tracin
- Default: `X-OpenWebUI-Chat-Id`
- Description: Customizes the header name used to forward the current chat/session ID.
#### `FORWARD_SESSION_INFO_HEADER_MESSAGE_ID`
- Type: `str`
- Default: `X-OpenWebUI-Message-Id`
- Description: Customizes the header name used to forward the current message ID. This header is required for [external tool event emitting](/features/plugin/development/events#-external-tool-events).
:::tip Custom Header Prefix
Use these variables when integrating with services that require specific header naming conventions. For example, AWS Bedrock AgentCore requires headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-`:
@@ -1399,6 +1406,7 @@ FORWARD_USER_INFO_HEADER_USER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id
FORWARD_USER_INFO_HEADER_USER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email
FORWARD_USER_INFO_HEADER_USER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role
FORWARD_SESSION_INFO_HEADER_CHAT_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Chat-Id
FORWARD_SESSION_INFO_HEADER_MESSAGE_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Message-Id
```
:::
@@ -2869,6 +2877,18 @@ If you are embedding externally via API, ensure your rate limits are high enough
:::
#### `RAG_EMBEDDING_TIMEOUT`
- Type: `int` (seconds)
- Default: `None` (no timeout)
- Description: Sets an optional timeout in seconds for embedding operations during document upload. When set, embedding requests that exceed this duration will be aborted with a timeout error. When unset (default), embedding operations run without a time limit. This setting is primarily relevant for deployments using the default **SentenceTransformers** embedding engine, where embeddings run locally and can take longer on slower hardware. External embedding engines (Ollama, OpenAI, Azure OpenAI) have their own timeout mechanisms and are generally not affected by this setting.
:::info
This variable was introduced alongside a fix for **uvicorn worker death during document uploads**. Previously, local embedding operations could block the worker thread long enough to trigger uvicorn's health check timeout (default: 5 seconds), causing the worker process to be killed. The underlying fix uses `run_coroutine_threadsafe` to keep the main event loop responsive to health checks regardless of this timeout setting. The timeout is purely a safety net for aborting abnormally long embedding operations — it does not affect worker health check behavior.
:::
#### `RAG_EMBEDDING_CONTENT_PREFIX`
- Type: `str`
@@ -5294,6 +5314,13 @@ For API Key creation (and the API keys themselves) to work, you need **both**:
- Description: Enables or disables user permission to access workspace tools.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `USER_PERMISSIONS_WORKSPACE_SKILLS_ACCESS`
- Type: `bool`
- Default: `False`
- Description: Enables or disables user permission to access workspace skills.
- Persistence: This environment variable is a `PersistentConfig` variable.
### Sharing (Private)
These settings control whether users can share workspace items with other users **privately** (non-public sharing).
@@ -5326,6 +5353,13 @@ These settings control whether users can share workspace items with other users
- Description: Enables or disables **private sharing** of workspace tools.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `USER_PERMISSIONS_WORKSPACE_SKILLS_ALLOW_SHARING`
- Type: `str`
- Default: `False`
- Description: Enables or disables **private sharing** of workspace skills.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `USER_PERMISSIONS_NOTES_ALLOW_SHARING`
- Type: `str`
@@ -5365,6 +5399,13 @@ These settings control whether users can share workspace items **publicly**.
- Description: Enables or disables **public sharing** of workspace tools.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `USER_PERMISSIONS_WORKSPACE_SKILLS_ALLOW_PUBLIC_SHARING`
- Type: `str`
- Default: `False`
- Description: Enables or disables **public sharing** of workspace skills.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING`
- Type: `str`

2
docs/getting-started/quick-start/starting-with-openai.mdx
View File

@@ -83,7 +83,7 @@ Once Open WebUI is running:
:::
:::caution MiniMax Whitelisting
Some providers, like **MiniMax**, do not expose their models via a `/models` endpoint. For these providers, you **must** manually add the Model ID (e.g., `MiniMax-M2.1`) to the **Model IDs (Filter)** list for them to appear in the UI.
Some providers, like **MiniMax**, do not expose their models via a `/models` endpoint. For these providers, you **must** manually add the Model ID (e.g., `MiniMax-M2.5`) to the **Model IDs (Filter)** list for them to appear in the UI.
:::
* **Prefix ID**:

2
docs/getting-started/quick-start/tab-docker/ManualDocker.md
View File

@@ -23,7 +23,7 @@ docker pull ghcr.io/open-webui/open-webui:main-slim
You can also pull a specific Open WebUI release version directly by using a versioned image tag. This is recommended for production environments to ensure stable and reproducible deployments.
```bash
docker pull ghcr.io/open-webui/open-webui:v0.7.0
docker pull ghcr.io/open-webui/open-webui:v0.8.0
```
## Step 2: Run the Container

6
docs/intro.mdx
View File

@@ -99,9 +99,9 @@ ghcr.io/open-webui/open-webui:<RELEASE_VERSION>-<TYPE>
Examples (pinned versions for illustration purposes only):
```
ghcr.io/open-webui/open-webui:v0.7.0
ghcr.io/open-webui/open-webui:v0.7.0-ollama
ghcr.io/open-webui/open-webui:v0.7.0-cuda
ghcr.io/open-webui/open-webui:v0.8.0
ghcr.io/open-webui/open-webui:v0.8.0-ollama
ghcr.io/open-webui/open-webui:v0.8.0-cuda
```
### Using the Dev Branch 🌙

45
docs/troubleshooting/rag.mdx
View File

@@ -309,6 +309,51 @@ If PDFs containing images with text are returning empty content:
| 📄 API returns "empty content" error | Wait for file processing to complete before adding to knowledge base |
| 💥 CUDA OOM during embedding | Reduce batch size, isolate GPU, or restart container |
| 📷 PDF images not extracted | Use Tika/Docling, enable OCR, or update pypdf |
| 💀 Worker dies during upload | Update Open WebUI, or increase `--timeout-worker-healthcheck` |
---
### 12. Worker Dies During Document Upload (SentenceTransformers) 💀
When uploading documents with the default SentenceTransformers embedding engine in a **multi-worker** deployment, you may see:
```
INFO: Waiting for child process [12]
INFO: Child process [12] died
```
**The Problem**: When using **multiple uvicorn workers** (`--workers 2` or more), uvicorn monitors worker health via periodic pings. The default health check timeout is just **5 seconds**. Local SentenceTransformers embedding operations can take longer than this, and in older versions of Open WebUI, the embedding call blocked the event loop entirely — preventing the worker from responding to health checks. Uvicorn then killed the worker as unresponsive.
:::note
This issue was **fixed** in Open WebUI. The embedding system now uses `run_coroutine_threadsafe` to keep the main event loop responsive during embedding operations, so workers will no longer be killed during uploads regardless of how long embeddings take.
If you are running a version with this fix and still experiencing worker death, ensure your Open WebUI is up to date.
:::
**Who is affected:**
- Only deployments using the **default SentenceTransformers** embedding engine (local embeddings).
- Only when running **multiple uvicorn workers**. Single-worker deployments don't have health check timeouts.
- External embedding engines (Ollama, OpenAI, Azure OpenAI) are **not affected** since their API calls don't block the event loop.
✅ **Solutions (for older versions without the fix):**
1. **Update Open WebUI** to a version that includes the `run_coroutine_threadsafe` fix.
2. **Increase the health check timeout** as a workaround:
```yaml
# docker-compose.yaml
command: ["bash", "start.sh", "--workers", "2", "--timeout-worker-healthcheck", "120"]
```
3. **Switch to an external embedding engine** to avoid local blocking entirely:
```
RAG_EMBEDDING_ENGINE=ollama
RAG_EMBEDDING_MODEL=nomic-embed-text
```
4. **Optionally set a safety timeout** via [`RAG_EMBEDDING_TIMEOUT`](/getting-started/env-configuration#rag_embedding_timeout) to abort abnormally long embedding operations (does not affect health checks).
---

14
docs/tutorials/integrations/minimax.md
View File

@@ -1,6 +1,6 @@
---
sidebar_position: 32
title: "Integrate with MiniMax M2.1"
title: "Integrate with MiniMax M2.5"
---
:::warning
@@ -11,9 +11,9 @@ This tutorial is a community contribution and is not supported by the Open WebUI
---
# Integrating Open WebUI with MiniMax M2.1
# Integrating Open WebUI with MiniMax M2.5
MiniMax is a leading AI company providing high-performance coding-focused models. Their latest model, **MiniMax M2.1**, is specifically optimized for coding, reasoning, and multi-turn dialogue. This guide covers how to set up MiniMax via their cost-effective **Coding Plan** and integrate it into Open WebUI.
MiniMax is a leading AI company providing high-performance coding-focused models. Their latest model, **MiniMax M2.5**, is specifically optimized for coding, reasoning, and multi-turn dialogue. This guide covers how to set up MiniMax via their cost-effective **Coding Plan** and integrate it into Open WebUI.
## Step 1: Subscribe to a MiniMax Coding Plan
@@ -56,8 +56,8 @@ Now, link MiniMax to your Open WebUI instance.
3. Enter the following details:
- **API Base URL**: `https://api.minimax.io/v1`
- **API Key**: `YOUR_CODING_PLAN_API_KEY`
4. **Important**: MiniMax does not expose models via a `/models` endpoint, so you must whitelist the model manually. The connection verify button would also return with an error of "OpenAI: Network Problem" error because of this.
5. In the **Model Whitelist**, type `MiniMax-M2.1` and click the **+** icon.
4. **Important**: MiniMax does not expose models via a `/models` endpoint, so you must whitelist the model manually.
5. In the **Model Whitelist**, type `MiniMax-M2.5` and click the **+** icon.
6. Click **Verify Connection** (you should see a success alert).
7. Click **Save** on the connection popup, then scroll down and click **Save** on the main Connections page.
@@ -66,10 +66,10 @@ Now, link MiniMax to your Open WebUI instance.
## Step 4: Start Chatting
You are now ready to use MiniMax M2.1!
You are now ready to use MiniMax M2.5!
1. Start a new chat.
2. Select **MiniMax-M2.1** from the model dropdown menu.
2. Select **MiniMax-M2.5** from the model dropdown menu.
3. Send a message. Reasoning and thinking work by default without any additional configuration.
![MiniMax Chat interface](/images/tutorials/minimax/minimax-chat.png)

144
docs/tutorials/tips/sqlite-database.md
View File

@@ -10,7 +10,7 @@ This tutorial is a community contribution and is not supported by the Open WebUI
:::
> [!WARNING]
> This documentation was created/updated based on version 0.7.0 and updated for recent migrations.
> This documentation was created/updated based on version 0.8.0 and updated for recent migrations.
## Open-WebUI Internal SQLite Database
@@ -54,35 +54,37 @@ Here is a complete list of tables in Open-WebUI's SQLite database. The tables ar
| **No.** | **Table Name** | **Description** |
| ------- | ---------------- | ------------------------------------------------------------ |
| 01 | auth | Stores user authentication credentials and login information |
| 02 | channel | Manages chat channels and their configurations |
| 03 | channel_file | Links files to channels and messages |
| 04 | channel_member | Tracks user membership and permissions within channels |
| 05 | chat | Stores chat sessions and their metadata |
| 06 | chat_file | Links files to chats and messages |
| 07 | chatidtag | Maps relationships between chats and their associated tags |
| 08 | config | Maintains system-wide configuration settings |
| 09 | document | Stores documents and their metadata for knowledge management |
| 10 | feedback | Captures user feedback and ratings |
| 11 | file | Manages uploaded files and their metadata |
| 12 | folder | Organizes files and content into hierarchical structures |
| 13 | function | Stores custom functions and their configurations |
| 14 | group | Manages user groups and their permissions |
| 15 | group_member | Tracks user membership within groups |
| 16 | knowledge | Stores knowledge base entries and related information |
| 17 | knowledge_file | Links files to knowledge bases |
| 18 | memory | Maintains chat history and context memory |
| 19 | message | Stores individual chat messages and their content |
| 20 | message_reaction | Records user reactions (emojis/responses) to messages |
| 21 | migrate_history | Tracks database schema version and migration records |
| 22 | model | Manages AI model configurations and settings |
| 23 | note | Stores user-created notes and annotations |
| 24 | oauth_session | Manages active OAuth sessions for users |
| 25 | prompt | Stores templates and configurations for AI prompts |
| 26 | prompt_history | Tracks version history and snapshots for prompts |
| 27 | tag | Manages tags/labels for content categorization |
| 28 | tool | Stores configurations for system tools and integrations |
| 29 | user | Maintains user profiles and account information |
| 01 | access_grant | Stores normalized access control grants for all resources |
| 02 | auth | Stores user authentication credentials and login information |
| 03 | channel | Manages chat channels and their configurations |
| 04 | channel_file | Links files to channels and messages |
| 05 | channel_member | Tracks user membership and permissions within channels |
| 06 | chat | Stores chat sessions and their metadata |
| 07 | chat_file | Links files to chats and messages |
| 08 | chatidtag | Maps relationships between chats and their associated tags |
| 09 | config | Maintains system-wide configuration settings |
| 10 | document | Stores documents and their metadata for knowledge management |
| 11 | feedback | Captures user feedback and ratings |
| 12 | file | Manages uploaded files and their metadata |
| 13 | folder | Organizes files and content into hierarchical structures |
| 14 | function | Stores custom functions and their configurations |
| 15 | group | Manages user groups and their permissions |
| 16 | group_member | Tracks user membership within groups |
| 17 | knowledge | Stores knowledge base entries and related information |
| 18 | knowledge_file | Links files to knowledge bases |
| 19 | memory | Maintains chat history and context memory |
| 20 | message | Stores individual chat messages and their content |
| 21 | message_reaction | Records user reactions (emojis/responses) to messages |
| 22 | migrate_history | Tracks database schema version and migration records |
| 23 | model | Manages AI model configurations and settings |
| 24 | note | Stores user-created notes and annotations |
| 25 | oauth_session | Manages active OAuth sessions for users |
| 26 | prompt | Stores templates and configurations for AI prompts |
| 27 | prompt_history | Tracks version history and snapshots for prompts |
| 28 | skill | Stores reusable markdown instruction sets (Skills) |
| 29 | tag | Manages tags/labels for content categorization |
| 30 | tool | Stores configurations for system tools and integrations |
| 31 | user | Maintains user profiles and account information |
Note: there are two additional tables in Open-WebUI's SQLite database that are not related to Open-WebUI's core functionality, that have been excluded:
@@ -91,6 +93,26 @@ Note: there are two additional tables in Open-WebUI's SQLite database that are n
Now that we have all the tables, let's understand the structure of each table.
## Access Grant Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
| --------------- | ------------- | ----------------------- | ------------------------------------------------------ |
| id | Integer | PRIMARY KEY, AUTOINCREMENT | Unique identifier |
| resource_type | Text | NOT NULL | Type of resource (e.g., `model`, `knowledge`, `tool`) |
| resource_id | Text | NOT NULL | ID of the specific resource |
| principal_type | Text | NOT NULL | Type of grantee: `user` or `group` |
| principal_id | Text | NOT NULL | ID of the user or group (or `*` for public) |
| permission | Text | NOT NULL | Permission level: `read` or `write` |
| created_at | BigInteger | nullable | Grant creation timestamp |
Things to know about the access_grant table:
- Unique constraint on (`resource_type`, `resource_id`, `principal_type`, `principal_id`, `permission`) to prevent duplicate grants
- Indexed on (`resource_type`, `resource_id`) and (`principal_type`, `principal_id`) for efficient lookups
- Replaces the former `access_control` JSON column that was previously embedded in each resource table
- `principal_type` of `user` with `principal_id` of `*` represents public (open) access
- Supports both group-level and individual user-level access grants
## Auth Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
@@ -116,7 +138,7 @@ Things to know about the auth table:
| description | Text | nullable | Channel description |
| data | JSON | nullable | Flexible data storage |
| meta | JSON | nullable | Channel metadata |
| access_control | JSON | nullable | Permission settings |
| created_at | BigInteger | - | Creation timestamp (nanoseconds) |
| updated_at | BigInteger | - | Last update timestamp (nanoseconds) |
@@ -237,7 +259,7 @@ Things to know about the chat_file table:
| path | Text | nullable | File system path |
| data | JSON | nullable | File-related data |
| meta | JSON | nullable | File metadata |
| access_control | JSON | nullable | Permission settings |
| created_at | BigInteger | - | Creation timestamp |
| updated_at | BigInteger | - | Last update timestamp |
@@ -335,7 +357,7 @@ Things to know about the group_member table:
| description | Text | - | Knowledge base description |
| data | JSON | nullable | Knowledge base content |
| meta | JSON | nullable | Additional metadata |
| access_control | JSON | nullable | Access control rules |
| created_at | BigInteger | - | Creation timestamp |
| updated_at | BigInteger | - | Last update timestamp |
@@ -356,20 +378,7 @@ Things to know about the knowledge_file table:
- Foreign key relationships with CASCADE delete
- Indexed on `knowledge_id`, `file_id`, and `user_id` for performance
The `access_control` fields expected structure:
```python
{
"read": {
"group_ids": ["group_id1", "group_id2"],
"user_ids": ["user_id1", "user_id2"]
},
"write": {
"group_ids": ["group_id1", "group_id2"],
"user_ids": ["user_id1", "user_id2"]
}
}
```
Access control for resources (models, knowledge bases, tools, prompts, notes, files, channels) is managed through the `access_grant` table rather than embedded JSON. Each grant entry specifies a resource, a principal (user or group), and a permission level (read or write). See the [Access Grant Table](#access-grant-table) section above for details.
## Memory Table
@@ -415,7 +424,7 @@ The `access_control` fields expected structure:
| name | Text | - | Display name |
| params | JSON | - | Model parameters |
| meta | JSON | - | Model metadata |
| access_control | JSON | nullable | Access permissions |
| is_active | Boolean | default=True | Active status |
| created_at | BigInteger | - | Creation timestamp |
| updated_at | BigInteger | - | Last update timestamp |
@@ -429,7 +438,7 @@ The `access_control` fields expected structure:
| title | Text | nullable | Note title |
| data | JSON | nullable | Note content and data |
| meta | JSON | nullable | Note metadata |
| access_control | JSON | nullable | Permission settings |
| created_at | BigInteger | nullable | Creation timestamp |
| updated_at | BigInteger | nullable | Last update timestamp |
@@ -456,7 +465,7 @@ The `access_control` fields expected structure:
| content | Text | NOT NULL | Prompt content/template |
| data | JSON | nullable | Additional prompt data |
| meta | JSON | nullable | Prompt metadata |
| access_control | JSON | nullable | Permission settings |
| is_active | Boolean | default=True | Active status |
| version_id | Text | nullable | Current version identifier |
| tags | JSON | nullable | Associated tags |
@@ -475,6 +484,27 @@ The `access_control` fields expected structure:
| commit_message | Text | nullable | Version commit message |
| created_at | BigInteger | NOT NULL | Creation timestamp |
## Skill Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
| --------------- | ------------- | --------------- | ---------------------------------- |
| id | Text | PRIMARY KEY | Unique identifier (UUID) |
| user_id | Text | NOT NULL | Owner/creator of the skill |
| name | Text | NOT NULL | Display name of the skill |
| description | Text | nullable | Short description (used in manifest) |
| content | Text | NOT NULL | Full skill instructions (Markdown) |
| data | JSON | nullable | Additional skill data |
| meta | JSON | nullable | Skill metadata |
| is_active | Boolean | default=True | Active status |
| created_at | BigInteger | NOT NULL | Creation timestamp |
| updated_at | BigInteger | NOT NULL | Last update timestamp |
Things to know about the skill table:
- Uses UUID for primary key
- Access control is managed through the `access_grant` table (resource_type `skill`)
- `description` is injected into the system prompt as part of the manifest; `content` is loaded on-demand via the `view_skill` builtin tool
## Tag Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
@@ -499,7 +529,7 @@ Things to know about the tag table:
| specs | JSON | - | Tool specifications |
| meta | JSON | - | Tool metadata |
| valves | JSON | - | Tool control settings |
| access_control | JSON | nullable | Access permissions |
| created_at | BigInteger | - | Creation timestamp |
| updated_at | BigInteger | - | Last update timestamp |
@@ -547,6 +577,7 @@ erDiagram
user ||--o{ prompt_history : "creates"
prompt ||--o{ prompt_history : "has"
user ||--o{ tag : "creates"
user ||--o{ skill : "manages"
user ||--o{ tool : "manages"
user ||--o{ note : "owns"
user ||--|| oauth_session : "has"
@@ -749,6 +780,17 @@ erDiagram
json meta
}
skill {
text id PK
text user_id FK
text name
text description
text content
json data
json meta
boolean is_active
}
tool {
string id PK
string user_id FK