mirror of
https://github.com/open-webui/docs.git
synced 2026-07-22 18:45:42 -04:00
Merge upstream/dev: resolve conflicts, retain info additions
This commit is contained in:
DrMelone
+56
-70
@@ -3,111 +3,97 @@ sidebar_position: 1600
|
||||
title: "🤝 Contributing"
|
||||
---
|
||||
|
||||
# 🤝 Contributing
|
||||
|
||||
🚀 **Welcome, Contributors!** 🚀
|
||||
**Help build the AI interface everyone deserves.**
|
||||
|
||||
Your interest in contributing to Open WebUI is greatly appreciated. This document is here to guide you through the process, ensuring your contributions enhance the project effectively. Let's make Open WebUI even better, together!
|
||||
Open WebUI is an independent project built and maintained by a small, dedicated core team. Whether you test dev builds, fix bugs, improve docs, or translate the UI, every contribution makes the project better for thousands of users. This page explains how to get involved and what to expect.
|
||||
|
||||
## 📜 Code of Conduct
|
||||
---
|
||||
|
||||
All contributors and community participants are expected to follow our **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. We operate under a **zero-tolerance policy** — disrespectful, demanding, or hostile behavior will result in immediate action without prior warning.
|
||||
## Code of Conduct
|
||||
|
||||
Our community is built on the work of volunteers who dedicate their free time to this project. Please treat every interaction with professionalism and respect.
|
||||
All contributors and community participants must follow the **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. We operate under a **zero-tolerance policy**: disrespectful, demanding, or hostile behavior results in immediate action without prior warning.
|
||||
|
||||
## 💡 Contributing
|
||||
This project is built by volunteers in their free time. Treat every interaction with professionalism and respect.
|
||||
|
||||
Looking to contribute? Great! Here's how you can help:
|
||||
---
|
||||
|
||||
### 🧪 Test the Development Branch
|
||||
## Ways to Contribute
|
||||
|
||||
**One of the most valuable ways to contribute is running the dev branch.** You don't need to write code—just use it and report issues!
|
||||
### Test the development branch
|
||||
|
||||
One of the most valuable contributions requires no code at all. Run the dev branch, use it daily, and report what breaks.
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:dev
|
||||
```
|
||||
|
||||
**Keep it updated regularly** — the dev branch moves fast! If Docker doesn't work for you, the [Local Development Guide](/getting-started/development) is another great option.
|
||||
The dev branch moves fast, so **pull updates regularly**. If Docker is not your preference, follow the [Local Development Guide](/getting-started/advanced-topics/development) instead.
|
||||
|
||||
By testing dev builds, you help us catch bugs before stable releases. Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps. **We cannot deliver high-quality releases without community testing.**
|
||||
Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps. We cannot deliver high-quality releases without community testing.
|
||||
|
||||
### 🌟 Code Contribution Guidelines
|
||||
### Submit code
|
||||
|
||||
We welcome pull requests. Before submitting one, please:
|
||||
We welcome pull requests. Before submitting one:
|
||||
|
||||
1. Open a discussion regarding your ideas [here](https://github.com/open-webui/open-webui/discussions/new/choose).
|
||||
2. Follow the project's coding standards and include tests for new features.
|
||||
3. Update documentation as necessary.
|
||||
4. Write clear, descriptive commit messages.
|
||||
1. **Open a discussion first.** Propose your idea [here](https://github.com/open-webui/open-webui/discussions/new/choose) so the team can align on approach before you write code.
|
||||
2. **Follow existing conventions.** Match the project's coding standards, naming patterns, and architecture.
|
||||
3. **Keep PRs atomic.** Each pull request should address a single objective. If scope grows, split it into smaller, logically independent PRs.
|
||||
4. **Avoid new external dependencies.** Do not add libraries or frameworks without prior discussion. We aim to stay framework-agnostic and implement functionality ourselves when practical.
|
||||
5. **Include tests.** Cover new features with tests and update documentation as needed.
|
||||
6. **Write clear commit messages.** Descriptive messages make review and history tracking easier.
|
||||
|
||||
### 🛠 Code PR Best Practices:
|
||||
### Improve documentation
|
||||
|
||||
1. **Atomic PRs:** Make sure your PRs are small, focused, and deal with a single objective or task. This helps in easier code review and limits the chances of introducing unrelated issues. If the scope of changes grows too large, consider breaking them into smaller, logically independent PRs.
|
||||
2. **Follow Existing Code Convention:** Ensure your code aligns with the existing coding standards and practices of the project.
|
||||
3. **Avoid Additional External Dependencies:** Do not include additional external dependencies without prior discussion.
|
||||
4. **Framework Agnostic Approach:** We aim to stay framework agnostic. Implement functionalities on our own whenever possible rather than relying on external frameworks or libraries. If you have doubts or suggestions regarding this approach, feel free to discuss it.
|
||||
Help make Open WebUI more accessible by improving docs, writing tutorials, or creating setup guides. Documentation lives in the [docs repository](https://github.com/open-webui/docs).
|
||||
|
||||
Thank you for contributing! 🚀
|
||||
### Translate the UI
|
||||
|
||||
### 📚 Documentation & Tutorials
|
||||
|
||||
Help us make Open WebUI more accessible by improving documentation, writing tutorials, or creating guides on setting up and optimizing the web UI.
|
||||
|
||||
### 🌐 Translations and Internationalization
|
||||
|
||||
Help us make Open WebUI available to a wider audience. In this section, we'll guide you through the process of adding new translations to the project.
|
||||
|
||||
We use JSON files to store translations. You can find the existing translation files in the `src/lib/i18n/locales` directory. Each directory corresponds to a specific language, for example, `en-US` for English (US), `fr-FR` for French (France) and so on. You can refer to [ISO 639 Language Codes](http://www.lingoes.net/en/translator/langcode.htm) to find the appropriate code for a specific language.
|
||||
Open WebUI uses JSON translation files in `src/lib/i18n/locales`. Each subdirectory is named with an [ISO 639 language code](http://www.lingoes.net/en/translator/langcode.htm) (e.g., `en-US`, `fr-FR`).
|
||||
|
||||
To add a new language:
|
||||
|
||||
- Create a new directory in the `src/lib/i18n/locales` path with the appropriate language code as its name. For instance, if you're adding translations for Spanish (Spain), create a new directory named `es-ES`.
|
||||
- Copy the American English translation file(s) (from `en-US` directory in `src/lib/i18n/locale`) to this new directory and update the string values in JSON format according to your language. Make sure to preserve the structure of the JSON object.
|
||||
- Add the language code and its respective title to languages file at `src/lib/i18n/locales/languages.json`.
|
||||
1. Create a new directory under `src/lib/i18n/locales` named with the appropriate language code
|
||||
2. Copy the `en-US` translation files into the new directory
|
||||
3. Translate the string values in each JSON file while preserving the object structure
|
||||
4. Register the language in `src/lib/i18n/locales/languages.json`
|
||||
|
||||
### 🌎 Accessibility Matters
|
||||
### Improve accessibility
|
||||
|
||||
We are committed to making **Open WebUI** inclusive and usable for everyone. Accessibility is a core part of good system design.
|
||||
Accessibility is a core part of good design. When contributing UI changes:
|
||||
|
||||
Here’s how you can help improve accessibility when you contribute:
|
||||
| Principle | What to do |
|
||||
|-----------|-----------|
|
||||
| **Semantic HTML** | Use `<button>`, `<label>`, `<nav>`, and other semantic elements instead of generic `<div>` wrappers |
|
||||
| **Keyboard navigation** | Ensure all interactive elements work without a mouse |
|
||||
| **ARIA labels** | Add [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) roles and labels where semantic HTML alone is insufficient |
|
||||
| **Color contrast** | Verify contrast ratios with [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) |
|
||||
| **Alt text** | Provide descriptive `alt` for meaningful images; use `alt=""` for decorative ones |
|
||||
|
||||
- **Semantic HTML**: Use semantic HTML elements (`<button>`, `<label>`, `<nav>`, etc.) to ensure screen readers and other assistive technologies can properly interpret the interface.
|
||||
- **Keyboard Navigation**: Ensure all interactive elements are fully usable with a keyboard. Avoid mouse-only interactions.
|
||||
- **ARIA Labels**: When necessary, use appropriate [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) roles and labels to enhance accessibility, but do not replace semantic html with roles and labels.
|
||||
- **Color Contrast & Visual Indicators**: Use high-contrast colors and ensure visual indicators, like focus states, are clear. You can use tools like [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify your changes.
|
||||
- **Alt Text for Images**: Provide descriptive `alt` text for images and icons when they convey meaning, but equally important, if the image convays no information and is decorative in nature, use an empty alt text (`alt=""`).
|
||||
Test your changes with Lighthouse or your browser's accessibility tools.
|
||||
|
||||
To test you changes, you can use tools like lighthouse or the accessibility tools in your browser.
|
||||
---
|
||||
|
||||
Let's make Open WebUI usable for *everyone*.
|
||||
## Reporting Issues
|
||||
|
||||
### 🤔 Questions & Feedback
|
||||
Check the [Issues tab](https://github.com/open-webui/open-webui/issues) before opening a new one. When filing:
|
||||
|
||||
Got questions or feedback? Join our [Discord community](https://discord.gg/5rJgQTnV4s), visit our [Reddit](https://www.reddit.com/r/OpenWebUI/), or open an issue. We're here to help!
|
||||
|
||||
### 🚨 Reporting Issues
|
||||
|
||||
Noticed something off? Have an idea? Check our [Issues tab](https://github.com/open-webui/open-webui/issues) to see if it's already been reported or suggested. If not, feel free to open a new issue. When reporting an issue, please follow our issue templates. These templates are designed to ensure that all necessary details are provided from the start, enabling us to address your concerns more efficiently.
|
||||
|
||||
:::important
|
||||
|
||||
- **Template Compliance:** Please be aware that failure to follow the provided issue template, or not providing the requested information at all, will likely result in your issue being closed without further consideration. This approach is critical for maintaining the manageability and integrity of issue tracking.
|
||||
|
||||
- **Detail is Key:** To ensure your issue is understood and can be effectively addressed, it's imperative to include comprehensive details. Descriptions should be clear, including steps to reproduce, expected outcomes, and actual results. Lack of sufficient detail may hinder our ability to resolve your issue.
|
||||
|
||||
- **Respectful Communication:** All interactions — including issue reports and discussions — fall under our **[Code of Conduct](https://github.com/open-webui/open-webui/blob/main/CODE_OF_CONDUCT.md)**. Hostile, entitled, or demanding behavior toward contributors will not be tolerated.
|
||||
- **Use the issue template.** Issues that do not follow the template or lack requested information will be closed.
|
||||
- **Include reproduction steps.** Describe what you did, what you expected, and what actually happened.
|
||||
- **Be specific.** Vague reports ("it doesn't work") cannot be investigated effectively.
|
||||
|
||||
:::warning Scope of support
|
||||
Open WebUI supports Docker deployment, but we assume familiarity with Docker fundamentals. Issues related to reverse proxy configuration, container networking, or host OS setup are outside the project's support scope. Refer to the [official Docker documentation](https://docs.docker.com/get-started/overview/) for those topics.
|
||||
:::
|
||||
|
||||
### 🧭 Scope of Support
|
||||
---
|
||||
|
||||
We've noticed an uptick in issues not directly related to Open WebUI but rather to the environment it's run in, especially Docker setups. While we strive to support Docker deployment, understanding Docker fundamentals is crucial for a smooth experience.
|
||||
## Get in Touch
|
||||
|
||||
- **Docker Deployment Support**: Open WebUI supports Docker deployment. Familiarity with Docker is assumed. For Docker basics, please refer to the [official Docker documentation](https://docs.docker.com/get-started/overview/).
|
||||
|
||||
- **Advanced Configurations**: Setting up reverse proxies for HTTPS and managing Docker deployments requires foundational knowledge. There are numerous online resources available to learn these skills. Ensuring you have this knowledge will greatly enhance your experience with Open WebUI and similar projects.
|
||||
|
||||
## 🙏 Thank You!
|
||||
|
||||
Your contributions, big or small, make a significant impact on Open WebUI. We're excited to see what you bring to the project!
|
||||
|
||||
Together, let's create an even more powerful tool for the community. 🌟
|
||||
| Channel | Link |
|
||||
|---------|------|
|
||||
| **Discord** | [discord.gg/5rJgQTnV4s](https://discord.gg/5rJgQTnV4s) |
|
||||
| **Reddit** | [r/OpenWebUI](https://www.reddit.com/r/OpenWebUI/) |
|
||||
| **GitHub Issues** | [open-webui/open-webui/issues](https://github.com/open-webui/open-webui/issues) |
|
||||
| **GitHub Discussions** | [open-webui/open-webui/discussions](https://github.com/open-webui/open-webui/discussions) |
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
{
|
||||
"label": "Interface",
|
||||
"position": 900,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"label": "🔐 Admin & Security",
|
||||
"label": "🔧 Administration",
|
||||
"position": 10,
|
||||
"collapsible": true,
|
||||
"collapsed": true
|
||||
+4
-4
@@ -54,7 +54,7 @@ Your selected time period is **automatically saved** and persists across browser
|
||||
|
||||
### Group Filtering
|
||||
|
||||
If you have [user groups](/features/access-security/rbac/groups) configured, the Analytics dashboard allows filtering by group:
|
||||
If you have [user groups](/features/authentication-access/rbac/groups) configured, the Analytics dashboard allows filtering by group:
|
||||
|
||||
- Use the **group dropdown** next to the time period selector
|
||||
- Select a specific group to view analytics **only for users in that group**
|
||||
@@ -237,7 +237,7 @@ Example for GPT-4:
|
||||
- Compare **message counts** across models to see adoption rates
|
||||
- Check **token efficiency** (tokens per message) to identify verbose models
|
||||
- Monitor **trends** in the timeline chart after introducing new models
|
||||
- Combine with the [Evaluation feature](/features/access-security/evaluation/) for quality insights
|
||||
- Combine with the [Evaluation feature](/features/administration/evaluation/) for quality insights
|
||||
|
||||
### 3. Cost Management
|
||||
|
||||
@@ -408,6 +408,6 @@ Whether you're managing a personal instance or a large organizational deployment
|
||||
|
||||
## Related Features
|
||||
|
||||
- [**Evaluation**](/features/access-security/evaluation/) - Measure model quality through user feedback
|
||||
- [**RBAC**](../rbac/index.mdx) - Control access to models and features per user
|
||||
- [**Evaluation**](/features/administration/evaluation/) - Measure model quality through user feedback
|
||||
- [**RBAC**](/features/authentication-access/rbac) - Control access to models and features per user
|
||||
- [**Data Controls**](/features/chat-conversations/data-controls/) - Manage chat history and exports
|
||||
@@ -0,0 +1,72 @@
|
||||
---
|
||||
sidebar_position: 0
|
||||
title: "Administration"
|
||||
---
|
||||
|
||||
# 🔧 Administration
|
||||
|
||||
**Monitor usage, evaluate model quality, and communicate with your users, all from the Admin Panel.**
|
||||
|
||||
Open WebUI gives administrators a full operational toolkit. Track which models your team uses and how much they cost. Run blind evaluations to find the best model for your workload. Push announcements to every user with customizable banners. Wire up webhooks to get notified when users sign up or when long-running tasks finish.
|
||||
|
||||
---
|
||||
|
||||
## What's In This Section
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 📊 **[Analytics](./analytics)** | Usage dashboards with message volume, token consumption, model breakdowns, and per-user activity |
|
||||
| 🏆 **[Evaluation](./evaluation)** | Model arena, blind A/B testing, ELO-based leaderboards, and chat snapshots for fine-tuning |
|
||||
| 📢 **[Banners](./banners)** | Customizable system-wide announcements with dismissible notifications |
|
||||
| 🔔 **[Webhooks](./webhooks)** | Automated notifications for user sign-ups, chat completions, and external service integration |
|
||||
|
||||
---
|
||||
|
||||
## Analytics
|
||||
|
||||
Get a bird's-eye view of how your instance is being used. The analytics dashboard shows message volume, token consumption, model popularity, and user activity, filterable by time period and user group.
|
||||
|
||||
**Use it for:** capacity planning, cost estimation, identifying popular models, tracking adoption trends, and per-department usage reporting.
|
||||
|
||||
[**Learn about Analytics →**](./analytics)
|
||||
|
||||
---
|
||||
|
||||
## Evaluation
|
||||
|
||||
Not sure which model fits your team best? The evaluation system lets users rate model responses with thumbs up/down during normal conversations. Ratings feed into an ELO-based leaderboard, and rated chats are snapshotted for future model fine-tuning.
|
||||
|
||||
**Two evaluation modes:**
|
||||
- **Arena Mode**: Randomly selects models for blind comparison, removing bias
|
||||
- **Normal interaction**: Rate responses during regular use, then compare models by swapping them out
|
||||
|
||||
[**Learn about Evaluation →**](./evaluation)
|
||||
|
||||
---
|
||||
|
||||
## Banners
|
||||
|
||||
Push high-visibility messages to every logged-in user. Use banners for maintenance windows, incident alerts, policy reminders, and feature announcements. Configure via the Admin Panel or the `WEBUI_BANNERS` environment variable for GitOps workflows.
|
||||
|
||||
| Type | Color | Best for |
|
||||
|------|-------|----------|
|
||||
| `info` | Blue | General announcements |
|
||||
| `success` | Green | Resolved incidents, completed changes |
|
||||
| `warning` | Yellow | Planned maintenance, partial degradation |
|
||||
| `error` | Red | Active incidents, outages |
|
||||
|
||||
[**Learn about Banners →**](./banners)
|
||||
|
||||
---
|
||||
|
||||
## Webhooks
|
||||
|
||||
Three types of webhook integrations keep your external services in sync:
|
||||
|
||||
| Webhook | Purpose |
|
||||
|---------|---------|
|
||||
| **Admin Webhook** | Notifies a Slack/Discord channel when a new user signs up |
|
||||
| **User Webhook** | Notifies individual users when a long-running chat response is ready |
|
||||
| **Channel Webhooks** | Let external services (CI/CD, monitoring, scripts) post messages into Open WebUI channels |
|
||||
|
||||
[**Learn about Webhooks →**](./webhooks)
|
||||
@@ -1,176 +0,0 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: "Knowledge"
|
||||
---
|
||||
|
||||
Knowledge part of Open WebUI is like a memory bank that makes your interactions even more powerful and context-aware. Let's break down what "Knowledge" really means in Open WebUI, how it works, and why it's incredibly helpful for enhancing your experience.
|
||||
|
||||
## TL;DR
|
||||
|
||||
- **Knowledge** is a section in Open WebUI where you can store structured information that the system can refer to during your interactions.
|
||||
- It's like a memory system for Open WebUI that allows it to pull from saved data, making responses more personalized and contextually aware.
|
||||
- You can use Knowledge directly in your chats with Open WebUI to access the stored data whenever you need it.
|
||||
|
||||
Setting up Knowledge is straightforward! Simply navigate to **Workspace → Knowledge** in the sidebar and start adding details or data. You don't need coding expertise or technical setup; it's built into the core system!
|
||||
|
||||
## What is the "Knowledge" Section?
|
||||
|
||||
The **Knowledge section** is a storage area within Open WebUI where you can save specific pieces of information or data points. Think of it as a **reference library** that Open WebUI can use to make its responses more accurate and relevant to your needs.
|
||||
|
||||
### Why is Knowledge Useful?
|
||||
|
||||
Imagine you're working on a long-term project and want the system to remember certain parameters, settings, or even key notes about the project without having to remind it every time. Or perhaps, you want it to remember specific personal preferences for chats and responses. The Knowledge section is where you can store this kind of **persistent information** so that Open WebUI can reference it in future conversations, creating a more **coherent, personalized experience**.
|
||||
|
||||
Some examples of what you might store in Knowledge:
|
||||
|
||||
- Important project parameters or specific data points you'll frequently reference.
|
||||
- Custom commands, workflows, or settings you want to apply.
|
||||
- Personal preferences, guidelines, or rules that Open WebUI can follow in every chat.
|
||||
|
||||
### How to Use Knowledge in Chats
|
||||
|
||||
Accessing stored Knowledge in your chats is easy! By simply referencing what's saved (using '#' before the name), Open WebUI can pull in data or follow specific guidelines that you've set up in the Knowledge section.
|
||||
|
||||
For example:
|
||||
|
||||
- When discussing a project, Open WebUI can automatically recall your specified project details.
|
||||
- It can apply custom preferences to responses, like formality levels or preferred phrasing.
|
||||
|
||||
To reference Knowledge in your chats, just ensure it's saved in the Knowledge section, and Open WebUI will know when and where to bring in the relevant information!
|
||||
|
||||
Admins can add knowledge to the workspace, which users can access and use; however, users do not have direct access to the workspace itself.
|
||||
|
||||
### Native Mode (Agentic Mode) Knowledge Tools
|
||||
|
||||
When using **Native Function Calling (Agentic Mode)**, quality models can interact with your Knowledge Bases autonomously using built-in tools:
|
||||
|
||||
:::tip Quality Models for Knowledge Exploration
|
||||
Autonomous knowledge base exploration works best with frontier models (GPT-5, Claude 4.5+, Gemini 3+) that can intelligently search, browse, and synthesize information from multiple documents. Small local models may struggle with multi-step knowledge retrieval.
|
||||
:::
|
||||
|
||||
- **`list_knowledge`**: List all knowledge bases, files, and notes attached to the current model with file details. **Use this first** to discover what knowledge is available. Only available when the model has attached knowledge.
|
||||
- **`query_knowledge_files`**: Search file contents using retrieval over the configured RAG pipeline (including hybrid search/reranking when `ENABLE_RAG_HYBRID_SEARCH` is enabled). When a KB is attached to the model, searches are automatically scoped. This should be the model's first choice for finding information before searching the web.
|
||||
- **`search_knowledge_files`**: Search files by filename. Available in both modes; auto-scopes to attached KBs when the model has attached knowledge.
|
||||
- **`list_knowledge_bases`**: Browse available knowledge bases with file counts. Only available when the model has **no** attached knowledge.
|
||||
- **`search_knowledge_bases`**: Find specific knowledge bases by name or description. Only available when the model has **no** attached knowledge.
|
||||
- **`query_knowledge_bases`**: Search KB names/descriptions by semantic similarity. Only available when the model has **no** attached knowledge.
|
||||
- **`view_file`** / **`view_knowledge_file`**: Read file content with pagination support (`offset` and `max_chars` parameters for large files, default 10K chars, hard cap 100K).
|
||||
|
||||
These tools enable models to autonomously explore and retrieve information from your knowledge bases, making conversations more contextually aware and grounded in your stored documents.
|
||||
|
||||
#### Knowledge Scoping with Native Function Calling
|
||||
|
||||
When native function calling is enabled, the model's access to knowledge bases depends on whether you've attached specific knowledge to the model:
|
||||
|
||||
| Model Configuration | Knowledge Access |
|
||||
|-------------------|------------------|
|
||||
| **No KB attached** | Model can access **all** knowledge bases the user has access to (public KBs, user's own KBs) |
|
||||
| **KB attached to model** | Model is **limited** to only the attached knowledge base(s) |
|
||||
|
||||
Knowledge tool availability at a glance:
|
||||
|
||||
| Tool | Model has attached knowledge | Model has no attached knowledge |
|
||||
|------|------------------------------|---------------------------------|
|
||||
| `list_knowledge` | ✅ | ❌ |
|
||||
| `list_knowledge_bases` | ❌ | ✅ |
|
||||
| `search_knowledge_bases` | ❌ | ✅ |
|
||||
| `query_knowledge_bases` | ❌ | ✅ |
|
||||
| `search_knowledge_files` | ✅ (auto-scoped) | ✅ (all accessible KBs) |
|
||||
| `query_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.
|
||||
|
||||
:::warning Knowledge is NOT Auto-Injected with Native Function Calling
|
||||
|
||||
**Important behavioral difference:** When using Native Function Calling, attached knowledge is **not automatically injected** into the conversation. Instead, the model must actively call the knowledge tools to search and retrieve information.
|
||||
|
||||
**If your model isn't using attached knowledge:**
|
||||
|
||||
1. **Add instructions to your system prompt** telling the model to discover and query knowledge bases. For example:
|
||||
> "When users ask questions, first use list_knowledge to see what knowledge is available, then use query_knowledge_files to search the relevant knowledge base before answering. If no knowledge is attached to this model, use list_knowledge_bases first to discover available KBs."
|
||||
|
||||
2. **Or disable Native Function Calling** for that model to restore the automatic RAG injection behavior from earlier versions.
|
||||
|
||||
3. **Or use "Full Context" mode** for the attached knowledge (click on the attachment and select "Use Entire Document") which bypasses RAG and always injects the full content.
|
||||
|
||||
:::
|
||||
|
||||
:::tip Restricting Knowledge Access
|
||||
If you want a model to focus on specific documents, attach those knowledge bases to the model in **Workspace > Models > Edit**. This prevents the model from searching other available knowledge bases.
|
||||
:::
|
||||
|
||||
### Full Context vs Focused Retrieval
|
||||
|
||||
When attaching files, notes, or knowledge bases to a model, you can choose between two retrieval modes by clicking on the attached item:
|
||||
|
||||
#### 🔍 Focused Retrieval (Default)
|
||||
|
||||
- Uses **RAG (Retrieval Augmented Generation)** to find relevant chunks
|
||||
- Only injects the most relevant portions of documents based on the user's query
|
||||
- When **hybrid search** is enabled (`ENABLE_RAG_HYBRID_SEARCH`), retrieval uses BM25 keyword search combined with vector search, plus reranking for improved accuracy — this applies to both the standard RAG pipeline and native knowledge tool retrieval paths
|
||||
- Best for large documents or knowledge bases where only specific sections are relevant
|
||||
- With native function calling enabled, the model decides when to search
|
||||
|
||||
#### 📄 Using Entire Document (Full Context)
|
||||
|
||||
- Injects the **complete content** of the file/note into every message
|
||||
- Bypasses RAG entirely—no chunking or semantic search
|
||||
- Best for short reference documents, style guides, or context that's always relevant
|
||||
- **Always injected** regardless of native function calling settings
|
||||
|
||||
:::info Full Context with Native Function Calling
|
||||
When "Using Entire Document" is enabled for a file or knowledge base, its content is **always injected** into the conversation, even when native function calling is enabled. The model does not need to call any tools to access this content—it's automatically included in the context.
|
||||
|
||||
Files set to Focused Retrieval (the default) will only be accessed when the model calls the appropriate knowledge tools.
|
||||
:::
|
||||
|
||||
:::note Per-Model Control
|
||||
The Knowledge Base tools require the **Knowledge Base** category to be enabled for the model in **Workspace > Models > Edit > Builtin Tools** (enabled by default). Administrators can disable this category per-model to prevent autonomous knowledge base access.
|
||||
:::
|
||||
|
||||
:::info Central Tool Documentation
|
||||
For complete details on all built-in agentic tools and how to configure them, see the [**Native/Agentic Mode Tools Guide**](/features/extensibility/plugin/tools#built-in-system-tools-nativeagentic-mode).
|
||||
:::
|
||||
|
||||
### Setting Up Your Knowledge Base
|
||||
|
||||
1. **Navigate to the Knowledge Section**: Click **Workspace** in the sidebar, then select **Knowledge**. This area is designed to be user-friendly and intuitive.
|
||||
2. **Add Entries**: Input information you want Open WebUI to remember. It can be as specific or broad as you like.
|
||||
3. **Save and Apply**: Once saved, the Knowledge is accessible and ready to enhance your chat interactions.
|
||||
|
||||
### Exporting a Knowledge Base
|
||||
|
||||
Admins can export an entire knowledge base as a downloadable zip file. This is useful for backing up your knowledge, migrating data between instances, or sharing curated knowledge collections with others.
|
||||
|
||||
To export a knowledge base, open the item menu (three dots) on any knowledge base entry and select **Export**. The system will generate a zip archive containing all files from that knowledge base, converted to `.txt` format for universal compatibility. The zip file will be named after the knowledge base itself.
|
||||
|
||||
:::note Admin Only
|
||||
The export feature is restricted to admin users. Regular users will not see the Export option in the menu.
|
||||
:::
|
||||
|
||||
### Programmatic Access via API
|
||||
|
||||
Knowledge bases can also be managed programmatically through the Open WebUI API. This is useful for automated workflows, bulk imports, or integrating with external systems.
|
||||
|
||||
Key API endpoints:
|
||||
- `POST /api/v1/files/` - Upload files
|
||||
- `GET /api/v1/files/{id}/process/status` - Check file processing status
|
||||
- `POST /api/v1/knowledge/{id}/file/add` - Add files to a knowledge base
|
||||
|
||||
:::warning Important: Async File Processing
|
||||
When uploading files via API, processing happens asynchronously. You **must** wait for file processing to complete before adding files to a knowledge base, or you will receive an "empty content" error.
|
||||
|
||||
For detailed examples and proper workflow handling, see the [API Endpoints documentation](/reference/api-endpoints#-retrieval-augmented-generation-rag).
|
||||
:::
|
||||
|
||||
## Summary
|
||||
|
||||
- The Knowledge section is like Open WebUI's "memory bank," where you can store data that you want it to remember and use.
|
||||
- **Use Knowledge to keep the system aware** of important details, ensuring a personalized chat experience.
|
||||
- You can **directly reference Knowledge in chats** to bring in stored data whenever you need it using '#' + name of the knowlege.
|
||||
- **Admins can export knowledge bases** as zip files for backup, migration, or sharing purposes.
|
||||
|
||||
🌟 Remember, there's always more to discover, so dive in and make Open WebUI truly your own!
|
||||
@@ -1,195 +0,0 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: "Models"
|
||||
sidebar_label: "Models"
|
||||
---
|
||||
|
||||
The `Models` section of the `Workspace` within Open WebUI is a powerful tool that allows you to create and manage custom models tailored to specific purposes.
|
||||
|
||||
While backends like Ollama have their own `Modelfile` format, Open WebUI employs a robust internal **Preset System**. This allows you to "wrap" any model (including GPT-4, Claude, or local Llama 3) to bind specific **System Prompts**, **Knowledge Collections**, **Tools**, and **Dynamic Variables** to it.
|
||||
|
||||
This section serves as a central hub for all your models, providing a range of features to edit, clone, share, export, and hide your custom agents.
|
||||
|
||||
## Creating and Editing Models
|
||||
|
||||
When you create a new model or edit an existing one, you are building a configuration wrapper around a "Base Model".
|
||||
To access the model configuration interface, you have two primary entry points from the main Models list:
|
||||
|
||||
1. **New Model**: Click the **+ New Model** button in the top-right corner. This opens a blank configuration page to create a preset from scratch.
|
||||
2. **Edit Model**: Click the ellipsis (**...**) on an existing model card and select **Edit**. This opens the configuration page pre-filled with that model's current settings.
|
||||
|
||||
Both actions lead to the same Model Builder interface, where you can configure the settings below.
|
||||
|
||||
### Core Configuration
|
||||
|
||||
- **Avatar Photo**: Upload a custom image to represent your model in the chat interface. **Animated formats** (GIF and WebP) are supported and their animations will be preserved during the upload process.
|
||||
- **Model Name & ID**: The display name and unique identifier for your custom preset (e.g., "Python Tutor" or "Meeting Summarizer").
|
||||
- **Base Model**: The actual model beneath the hood that powers the agent. You can choose *any* model connected to Open WebUI. You can create a custom preset for `gpt-4o` just as easily as `llama3`.
|
||||
- **Fallback Behavior**: If the configured Base Model is unavailable and the `ENABLE_CUSTOM_MODEL_FALLBACK` environment variable is set to `True`, the system will automatically fall back to the first configured default model (set in Admin Panel > Settings > Models > Default Models). This ensures mission-critical custom models remain functional even if their specific base model is removed or temporarily unavailable.
|
||||
- **Description**: A short summary of what the model does.
|
||||
- **Tags**: Add tags to organize models in the selector dropdown.
|
||||
- **Visibility & Groups**:
|
||||
- **Private**: Restricts access to specific users or groups.
|
||||
- **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
|
||||
|
||||
The **System Prompt** defines the behavior and persona of the model. Unlike standard prompts, Open WebUI supports **Dynamic Variable Injection** using Jinja2-style placeholders. This allows the model to be aware of time, date, and user details.
|
||||
|
||||
| Variable | Description | Output Example |
|
||||
| :--- | :--- | :--- |
|
||||
| `{{ CURRENT_DATE }}` | Injects today's date (YYYY-MM-DD). | `2024-10-27` |
|
||||
| `{{ CURRENT_TIME }}` | Injects the current time (24hr). | `14:30:05` |
|
||||
| `{{ USER_NAME }}` | The display name of the logged-in user. | `Admin` |
|
||||
|
||||
**Example System Prompt:**
|
||||
|
||||
```
|
||||
You are a helpful assistant for {{ USER_NAME }}.
|
||||
The current date is {{ CURRENT_DATE }}.
|
||||
```
|
||||
|
||||
### Advanced Parameters
|
||||
|
||||
Clicking **Show** on **Advanced Params** allows you to fine-tune the inference generation.
|
||||
|
||||
- **Stop Sequences**: A powerful feature that tells the model to force-stop generating text when it hits specific characters. This is vital for roleplay or coding models to prevent them from hallucinating both sides of a conversation.
|
||||
- *Format:* Enter the string (e.g., `<|end_of_text|>`, `User:`) and press `Enter`.
|
||||
- **Temperature, Top P, etc.**: Adjust the creativity and determinism of the model.
|
||||
|
||||
### Prompt Suggestions
|
||||
|
||||
**Prompt Suggestions** are clickable "starter chips" that appear above the input bar when a user opens a fresh chat with this model. These are vital for onboarding users to specialized agents.
|
||||
|
||||
- **Purpose**: To guide the user on what the model is capable of or to provide one-click shortcuts for common tasks.
|
||||
- **How to add**: Type a phrase (e.g., "Summarize this text") and click the **+** button. You can add multiple suggestions.
|
||||
- **Example**: For a "Python Tutor" model, you might add:
|
||||
- *"Explain this code step-by-step"*
|
||||
- *"Find bugs in the following script"*
|
||||
- *"Write a Unit Test for this function"*
|
||||
|
||||
### Capabilities, Binding & Defaults
|
||||
|
||||
You can transform a generic model into a specialized agent by toggling specific capabilities and binding resources.
|
||||
|
||||
- **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/ai-knowledge/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/ai-knowledge/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:
|
||||
- **Vision**: Toggle to enable image analysis capabilities (requires a vision-capable Base Model).
|
||||
- **Web Search**: Enable the model to access the configured search provider (e.g., Google, SearxNG) for real-time information.
|
||||
- **File Upload**: Allow users to upload files to this model.
|
||||
- **File Context**: When enabled (default), attached files are processed via RAG and their content is injected into the conversation. When disabled, file content is **not** extracted or injected—the model receives no file content unless it retrieves it via builtin tools. Only visible when File Upload is enabled. See [File Context vs Builtin Tools](/features/chat-conversations/rag#file-context-vs-builtin-tools) for details.
|
||||
- **Code Interpreter**: Enable Python code execution. See [Python Code Execution](/features/chat-conversations/chat-features/code-execution/python) for details.
|
||||
- **Image Generation**: Enable image generation integration.
|
||||
- **Usage / Citations**: Toggle usage tracking or source citations.
|
||||
- **Status Updates**: Show visible progress steps in the chat UI (e.g., "Searching web...", "Reading file...") during generation. Useful for slower, complex tasks.
|
||||
- **Builtin Tools**: When enabled (default), automatically injects system tools (timestamps, memory, chat history, knowledge base queries, notes, etc.) in [Native Function Calling mode](/features/extensibility/plugin/tools#disabling-builtin-tools-per-model). When enabled, you can further control which **tool categories** are available (Time, Memory, Chats, Notes, Knowledge, Channels) via checkboxes in the Model Editor. Disable the main toggle if the model doesn't support function calling or you need to save context window tokens. Note: This is separate from **File Context**—see [File Context vs Builtin Tools](/features/chat-conversations/rag#file-context-vs-builtin-tools) for the difference.
|
||||
- **TTS Voice**: Set a specific Text-to-Speech voice for this model. When users read responses aloud, this voice will be used instead of the global default. Useful for giving different personas distinct voices. Leave empty to use the user's settings or system default. See [Per-Model TTS Voice](/features/media-generation/audio/text-to-speech/openai-tts-integration#per-model-tts-voice) for details.
|
||||
- **Default Features**: Force specific toggles (like Web Search) to be "On" immediately when a user starts a chat with this model.
|
||||
|
||||
## Model Management
|
||||
|
||||
From the main list view in the `Models` section, click the ellipsis (`...`) next to any model to perform actions:
|
||||
|
||||
- **Edit**: Open the configuration panel for this model.
|
||||
- **Hide**: Hide the model from the model selector dropdown within chats (useful for deprecated models) without deleting it.
|
||||
- **Clone**: Create a copy of a model configuration, which will be appended with `-clone`.
|
||||
|
||||
:::note
|
||||
A raw Base Model can be cloned as a custom Workspace model, but it will not clone the raw Base Model itself.
|
||||
:::
|
||||
|
||||
- **Copy Link**: Copies a direct URL to the model settings.
|
||||
- **Export**: Download the model configuration as a `.json` file.
|
||||
- **Share**: Share your model configuration with the Open WebUI community by clicking the `Share` button (redirects to [openwebui.com](https://openwebui.com/models/create)).
|
||||
- **Delete**: Permanently remove the preset.
|
||||
|
||||
### Import and Export
|
||||
|
||||
- **Import Models**: Import models from a `.json` file or from Open WebUI community links.
|
||||
- **Export Models**: Export all your custom model configurations into a single `.json` file for backup or migration.
|
||||
- **Discover a Model**: At the bottom of the page, you can explore and download presets made by the Open WebUI community.
|
||||
|
||||
:::info Downloading Raw Models
|
||||
To download new raw Base Models (like `Llama-3.2-3B-Instruct-GGUF:Q8_0` or `Mistral-7B-Instruct-v0.2-GGUF:Q4_K_M`), navigate to **Settings > Connections > Ollama**. Alternatively, type `ollama run hf.co/{username}/{repository}:{quantization}` in the model selector to pull directly from Hugging Face. This action will create a button within the model selector labeled "Pull [Model Name]" that will begin downloading the model from its source once clicked.
|
||||
:::
|
||||
|
||||
## Global Model Management (Admin)
|
||||
|
||||
Administrators have access to a centralized management interface via **Admin Panel > Settings > Models**. This page provides powerful tools for decluttering and organizing the model list, especially when connected to providers with hundreds of available models.
|
||||
|
||||
### View Filtering
|
||||
|
||||
The **Admin View Selector** allows you to filter the entire list of models by their operational status. This is located next to the search bar and includes the following views:
|
||||
|
||||
- **All**: Shows every model available to the system.
|
||||
- **Enabled**: Displays only models that are currently active and selectable by users.
|
||||
- **Disabled**: Shows models that have been deactivated.
|
||||
- **Visible**: Shows models that are currently visible in the user model selector.
|
||||
- **Hidden**: Displays only the models that have been hidden (these appear with reduced opacity in the list).
|
||||
|
||||
### Bulk Actions
|
||||
|
||||
To streamline the management of large model collections, the Admin Panel includes **Bulk Actions** that apply to the models currently visible in your filtered view.
|
||||
|
||||
1. **Filter your view** (e.g., select "Disabled" or "Hidden").
|
||||
2. **Open the Actions menu** (Ellipsis icon next to the search bar).
|
||||
3. **Select an action**:
|
||||
- **Enable All**: Activates all models in the current filtered list simultaneously.
|
||||
- **Disable All**: Deactivates all models in the current filtered list.
|
||||
|
||||
These tools are specifically designed to help administrators quickly manage external providers (like OpenAI or Anthropic) that expose a high volume of models, allowing for instant site-wide configuration changes.
|
||||
|
||||
### Global Model Defaults
|
||||
|
||||
Administrators can set **global default metadata and parameters** that apply as a baseline to all models. This eliminates the need to manually configure capabilities and inference settings for every model individually.
|
||||
|
||||
- **Default Model Metadata** (`DEFAULT_MODEL_METADATA`): Sets baseline capabilities (vision, web search, file context, code interpreter, builtin tools, etc.) and other model metadata for all models. For capabilities, defaults and per-model values are merged — per-model overrides always win on conflicts. For other metadata fields, the global default is only applied when a model has no value set.
|
||||
- **Default Model Params** (`DEFAULT_MODEL_PARAMS`): Sets baseline inference parameters (temperature, top_p, max_tokens, seed, function_calling, etc.) for all models. Per-model parameter overrides always take precedence — but only when a per-model value is explicitly set. This value is loaded from the environment as JSON; invalid JSON is ignored and falls back to `{}`.
|
||||
|
||||
These settings are accessible via **Admin Settings → Models → ⚙️ (gear icon)** and are persisted via `PersistentConfig`. See [`DEFAULT_MODEL_METADATA`](/reference/env-configuration#default_model_metadata) and [`DEFAULT_MODEL_PARAMS`](/reference/env-configuration#default_model_params) for details.
|
||||
|
||||
#### Merge Behavior
|
||||
|
||||
Understanding how defaults combine with per-model settings is important:
|
||||
|
||||
| Setting Type | Merge Strategy | Example |
|
||||
|---|---|---|
|
||||
| **Capabilities** (metadata) | Deep merge: `{...global, ...per_model}` | Global sets `file_context: false`, model sets `vision: true` → model gets both |
|
||||
| **Other metadata** (description, tags, etc.) | Fill-only: global applied when model value is `None` | Global sets `description: "Default"`, model has no description → model gets "Default" |
|
||||
| **Parameters** | Simple merge: `{...global, ...per_model}` | Global sets `temperature: 0.7`, model sets `temperature: 0.3` → model gets `0.3` |
|
||||
|
||||
The key subtlety: **if a model doesn't explicitly set a parameter, the global default is the only value**. This is especially important for `function_calling` — see the warning below.
|
||||
|
||||
:::warning Knowledge Base + Function Calling Interaction
|
||||
Setting `function_calling: native` in Global Model Params changes how **all** models handle attached Knowledge Bases. In native mode, model-attached KBs are **not** auto-injected via RAG — instead, the model must autonomously call builtin tools to retrieve knowledge. If a model doesn't explicitly override `function_calling` in its own Advanced Params, it inherits the global value silently.
|
||||
|
||||
Additionally, if `file_context` is disabled in Global Model Capabilities, the RAG retrieval handler is skipped for all models that don't explicitly enable it — meaning attached files and KBs produce no results.
|
||||
|
||||
If your models' attached Knowledge Bases are not working, check global defaults first. See [Knowledge Base Attached to Model Not Working](/troubleshooting/rag#13-knowledge-base-attached-to-model-not-working) for detailed troubleshooting steps.
|
||||
:::
|
||||
|
||||
:::tip
|
||||
Global defaults are ideal for enforcing organizational policies — for example, disabling code interpreter by default across all models, or setting a consistent temperature for all models. However, be cautious with `function_calling` and capability toggles, as they can have unexpected effects on Knowledge Base behavior.
|
||||
:::
|
||||
|
||||
## Model Switching in Chat
|
||||
|
||||
Open WebUI allows for dynamic model switching and parallel inference within a chat session.
|
||||
|
||||
**Example**: Switching between **Mistral**, **LLaVA**, and **GPT-4** in a Multi-Stage Task.
|
||||
|
||||
- **Scenario**: A multi-stage conversation involves different task types, such as starting with a simple FAQ, interpreting an image, and then generating a creative response.
|
||||
- **Reason for Switching**: The user can leverage each model's specific strengths for each stage:
|
||||
- **Mistral** for general questions to reduce computation time and costs.
|
||||
- **LLaVA** for visual tasks to gain insights from image-based data.
|
||||
- **GPT-4** for generating more sophisticated and nuanced language output.
|
||||
- **Process**: The user switches between models, depending on the task type, to maximize efficiency and response quality.
|
||||
|
||||
**How To:**
|
||||
|
||||
1. **Select the Model**: Within the chat interface, select the desired models from the model switcher dropdown. You can select up to two models simultaneously, and both responses will be generated. You can then navigate between them by using the back and forth arrows.
|
||||
2. **Context Preservation**: Open WebUI retains the conversation context across model switches, allowing smooth transitions.
|
||||
@@ -1,407 +0,0 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "Prompts"
|
||||
---
|
||||
|
||||
The `Prompts` section of the `Workspace` within Open WebUI enables users to create, manage, and share custom prompts. This feature streamlines interactions with AI models by allowing users to save frequently used prompts and easily access them through slash commands.
|
||||
|
||||
### Prompt Management
|
||||
|
||||
The Prompts interface provides several key features for managing your custom prompts:
|
||||
|
||||
* **Create**: Design new prompts with customizable names, tags, access levels, and content.
|
||||
* **Share**: Share prompts with other users based on configured access permissions.
|
||||
* **Access Control**: Set visibility and usage permissions for each prompt (refer to [Permissions](/features/access-security/rbac/permissions) for more details).
|
||||
* **Enable/Disable**: Toggle prompts on or off without deleting them. Disabled prompts won't appear in slash command suggestions but remain in your workspace for future use.
|
||||
* **Slash Commands**: Quickly access prompts using custom slash commands during chat sessions.
|
||||
* **Versioning & History**: Track every change with a full version history, allowing you to compare and revert to previous versions.
|
||||
* **Tags & Filtering**: Organize your prompts using tags and easily filter through your collection in the workspace.
|
||||
|
||||
### Creating and Editing Prompts
|
||||
|
||||
When creating or editing a prompt, you can configure the following settings:
|
||||
|
||||
* **Name**: Give your prompt a descriptive name for easy identification.
|
||||
* **Tags**: Categorize your prompts with tags to make them easier to find and filter in your workspace.
|
||||
* **Access**: Set the access level to control who can view and use the prompt.
|
||||
* **Command**: Define a slash command that will trigger the prompt (e.g., `/summarize`). Commands are triggered in the chat by typing `/` followed by the command name.
|
||||
* **Prompt Content**: Write the actual prompt text that will be sent to the model.
|
||||
* **Commit Message**: When saving changes, you can provide an optional commit message to describe what was updated in this version.
|
||||
|
||||
### Prompt Variables
|
||||
|
||||
Open WebUI supports two kinds of variables to make your prompts more dynamic and powerful: **System Variables** and **Custom Input Variables**.
|
||||
|
||||
**System Variables** are automatically replaced with their corresponding value when the prompt is used. They are useful for inserting dynamic information like the current date or user details.
|
||||
|
||||
* **Clipboard Content**: Use `{{CLIPBOARD}}` to insert content from your clipboard.
|
||||
* **Date and Time**:
|
||||
* `{{CURRENT_DATE}}`: Current date
|
||||
* `{{CURRENT_DATETIME}}`: Current date and time
|
||||
* `{{CURRENT_TIME}}`: Current time
|
||||
* `{{CURRENT_TIMEZONE}}`: Current timezone
|
||||
* `{{CURRENT_WEEKDAY}}`: Current day of the week
|
||||
* **User Information**:
|
||||
* `{{USER_NAME}}`: Current user's name
|
||||
* `{{USER_EMAIL}}`: Current user's email address
|
||||
* `{{USER_BIO}}`: Current user's bio. Configured in **Settings > Account > User Profile**. If not set, the variable remains unreplaced.
|
||||
* `{{USER_GENDER}}`: Current user's gender. Configured in **Settings > Account > User Profile**. If not set, the variable remains unreplaced.
|
||||
* `{{USER_BIRTH_DATE}}`: Current user's birth date. Configured in **Settings > Account > User Profile**. If not set, the variable remains unreplaced.
|
||||
* `{{USER_AGE}}`: Current user's age, calculated from birth date. If birth date is not set, the variable remains unreplaced.
|
||||
* `{{USER_LANGUAGE}}`: User's selected language
|
||||
* `{{USER_LOCATION}}`: User's location (requires HTTPS and Settings > Interface toggle)
|
||||
|
||||
**Custom Input Variables** transform your prompts into interactive templates. When you use a prompt containing these variables, a modal window will automatically appear, allowing you to fill in your values. This is extremely powerful for creating complex, reusable prompts that function like forms. See the guidelines below for a full explanation.
|
||||
|
||||
By leveraging custom input variables, you can move beyond static text and build interactive tools directly within the chat interface. This feature is designed to be foolproof, enabling even non-technical users to execute complex, multi-step prompts with ease. Instead of manually editing a large block of text, users are presented with a clean, structured form. This not only streamlines the workflow but also reduces errors by guiding the user to provide exactly the right information in the right format. It unlocks a new level of interactive prompt design, making sophisticated AI usage accessible to everyone.
|
||||
|
||||
### Variable Usage Guidelines
|
||||
|
||||
* Enclose all variables with double curly braces: `{{variable}}`
|
||||
* **All custom input variables are optional by default** - users can leave fields blank when filling out the form
|
||||
* Use the `:required` flag to make specific variables mandatory when necessary
|
||||
* The `{{USER_LOCATION}}` system variable requires:
|
||||
* A secure HTTPS connection
|
||||
* Enabling the feature in `Settings` > `Interface`
|
||||
* The `{{CLIPBOARD}}` system variable requires clipboard access permission from your device.
|
||||
|
||||
---
|
||||
|
||||
#### Advanced Variable Modifiers
|
||||
|
||||
Certain system variables like `{{prompt}}` and `{{MESSAGES}}` support optional modifiers to control their length and which part of the content is included. This is particularly useful for managing context window limits.
|
||||
|
||||
##### Prompt Modifiers
|
||||
|
||||
The `{{prompt}}` variable supports character-based truncation:
|
||||
|
||||
* **Start Truncation**: `{{prompt:start:N}}` - Includes only the first **N** characters of the content.
|
||||
* **End Truncation**: `{{prompt:end:N}}` - Includes only the last **N** characters of the content.
|
||||
* **Middle Truncation**: `{{prompt:middletruncate:N}}` - Includes a total of **N** characters, taking half from the beginning and half from the end, with `...` in the middle.
|
||||
|
||||
##### Messages Variable: Two Types of Modifiers
|
||||
|
||||
The `{{MESSAGES}}` variable has **two distinct modifier types** that work at different levels:
|
||||
|
||||
| Modifier Type | Syntax | What It Controls | Example |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Message Selector** (colon `:`) | `{{MESSAGES:SELECTOR:N}}` | **How many messages** to include | `{{MESSAGES:END:5}}` = last 5 messages |
|
||||
| **Pipe Filter** (pipe `\|`) | `\{\{MESSAGES\|filter:N\}\}` | **Character limit per message** | `\{\{MESSAGES\|middletruncate:500\}\}` = each message to 500 chars |
|
||||
|
||||
:::warning Important Distinction
|
||||
|
||||
**Message selectors control MESSAGE COUNT, not token count or character count.**
|
||||
|
||||
- `{{MESSAGES:MIDDLETRUNCATE:500}}` selects **500 messages** (not 500 tokens/characters)
|
||||
- If you have 600 messages, it keeps the first ~250 and last ~250 messages
|
||||
- This does **not** truncate the content of each message
|
||||
|
||||
To limit content length, use **pipe filters** instead.
|
||||
|
||||
:::
|
||||
|
||||
##### Message Selectors
|
||||
|
||||
Message selectors control **how many messages** are included in the output:
|
||||
|
||||
| Selector | Description | Example |
|
||||
| :--- | :--- | :--- |
|
||||
| `START:N` | First N messages | `{{MESSAGES:START:5}}` = first 5 messages |
|
||||
| `END:N` | Last N messages | `{{MESSAGES:END:5}}` = last 5 messages |
|
||||
| `MIDDLETRUNCATE:N` | First half + last half (total N messages) | `{{MESSAGES:MIDDLETRUNCATE:6}}` = first 3 + last 3 messages |
|
||||
|
||||
**How MIDDLETRUNCATE works for messages:**
|
||||
|
||||
If you have 20 messages and use `{{MESSAGES:MIDDLETRUNCATE:6}}`:
|
||||
- Takes the first 3 messages
|
||||
- Takes the last 3 messages
|
||||
- Skips the 14 messages in the middle
|
||||
- Result: 6 messages total
|
||||
|
||||
##### Pipe Filters (Per-Message Content Truncation)
|
||||
|
||||
Pipe filters truncate the **content of each individual message** to a character limit. This is especially useful for task model prompts (title generation, tags, follow-ups) where conversations contain very long messages — for example, pasted documents or code.
|
||||
|
||||
| Filter | Description | Example |
|
||||
| :--- | :--- | :--- |
|
||||
| `\|start:N` | First N characters of each message | `\{\{MESSAGES\|start:300\}\}` |
|
||||
| `\|end:N` | Last N characters of each message | `\{\{MESSAGES\|end:300\}\}` |
|
||||
| `\|middletruncate:N` | First half + last half of each message (N chars total) | `\{\{MESSAGES\|middletruncate:500\}\}` |
|
||||
|
||||
##### Combining Message Selectors and Pipe Filters
|
||||
|
||||
You can combine both modifiers to control both **which messages** are included and **how long** each message's content is:
|
||||
|
||||
**Syntax:** `{{MESSAGES:SELECTOR:N|filter:N}}`
|
||||
|
||||
| Combined Syntax | What It Does |
|
||||
| :--- | :--- |
|
||||
| `\{\{MESSAGES\|middletruncate:500\}\}` | All messages, each truncated to 500 characters |
|
||||
| `\{\{MESSAGES:END:2\|middletruncate:500\}\}` | Last 2 messages, each truncated to 500 characters |
|
||||
| `\{\{MESSAGES:START:5\|start:200\}\}` | First 5 messages, each truncated to first 200 characters |
|
||||
| `\{\{MESSAGES:MIDDLETRUNCATE:10\|middletruncate:50\}\}` | First 5 + last 5 messages, each truncated to 50 characters |
|
||||
|
||||
##### Practical Examples
|
||||
|
||||
**Example 1: Title Generation with Limited Context**
|
||||
|
||||
```txt
|
||||
Chat history:
|
||||
<chat_history>
|
||||
{{MESSAGES:END:2|middletruncate:500}}
|
||||
</chat_history>
|
||||
|
||||
Generate a short title for this conversation.
|
||||
```
|
||||
|
||||
This sends only the last 2 messages, each limited to 500 characters — ideal for generating titles without processing entire pasted documents.
|
||||
|
||||
**Example 2: Summarization with Message Sampling**
|
||||
|
||||
```txt
|
||||
Conversation summary:
|
||||
{{MESSAGES:MIDDLETRUNCATE:10|start:300}}
|
||||
|
||||
Summarize the key points.
|
||||
```
|
||||
|
||||
This takes the first 5 and last 5 messages (skipping the middle), and each message is truncated to its first 300 characters.
|
||||
|
||||
**Example 3: Avoiding Common Mistakes**
|
||||
|
||||
| Wrong | Right | Why |
|
||||
| :--- | :--- | :--- |
|
||||
| `\{\{MESSAGES:MIDDLETRUNCATE:500\}\}` expecting 500 tokens | `\{\{MESSAGES\|middletruncate:500\}\}` | The first selects 500 **messages**, the second limits each message to 500 **characters** |
|
||||
| `\{\{MESSAGES:END:2\}\}` expecting 2000 chars | `\{\{MESSAGES:END:2\|middletruncate:1000\}\}` | Without a pipe filter, messages may be thousands of characters each |
|
||||
|
||||
:::tip
|
||||
|
||||
Using pipe filters on task model templates (title generation, tag generation, follow-up suggestions) is highly recommended for deployments that handle long conversations. Without pipe filters, a single message containing a pasted document could consume your entire context window.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
#### Using Custom Input Variables
|
||||
|
||||
**How It Works**
|
||||
|
||||
1. **Create a prompt** with one or more custom variables using the syntax below.
|
||||
2. **Use the prompt's slash command** in the chat input.
|
||||
3. An **"Input Variables" popup window** will appear with a form field for each variable you defined.
|
||||
4. **Fill out the form** and click `Save`. Note that by default, all fields are optional unless explicitly marked as required.
|
||||
5. The variables in your prompt will be replaced with your input, and the final prompt will be sent to the model.
|
||||
|
||||
**Syntax**
|
||||
|
||||
There are two ways to define a custom variable:
|
||||
|
||||
1. **Simple Input**: `{{variable_name}}`
|
||||
* This creates a standard, single-line `text` type input field in the popup window.
|
||||
* The field will be optional by default.
|
||||
|
||||
2. **Typed Input**: `{{variable_name | [type][:property="value"]}}`
|
||||
* This allows you to specify the type of input field (e.g., a dropdown, a date picker) and configure its properties.
|
||||
* The field will be optional by default unless you add the `:required` flag.
|
||||
|
||||
**Required vs Optional Variables**
|
||||
|
||||
By default, all custom input variables are **optional**, meaning users can leave them blank when filling out the form. This flexible approach allows for versatile prompt templates where some information might not always be needed.
|
||||
|
||||
To make a variable **required** (mandatory), add the `:required` flag:
|
||||
|
||||
```txt
|
||||
{{mandatory_field | text:required}}
|
||||
{{optional_field | text}}
|
||||
```
|
||||
|
||||
When a field is marked as required:
|
||||
|
||||
* The form will display a visual indicator (asterisk) next to the field label
|
||||
* Users cannot submit the form without providing a value
|
||||
* Browser validation will prevent form submission if required fields are empty
|
||||
|
||||
**Input Types Overview**
|
||||
|
||||
You can specify different input types to build rich, user-friendly forms. Here is a table of available types and their properties.
|
||||
|
||||
| Type | Description | Available Properties | Syntax Example |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **text** | A standard single-line text input field, perfect for capturing short pieces of information like names, titles, or single-sentence summaries. This is the **default type if no other is specified**. | `placeholder`, `default`, `required` | `{{name \| text:placeholder="Enter name":required}}` |
|
||||
| **textarea**| A multi-line text area designed for capturing longer blocks of text, such as detailed descriptions, article content, or code snippets. | `placeholder`, `default`, `required` | `{{description \| textarea:required}}` |
|
||||
| **select** | A dropdown menu that presents a predefined list of choices. This is ideal for ensuring consistent input for things like status, priority, or categories. | `options` (JSON array), `placeholder`, `default`, `required` | `{{priority \| select:options=["High","Medium","Low"]:placeholder="Choose priority":required}}` |
|
||||
| **number** | An input field that is restricted to numerical values only. Useful for quantities, ratings, or any other numeric data. | `placeholder`, `min`, `max`, `step`, `default`, `required` | `{{count \| number:min=1:max=100:default=5}}` |
|
||||
| **checkbox**| A simple checkbox that represents a true or false (boolean) value. It's perfect for on/off toggles, like 'Include a conclusion?' or 'Mark as urgent?'. | `label`, `default` (boolean), `required` | `{{include_details \| checkbox:label="Include detailed analysis"}}` |
|
||||
| **date** | A calendar-based date picker that allows users to easily select a specific day, month, and year, ensuring a standardized date format. | `placeholder`, `default` (YYYY-MM-DD), `required` | `{{start_date \| date:required}}` |
|
||||
| **datetime-local**| A specialized picker that allows users to select both a specific date and a specific time. Great for scheduling appointments or logging event timestamps. | `placeholder`, `default`, `required` | `{{appointment \| datetime-local}}` |
|
||||
| **color** | A visual color picker that allows the user to select a color or input a standard hex code (e.g., #FF5733). Useful for design and branding prompts. | `default` (hex code), `required` | `{{brand_color \| color:default="#FFFFFF"}}` |
|
||||
| **email** | An input field specifically formatted and validated for email addresses, ensuring the user provides a correctly structured email. | `placeholder`, `default`, `required` | `{{recipient_email \| email:required}}` |
|
||||
| **month** | A picker that allows users to select a specific month and year, without needing to choose a day. Useful for billing cycles, reports, or timelines. **Note:** This input type is only natively supported in Chrome and Edge. In Firefox and Safari, it will display as a plain text input instead of a month picker. | `placeholder`, `default`, `required` | `{{billing_month \| month}}` |
|
||||
| **range** | A slider control that allows the user to select a numerical value from within a defined minimum and maximum range. Ideal for satisfaction scores or percentage adjustments. | `min`, `max`, `step`, `default`, `required` | `{{satisfaction \| range:min=1:max=10}}` |
|
||||
| **tel** | An input field designed for telephone numbers. It semantically indicates the expected input type for browsers and devices. | `placeholder`, `default`, `required` | `{{phone_number \| tel}}` |
|
||||
| **time** | A picker for selecting a time. Useful for scheduling meetings, logging events, or setting reminders without an associated date. | `placeholder`, `default`, `required` | `{{meeting_time \| time}}` |
|
||||
| **url** | An input field for web addresses (URLs). It helps ensure that the user provides a link, which can be useful for prompts that analyze websites or reference online sources. | `placeholder`, `default`, `required` | `{{website \| url:required}}` |
|
||||
| **map** | **(Experimental)** An interactive map interface that lets users click to select geographic coordinates. This is a powerful tool for location-based prompts. | `default` (e.g., "51.5,-0.09"), `required` | `{{location \| map}}` |
|
||||
|
||||
#### Example Use Cases
|
||||
|
||||
**1. Flexible Article Summarizer**
|
||||
|
||||
Create a reusable prompt where the article content is required but additional parameters are optional.
|
||||
|
||||
* **Command:** `/summarize_article`
|
||||
* **Prompt Content:**
|
||||
|
||||
```txt
|
||||
Please summarize the following article. {{article_text | textarea:placeholder="Paste the full text of the article here...":required}}
|
||||
|
||||
{{summary_length | select:options=["Brief (3 bullets)","Detailed (5 bullets)","Executive Summary"]:default="Brief (3 bullets)"}}
|
||||
|
||||
{{focus_area | text:placeholder="Any specific aspect to focus on? (optional)"}}
|
||||
|
||||
{{include_quotes | checkbox:label="Include key quotes from the article"}}
|
||||
```
|
||||
|
||||
When you type `/summarize_article`, a modal will appear with a required text area for the article, and optional fields for customizing the summary style.
|
||||
|
||||
**2. Advanced Bug Report Generator**
|
||||
|
||||
This prompt ensures critical information is captured while allowing optional details.
|
||||
|
||||
* **Command:** `/bug_report`
|
||||
* **Prompt Content:**
|
||||
|
||||
```txt
|
||||
Generate a bug report with the following details:
|
||||
|
||||
**Summary:** {{summary | text:placeholder="A brief summary of the issue":required}}
|
||||
**Priority:** {{priority | select:options=["Critical","High","Medium","Low"]:default="Medium":required}}
|
||||
**Steps to Reproduce:**
|
||||
{{steps | textarea:placeholder="1. Go to...\n2. Click on...\n3. See error...":required}}
|
||||
|
||||
**Additional Context:** {{additional_context | textarea:placeholder="Browser version, OS, screenshots, etc. (optional)"}}
|
||||
**Workaround:** {{workaround | textarea:placeholder="Any temporary solutions found (optional)"}}
|
||||
|
||||
Please format this into a clear and complete bug report document.
|
||||
```
|
||||
|
||||
This creates a form where title, priority, and steps are mandatory, but additional context and workarounds are optional.
|
||||
|
||||
**3. Social Media Post Generator with Smart Defaults**
|
||||
|
||||
This prompt generates tailored content with required core information and optional customizations.
|
||||
|
||||
* **Command:** `/social_post`
|
||||
* **Prompt Content:**
|
||||
|
||||
```txt
|
||||
Generate a social media post for {{platform | select:options=["LinkedIn","Twitter","Facebook","Instagram"]:required}}.
|
||||
|
||||
**Topic:** {{topic | text:placeholder="e.g., New feature launch":required}}
|
||||
**Key Message:** {{key_message | textarea:placeholder="What are the essential points to communicate?":required}}
|
||||
**Tone of Voice:** {{tone | select:options=["Professional","Casual","Humorous","Inspirational"]:default="Professional"}}
|
||||
**Call to Action:** {{cta | text:placeholder="e.g., 'Learn more', 'Sign up today'"}}
|
||||
**Character Limit:** {{char_limit | number:placeholder="Leave blank for platform default"}}
|
||||
**Include Hashtags:** {{include_hashtags | checkbox:label="Add relevant hashtags":default=true}}
|
||||
|
||||
Please create an engaging post optimized for the selected platform.
|
||||
```
|
||||
|
||||
**4. Meeting Minutes Assistant with Flexible Structure**
|
||||
|
||||
Generate structured meeting minutes with required basics and optional details.
|
||||
|
||||
* **Command:** `/meeting_minutes`
|
||||
* **Prompt Content:**
|
||||
|
||||
```txt
|
||||
# Meeting Minutes
|
||||
|
||||
**Date:** {{meeting_date | date:required}}
|
||||
**Time:** {{meeting_time | time:required}}
|
||||
**Meeting Title:** {{title | text:placeholder="e.g., Weekly Team Sync":required}}
|
||||
**Attendees:** {{attendees | text:placeholder="Comma-separated list of names":required}}
|
||||
|
||||
## Agenda / Key Discussion Points
|
||||
{{agenda_items | textarea:placeholder="Paste the agenda or list the key topics discussed.":required}}
|
||||
|
||||
## Decisions Made
|
||||
{{decisions | textarea:placeholder="Key decisions and outcomes (optional)"}}
|
||||
|
||||
## Action Items
|
||||
{{action_items | textarea:placeholder="List each action item, who it is assigned to, and the deadline."}}
|
||||
|
||||
## Next Meeting
|
||||
**Date:** {{next_meeting | date}}
|
||||
**Topics:** {{next_topics | text:placeholder="Items to discuss next time"}}
|
||||
|
||||
Please format the above information into a clean and professional meeting summary.
|
||||
```
|
||||
|
||||
**5. Content Review Template**
|
||||
|
||||
A flexible template for reviewing various types of content.
|
||||
|
||||
* **Command:** `/content_review`
|
||||
* **Prompt Content:**
|
||||
|
||||
```txt
|
||||
Please review the following {{content_type | select:options=["Blog Post","Marketing Copy","Documentation","Email","Presentation"]:required}}:
|
||||
|
||||
**Content Title:** {{title | text:required}}
|
||||
**Content:** {{content | textarea:placeholder="Paste the content to be reviewed":required}}
|
||||
|
||||
**Review Focus:** {{focus | select:options=["Grammar & Style","Technical Accuracy","Brand Voice","SEO Optimization","General Feedback"]:default="General Feedback"}}
|
||||
**Target Audience:** {{audience | text:placeholder="Who is this content for?"}}
|
||||
**Specific Concerns:** {{concerns | textarea:placeholder="Any particular areas you'd like me to focus on?"}}
|
||||
**Word Count Target:** {{word_count | number:placeholder="Target word count (if relevant)"}}
|
||||
|
||||
Please provide detailed feedback and suggestions for improvement.
|
||||
```
|
||||
|
||||
### Prompt Versioning and History
|
||||
|
||||
Open WebUI includes a robust versioning system for prompts, allowing you to track changes over time and revert to previous versions if needed.
|
||||
|
||||
#### Version Tracking
|
||||
Every time you save changes to a prompt's content, name, command, or access control, a new version is automatically created. This ensures that your prompt's evolution is preserved.
|
||||
|
||||
#### History Sidebar
|
||||
When editing an existing prompt, you will see a **History** sidebar (on desktop) that lists all previous versions in reverse chronological order. Each entry shows:
|
||||
* **Commit Message**: A brief description of the changes (if provided).
|
||||
* **Author**: The user who made the changes, including their profile picture.
|
||||
* **Timestamp**: When the change was made.
|
||||
* **Live Badge**: Indicates which version is currently active in the chat.
|
||||
|
||||
#### Managing Versions
|
||||
* **Previewing**: Click on any version in the history sidebar to preview its content in the main editor.
|
||||
* **Setting as Production**: To make a previous version the active "Live" version, select it and click **Set as Production**.
|
||||
* **Deleting Versions**: You can delete individual history entries by clicking the menu icon next to the version. Note that you cannot delete the currently active production version.
|
||||
* **Copying ID**: Click the prompt ID or a specific version's short ID to copy it to your clipboard for reference.
|
||||
|
||||
### Access Control and Permissions
|
||||
|
||||
Prompt management is controlled by the following permission settings:
|
||||
|
||||
* **Prompts Access**: Users need the `USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS` permission to create and manage prompts.
|
||||
* For detailed information about configuring permissions, refer to the [Permissions documentation](/features/access-security/rbac/permissions).
|
||||
|
||||
### Best Practices
|
||||
|
||||
* Use clear, descriptive titles for your prompts
|
||||
* Create intuitive slash commands that reflect the prompt's purpose
|
||||
* **Design with flexibility in mind**: Mark only truly essential fields as required, leaving optional fields for enhanced customization
|
||||
* For custom variables, use clear names (e.g., `{{your_name}}` instead of `{{var1}}`) and descriptive `placeholder` text to make templates easy to understand
|
||||
* **Provide sensible defaults** for optional fields where appropriate to speed up form completion
|
||||
* **Use the required flag strategically** - only require information that is absolutely necessary for the prompt to function properly
|
||||
* Document any specific requirements or expected inputs in the prompt description
|
||||
* Test prompts with different variable combinations, including scenarios where optional fields are left blank
|
||||
* Consider access levels carefully when sharing prompts with other users - public sharing means that it will appear automatically for all users when they hit `/` in a chat, so you want to avoid creating too many
|
||||
* **Use the enable/disable toggle** to temporarily deactivate prompts you're not currently using instead of deleting them — this preserves the prompt's configuration and version history
|
||||
* **Consider user workflows**: Think about which information users will always have versus what they might want to customize occasionally
|
||||
|
||||
### Migration Notes
|
||||
|
||||
* **Prompt History Migration**: Existing prompts created before the versioning update have been automatically migrated to the new system. Their current content has been preserved as the initial "Live" version in their history.
|
||||
* **ID-based URLs**: The URL structure for editing prompts has changed from using commands to using unique IDs. Existing bookmarks to prompt edit pages may need to be updated.
|
||||
* **Variable Requirement**: As of the v0.5.0 update, all variables are now treated as optional by default. To maintain required behavior for critical fields, edit your prompts to add the `:required` flag to those variables.
|
||||
@@ -1,146 +0,0 @@
|
||||
---
|
||||
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/extensibility/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 behave differently depending on how they are activated:
|
||||
|
||||
### User-Selected Skills ($ Mention)
|
||||
|
||||
When you mention a skill in chat with `$`, its **full content is injected directly** into the system prompt. The model has immediate access to the complete instructions without needing any extra tool calls.
|
||||
|
||||
### Model-Attached Skills
|
||||
|
||||
Skills bound to a model use a **lazy-loading** architecture to keep the context window efficient:
|
||||
|
||||
1. **Manifest injection** — 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 many skills are attached to a model, 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. For model-attached skills, the model uses this to decide whether to load the full instructions. |
|
||||
| **Content** | The full skill instructions in **Markdown**. For user-selected skills this is injected directly; for model-attached skills it is loaded on-demand via `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's **full content** is injected directly into the conversation, giving the model immediate access to the complete instructions.
|
||||
|
||||
### 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 (name and description) are automatically injected, and the model can load the full content on-demand via `view_skill`.
|
||||
|
||||
## 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-conversations/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/extensibility/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 → Integrations**) — 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/ai-knowledge/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/access-security/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.
|
||||
|
||||
:::caution Attached Skills Still Require User Access
|
||||
Attaching a skill to a model does **not** bypass access control. When a user chats with the model, Open WebUI checks whether **that specific user** has read access to each attached skill. Skills the user cannot access are silently excluded — the model won't receive the skill manifest and cannot call `view_skill` for it.
|
||||
|
||||
**Example scenario**: An admin creates a private skill and attaches it to a model shared with all users. Regular users chatting with this model will **not** have the skill available because they don't have read access to the skill itself.
|
||||
|
||||
**Solution**: Make sure users who need access to the model's skills also have read access to each skill (via access grants, group permissions, or by making the skill public). The "Workspace → Skills Access" permission controls whether users can *create and manage* skills — it does **not** affect whether model-attached skills work for them.
|
||||
:::
|
||||
|
||||
### 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/access-security/rbac/permissions) for details on how to configure these.
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"label": "🔐 Authentication & Access",
|
||||
"position": 9,
|
||||
"collapsible": true,
|
||||
"collapsed": true
|
||||
}
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
sidebar_position: 500
|
||||
title: "API Keys"
|
||||
---
|
||||
|
||||
# 🔑 API Keys
|
||||
|
||||
**Programmatic access to Open WebUI, for scripts, bots, and integrations.**
|
||||
|
||||
API keys are personal access tokens that let external code call the same endpoints the web UI uses. Anything you can do in a browser - chat completions, model listing, file uploads, RAG queries - your scripts can do with a single `Authorization: Bearer` header. Each key inherits the permissions of the user who created it, so there's no separate permission model to learn.
|
||||
|
||||
---
|
||||
|
||||
## Why API Keys?
|
||||
|
||||
### Automation without a browser
|
||||
|
||||
Scripts, CI/CD pipelines, monitoring bots, and third-party tools all need programmatic access. API keys give them a stable credential that doesn't expire with a browser session.
|
||||
|
||||
### Same permissions, different interface
|
||||
|
||||
An API key acts as you. It inherits your role and group permissions - the same access controls that govern the web UI apply to every API request.
|
||||
|
||||
### Revocable and auditable
|
||||
|
||||
Name each key descriptively (e.g., "CI Pipeline", "Monitoring Bot") to track usage. Delete a key instantly if it's compromised - no password reset, no session invalidation, just a single click.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🔐 **Bearer token auth** | Standard `Authorization: Bearer` header, works with any HTTP client or SDK |
|
||||
| 🛡️ **Scoped to user** | Key inherits the creating user's role and group permissions |
|
||||
| 🚫 **Endpoint restrictions** | Optionally limit which API routes a key can access |
|
||||
| 👥 **Permission-gated** | Requires a global admin toggle plus per-group feature permission for non-admins |
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Step 1: Enable API Keys Globally (Admin)
|
||||
|
||||
1. Log in as an **administrator**
|
||||
2. Open **Admin Panel > Settings > General**
|
||||
3. Scroll to the **Authentication** section
|
||||
4. Toggle **Enable API Keys** on
|
||||
5. Click **Save**
|
||||
|
||||
:::info
|
||||
This is the global master switch. When it's off, no one - not even admins - can generate keys. When it's on:
|
||||
- **Admin** users can generate keys immediately
|
||||
- **Non-admin** users still need the API Keys feature permission (Step 2)
|
||||
:::
|
||||
|
||||
*(Optional)* Enable **API Key Endpoint Restrictions** to limit which routes API keys can call. Specify allowed endpoints as a comma-separated list (e.g., `/api/v1/models,/api/v1/chat/completions`).
|
||||
|
||||
### Step 2: Grant Permission to Non-admin Users (Admin)
|
||||
|
||||
Non-admin users need the **API Keys** feature permission. Grant it using either method:
|
||||
|
||||
#### Option A: Default Permissions (all users)
|
||||
|
||||
1. **Admin Panel > Users > Groups > Default Permissions**
|
||||
2. Under **Features Permissions**, toggle **API Keys** on
|
||||
3. Click **Save**
|
||||
|
||||
:::warning
|
||||
This grants every user with the "user" role the ability to generate API keys. For tighter control, use Option B.
|
||||
:::
|
||||
|
||||
#### Option B: User Groups (specific users)
|
||||
|
||||
1. **Admin Panel > Users > Groups**
|
||||
2. Select or create a group (e.g., "API Users")
|
||||
3. Under **Permissions > Features Permissions**, toggle **API Keys** on
|
||||
4. Click **Save**
|
||||
|
||||
:::tip
|
||||
Create a dedicated "API Users" or "Monitoring" group and add only the accounts that need programmatic access. This follows the principle of least privilege.
|
||||
:::
|
||||
|
||||
### Step 3: Generate a Key
|
||||
|
||||
1. Click your **profile icon** (bottom-left sidebar)
|
||||
2. Select **Settings > Account**
|
||||
3. In the **API Keys** section, click **Generate New API Key**
|
||||
4. Give it a descriptive name (e.g., "Monitoring Bot")
|
||||
5. **Copy the key immediately** - you won't be able to view it again
|
||||
|
||||
:::warning
|
||||
Treat API keys like passwords. Store them in a secrets manager, never commit them to version control, and never share them in public channels. If a key is compromised, delete it immediately and generate a new one.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Using Your API Key
|
||||
|
||||
Pass the key as a Bearer token in the `Authorization` header:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
http://localhost:8080/api/models
|
||||
```
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.get(
|
||||
"http://localhost:8080/api/models",
|
||||
headers={"Authorization": "Bearer YOUR_API_KEY"}
|
||||
)
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
For the full endpoint reference - chat completions, Ollama proxy, RAG, file management, and more - see [API Endpoints](/reference/api-endpoints).
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Dedicated service accounts
|
||||
|
||||
Create a **non-admin user** specifically for automation (e.g., `monitoring-bot`, `ci-pipeline`). Generate keys from that account. If a key leaks, the attacker only gets that user's permissions - not admin access.
|
||||
|
||||
### Endpoint restrictions
|
||||
|
||||
Enable **API Key Endpoint Restrictions** and whitelist only the routes your integration actually needs. A monitoring bot only needs `/api/models` and `/api/chat/completions` - don't give it access to `/api/v1/files/` or admin endpoints.
|
||||
|
||||
### Key rotation
|
||||
|
||||
Periodically delete old keys and generate new ones, especially for long-lived integrations. Name keys with a date or version to track rotation (`"Monitoring Bot - 2025-Q1"`).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Can't see the API Keys section in Settings > Account?**
|
||||
|
||||
- **Check the global toggle:** Verify that an admin has enabled API keys in **Admin Panel > Settings > General > Enable API Keys**. See [`ENABLE_API_KEYS`](/reference/env-configuration#enable_api_keys).
|
||||
- **Check your permissions (non-admin users):** Verify that your account or group has the **API Keys** feature permission under **Features Permissions**. See [`USER_PERMISSIONS_FEATURES_API_KEYS`](/reference/env-configuration#user_permissions_features_api_keys).
|
||||
|
||||
**Getting `401 Unauthorized` responses?**
|
||||
|
||||
- Verify the key is formatted correctly: `Authorization: Bearer sk-...`
|
||||
- Check that the key hasn't been deleted
|
||||
- If endpoint restrictions are enabled, confirm the route you're calling is in the allowlist
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
### No post-creation viewing
|
||||
|
||||
API keys cannot be viewed after creation. If you lose a key, delete it and generate a new one.
|
||||
|
||||
### No per-key permissions
|
||||
|
||||
Keys inherit the full permissions of the user who created them. You cannot restrict a key to a subset of its owner's permissions (beyond endpoint restrictions).
|
||||
|
||||
### No automatic expiration
|
||||
|
||||
API keys do not expire automatically. You must manually delete and rotate them.
|
||||
+1
-1
@@ -223,4 +223,4 @@ SCIM works best when combined with SSO (Single Sign-On). A typical setup include
|
||||
|
||||
This ensures users are automatically created and can immediately authenticate using their corporate credentials.
|
||||
|
||||
For SSO configuration, see the [SSO documentation](https://docs.openwebui.com/features/access-security/auth/sso/).
|
||||
For SSO configuration, see the [SSO documentation](https://docs.openwebui.com/features/authentication-access/auth/sso/).
|
||||
+6
-2
@@ -21,7 +21,7 @@ Check out our [troubleshooting guide](https://docs.openwebui.com/troubleshooting
|
||||
Right now, you can only configure **one** OpenID Connect (OIDC) provider at a time via `OPENID_PROVIDER_URL`.
|
||||
You cannot have Microsoft **and** Google as OIDC providers simultaneously.
|
||||
|
||||
*However, there is a community workaround for using both! See our [Dual OAuth Tutorial](/tutorials/integrations/auth-identity/dual-oauth-configuration) for more details.*
|
||||
*However, there is a community workaround for using both! See our [Dual OAuth Tutorial](/tutorials/auth-sso/dual-oauth-configuration) for more details.*
|
||||
:::
|
||||
|
||||
## OAuth Configuration Overview
|
||||
@@ -208,7 +208,7 @@ The following environment variables are used:
|
||||
:::
|
||||
|
||||
:::tip Community Workaround: Multi-Provider OAuth
|
||||
If you need to support both Microsoft and Google simultaneously, check out our **[Dual OAuth Configuration Tutorial](/tutorials/integrations/auth-identity/dual-oauth-configuration)**.
|
||||
If you need to support both Microsoft and Google simultaneously, check out our **[Dual OAuth Configuration Tutorial](/tutorials/auth-sso/dual-oauth-configuration)**.
|
||||
:::
|
||||
### OAuth Role Management
|
||||
|
||||
@@ -314,6 +314,10 @@ When configured, this header allows clients to set admin-level access via an HTT
|
||||
|
||||
### Tailscale Serve
|
||||
|
||||
:::tip
|
||||
For a complete end-to-end guide covering installation, HTTPS, authentication, and Docker Compose setup, see the [**Tailscale Integration Tutorial**](/tutorials/auth-sso/tailscale).
|
||||
:::
|
||||
|
||||
[Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve) allows you to share a service within your tailnet, and Tailscale will set the header `Tailscale-User-Login` with the email address of the requester.
|
||||
|
||||
Below is an example serve config with a corresponding Docker Compose file that starts a Tailscale sidecar, exposing Open WebUI to the tailnet with the tag `open-webui` and hostname `open-webui`, and can be reachable at `https://open-webui.TAILNET_NAME.ts.net`.
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
sidebar_position: 0
|
||||
title: "Authentication & Access"
|
||||
---
|
||||
|
||||
# 🔐 Authentication & Access
|
||||
|
||||
**Control who gets in, what they can do, and how your instance integrates with your identity stack.**
|
||||
|
||||
Open WebUI is multi-user from day one. Whether you're running a personal instance or managing thousands of seats across an organization, you have full control over authentication, authorization, and programmatic access. Connect your identity provider, define granular permissions, and automate user lifecycle management, all without touching a line of code.
|
||||
|
||||
---
|
||||
|
||||
## What's In This Section
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 👥 **[RBAC](./rbac)** | Roles, groups, and per-resource permissions. Define who can access what |
|
||||
| 🔑 **[SSO / OIDC](./auth/sso)** | Federated authentication with Google, Microsoft, Okta, Keycloak, or any OIDC provider |
|
||||
| 📂 **[LDAP](./auth/ldap)** | Authenticate against your existing directory service |
|
||||
| 📋 **[SCIM 2.0](./auth/scim)** | Automated user and group provisioning and deprovisioning from your IdP |
|
||||
| 🔐 **[API Keys](./api-keys)** | Programmatic access for scripts, bots, pipelines, and integrations |
|
||||
|
||||
---
|
||||
|
||||
## How It Fits Together
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
IdP["Identity Provider<br/>(Google, Okta, LDAP...)"] -->|SSO / OIDC / LDAP| Auth["Authentication"]
|
||||
IdP -->|SCIM 2.0| Provision["User & Group<br/>Provisioning"]
|
||||
Auth --> RBAC["RBAC Engine"]
|
||||
Provision --> RBAC
|
||||
RBAC -->|Roles + Groups| Permissions["Per-User<br/>Permissions"]
|
||||
Permissions --> Resources["Models · Knowledge<br/>Tools · Channels"]
|
||||
APIKeys["API Keys"] -->|Bearer Token| RBAC
|
||||
```
|
||||
|
||||
1. **Users authenticate** via SSO, OIDC, LDAP, or local credentials.
|
||||
2. **SCIM provisions** users and groups automatically from your identity provider.
|
||||
3. **RBAC determines access** based on roles (Admin, User) and group memberships.
|
||||
4. **Permissions are additive**: each group membership adds capabilities, never removes them.
|
||||
5. **API keys** inherit the creating user's full permissions for programmatic access.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Solo or small team? Start simple
|
||||
|
||||
Open WebUI works out of the box with local email/password authentication. No external identity provider required. Create accounts, assign admin or user roles, and you're done.
|
||||
|
||||
### Organization? Layer in SSO and SCIM
|
||||
|
||||
1. **[Set up SSO](./auth/sso)**: Configure your identity provider for single sign-on
|
||||
2. **[Configure RBAC](./rbac)**: Create groups, assign permissions, and set up access control lists
|
||||
3. **[Enable SCIM](./auth/scim)** *(optional)*: Automate user lifecycle from your IdP
|
||||
4. **[Generate API keys](./api-keys)** *(optional)*: Enable programmatic access for automation
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Additive permissions
|
||||
|
||||
Open WebUI's security model is **additive**. Users start with their role's default permissions, and group memberships only ever *add* capabilities. A user's effective permissions are the union of everything granted by their role and all their groups.
|
||||
|
||||
### Per-resource access control
|
||||
|
||||
Models, Knowledge bases, Tools, and Skills all support fine-grained access control. Resources are **private by default**. The creator controls who can see and use them via user grants, group grants, or public visibility.
|
||||
|
||||
### Admin vs. User
|
||||
|
||||
There are two primary roles. **Admins** have full system access. **Users** have capabilities defined by default permissions plus group memberships. A third role, **Pending**, holds new sign-ups in a queue for admin approval.
|
||||
|
||||
[**Roles →**](./rbac/roles) · [**Permissions →**](./rbac/permissions) · [**Groups →**](./rbac/groups)
|
||||
+1
-1
@@ -70,7 +70,7 @@ You can restrict access to specific objects (like a proprietary Model or sensiti
|
||||
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/ai-knowledge/knowledge#knowledge-scoping-with-native-function-calling) for details.
|
||||
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#scoped-access-keeps-things-organized) for details.
|
||||
:::
|
||||
|
||||
### Access Grant System
|
||||
+1
-1
@@ -55,7 +55,7 @@ Some permissions are **dependent** on others (e.g., you cannot import models if
|
||||
| **Tools Export** | *(Requires Tools Access)* Ability to export tools. |
|
||||
|
||||
:::danger ⚠️ Tools Access = Root-Equivalent Access
|
||||
**Treat the Tools Access permission as root-equivalent access.** Granting a user access to create or import Tools is equivalent to giving them shell access to your server, because Tools and Functions execute arbitrary Python code. Only grant this permission to users you would trust with direct access to your server. If you enable this permission for untrusted users, you are accepting the risk of arbitrary code execution on your host. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/#-critical-security-warning).
|
||||
**Treat the Tools Access permission as root-equivalent access.** Granting a user access to create or import Tools is equivalent to giving them shell access to your server, because Tools and Functions execute arbitrary Python code. Only grant this permission to users you would trust with direct access to your server. If you enable this permission for untrusted users, you are accepting the risk of arbitrary code execution on your host. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/).
|
||||
:::
|
||||
|
||||
| **Skills Access** | Access the **Skills** workspace to create and manage reusable instruction sets. |
|
||||
+2
-1
@@ -2,6 +2,7 @@
|
||||
"label": "Speech-to-Text & Text-to-Speech",
|
||||
"position": 500,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
"type": "generated-index",
|
||||
"slug": "/features/chat-conversations/audio"
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -8,7 +8,7 @@ title: "OpenAI STT Integration"
|
||||
This guide covers how to use OpenAI's Whisper API for Speech-to-Text with Open WebUI. This provides cloud-based transcription without needing local GPU resources.
|
||||
|
||||
:::tip Looking for TTS?
|
||||
See the companion guide: [Using OpenAI for Text-to-Speech](/features/media-generation/audio/text-to-speech/openai-tts-integration)
|
||||
See the companion guide: [Using OpenAI for Text-to-Speech](/features/chat-conversations/audio/text-to-speech/openai-tts-integration)
|
||||
:::
|
||||
|
||||
## Requirements
|
||||
+3
-3
@@ -15,9 +15,9 @@ The following speech-to-text providers are supported:
|
||||
|
||||
| Service | API Key Required | Guide |
|
||||
|---------|------------------|-------|
|
||||
| Local Whisper (default) | ❌ | Built-in, see [Environment Variables](/features/media-generation/audio/speech-to-text/env-variables) |
|
||||
| OpenAI (Whisper API) | ✅ | [OpenAI STT Guide](/features/media-generation/audio/speech-to-text/openai-stt-integration) |
|
||||
| Mistral (Voxtral) | ✅ | [Mistral Voxtral Guide](/features/media-generation/audio/speech-to-text/mistral-voxtral-integration) |
|
||||
| Local Whisper (default) | ❌ | Built-in, see [Environment Variables](/features/chat-conversations/audio/speech-to-text/env-variables) |
|
||||
| OpenAI (Whisper API) | ✅ | [OpenAI STT Guide](/features/chat-conversations/audio/speech-to-text/openai-stt-integration) |
|
||||
| Mistral (Voxtral) | ✅ | [Mistral Voxtral Guide](/features/chat-conversations/audio/speech-to-text/mistral-voxtral-integration) |
|
||||
| Deepgram | ✅ | — |
|
||||
| Azure | ✅ | — |
|
||||
|
||||
+1
-1
@@ -244,7 +244,7 @@ Chatterbox has higher memory requirements than other TTS solutions:
|
||||
- **Recommended:** 8GB+ RAM
|
||||
- **GPU:** NVIDIA CUDA or Apple M-series (MPS) recommended
|
||||
|
||||
If you experience memory issues, consider using a lighter alternative like [OpenAI Edge TTS](/features/media-generation/audio/text-to-speech/openai-edge-tts-integration) or [Kokoro-FastAPI](/features/media-generation/audio/text-to-speech/Kokoro-FastAPI-integration).
|
||||
If you experience memory issues, consider using a lighter alternative like [OpenAI Edge TTS](/features/chat-conversations/audio/text-to-speech/openai-edge-tts-integration) or [Kokoro-FastAPI](/features/chat-conversations/audio/text-to-speech/Kokoro-FastAPI-integration).
|
||||
|
||||
### Docker Networking
|
||||
|
||||
+1
-1
@@ -8,7 +8,7 @@ title: "Mistral TTS Integration"
|
||||
This guide covers how to use Mistral's Text-to-Speech API with Open WebUI.
|
||||
|
||||
:::tip Looking for STT?
|
||||
See the companion guide: [Using Mistral Voxtral for Speech-to-Text](/features/media-generation/audio/speech-to-text/mistral-voxtral-integration)
|
||||
See the companion guide: [Using Mistral Voxtral for Speech-to-Text](/features/chat-conversations/audio/speech-to-text/mistral-voxtral-integration)
|
||||
:::
|
||||
|
||||
## Requirements
|
||||
+2
-2
@@ -8,7 +8,7 @@ title: "OpenAI TTS Integration"
|
||||
This guide covers how to use OpenAI's official Text-to-Speech API with Open WebUI. This is the simplest setup if you already have an OpenAI API key.
|
||||
|
||||
:::tip Looking for STT?
|
||||
See the companion guide: [Using OpenAI for Speech-to-Text](/features/media-generation/audio/speech-to-text/openai-stt-integration)
|
||||
See the companion guide: [Using OpenAI for Speech-to-Text](/features/chat-conversations/audio/speech-to-text/openai-stt-integration)
|
||||
:::
|
||||
|
||||
## Requirements
|
||||
@@ -158,5 +158,5 @@ For more troubleshooting, see the [Audio Troubleshooting Guide](/troubleshooting
|
||||
OpenAI charges per character for TTS. See [OpenAI Pricing](https://platform.openai.com/docs/pricing) for current rates. Note that `tts-1-hd` costs more than `tts-1`.
|
||||
|
||||
:::info
|
||||
For a free alternative, consider [OpenAI Edge TTS](/features/media-generation/audio/text-to-speech/openai-edge-tts-integration) which uses Microsoft's free Edge browser TTS.
|
||||
For a free alternative, consider [OpenAI Edge TTS](/features/chat-conversations/audio/text-to-speech/openai-edge-tts-integration) which uses Microsoft's free Edge browser TTS.
|
||||
:::
|
||||
@@ -31,6 +31,6 @@ Open WebUI provides a comprehensive set of chat features designed to enhance you
|
||||
|
||||
- **[✅ Task Management](./task-management.mdx)**: Let agentic models keep a structured task/todo list in chat for multi-step workflows and transparent progress tracking.
|
||||
|
||||
- **Skill Mentions**: Use `$` in the chat input to mention and activate [Skills](/features/ai-knowledge/skills) on-the-fly, injecting their manifests into the conversation.
|
||||
- **Skill Mentions**: Use `$` in the chat input to mention and activate [Skills](/features/workspace/skills) on-the-fly, injecting their manifests into the conversation.
|
||||
|
||||
- **Writing & Content Blocks**: Responses from models that include colon-fence blocks (e.g., `:::writing`, `:::code_execution`, `:::search_results`) are automatically rendered as formatted content in a styled container with a copy button. This is commonly used by newer OpenAI models to distinguish different types of output (prose, code results, search results) from the main response text.
|
||||
|
||||
@@ -14,7 +14,7 @@ By default, Open WebUI injects temporal variables into the model's environment v
|
||||
- **`CURRENT_TIME`**: Injected as HH:MM.
|
||||
- **`CURRENT_WEEKDAY`**: (e.g., Monday, Tuesday).
|
||||
|
||||
These variables can be manually used in [**Prompts**](/features/ai-knowledge/prompts) or [**Model Files**](/features/ai-knowledge/models) using the `{{CURRENT_DATE}}` syntax.
|
||||
These variables can be manually used in [**Prompts**](/features/workspace/prompts) or [**Model Files**](/features/workspace/models) using the `{{CURRENT_DATE}}` syntax.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ The following table lists the available URL parameters, their function, and exam
|
||||
|
||||
### 1. **Models and Model Selection**
|
||||
|
||||
- **Description**: The `models` and `model` parameters allow you to specify which [language models](/features/ai-knowledge/models) should be used for a particular chat session.
|
||||
- **Description**: The `models` and `model` parameters allow you to specify which [language models](/features/workspace/models) should be used for a particular chat session.
|
||||
- **How to Set**: You can use either `models` for multiple models or `model` for a single model.
|
||||
- **Example**:
|
||||
- `/?models=model1,model2` – This initializes the chat with `model1` and `model2`.
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Create & Edit Images",
|
||||
"position": 400,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/features/chat-conversations/image-generation-and-editing"
|
||||
}
|
||||
}
|
||||
@@ -212,7 +212,7 @@ When File Context is disabled, file content is **not automatically extracted or
|
||||
:::
|
||||
|
||||
:::tip Per-File Retrieval Mode
|
||||
Individual files and knowledge bases can also be set to bypass RAG entirely using the **"Using Entire Document"** toggle. This injects the full file content into every message regardless of native function calling settings. See [Full Context vs Focused Retrieval](/features/ai-knowledge/knowledge#full-context-vs-focused-retrieval) for details.
|
||||
Individual files and knowledge bases can also be set to bypass RAG entirely using the **"Using Entire Document"** toggle. This injects the full file content into every message regardless of native function calling settings. See [Full Context vs Focused Retrieval](/features/workspace/knowledge#retrieval-modes) for details.
|
||||
:::
|
||||
|
||||
:::info
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
sidebar_position: 0
|
||||
title: "Extensibility"
|
||||
---
|
||||
|
||||
# 🔌 Extensibility
|
||||
|
||||
**Make Open WebUI do anything with Python, HTTP, or community plugins you install in one click.**
|
||||
|
||||
Open WebUI ships with powerful defaults, but your workflows aren't default. Extensibility is how you close the gap: give models real-time data, enforce compliance rules, add new AI providers, or connect to any external service. Write a few lines of Python, point at an OpenAPI endpoint, or browse the community library. The platform adapts to you, not the other way around.
|
||||
|
||||
There are three layers, and most teams end up using at least two:
|
||||
|
||||
- **In-process Python** (Tools & Functions) runs inside Open WebUI itself with zero infrastructure and instant iteration.
|
||||
- **External HTTP** (OpenAPI & MCP servers) connects to services running anywhere, from a sidecar container to a third-party SaaS.
|
||||
- **Pipeline workers** (Pipelines) offload heavy or sensitive processing to a separate container, keeping your main instance fast and clean.
|
||||
|
||||
---
|
||||
|
||||
## Why Extensibility?
|
||||
|
||||
### Give models real-world abilities
|
||||
|
||||
Out of the box, an LLM can only work with what's in its training data and your conversation. Tools let it reach out: check the weather, query a database, call an API, run a calculation. The model decides when to use a tool based on the conversation. You just make the capability available.
|
||||
|
||||
### Connect any external service
|
||||
|
||||
Have an internal API? A third-party SaaS with an OpenAPI spec? An MCP server already running in your stack? Open WebUI discovers endpoints automatically and exposes them as tools the model can call. No glue code, no wrappers.
|
||||
|
||||
### Control every message
|
||||
|
||||
Functions let you intercept and transform messages before they reach the model (input filters) or before they reach the user (output filters). Redact PII, enforce formatting rules, log to an observability platform, inject system instructions dynamically, all without touching model configuration.
|
||||
|
||||
### Offload heavy processing
|
||||
|
||||
When a plugin needs GPU access, large dependencies, or isolated execution, run it as a Pipeline on a separate machine. Open WebUI talks to it over a standard API. Your main instance stays lean.
|
||||
|
||||
### Import from the community
|
||||
|
||||
Browse hundreds of community-built Tools and Functions from the Open WebUI Community site. Find what you need, click **Import**, and it's live. No `pip install`, no restart.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🐍 **Tools** | Python scripts that give models new abilities: web search, API calls, code execution |
|
||||
| ⚙️ **Functions** | Platform extensions that add model providers (Pipes), message processing (Filters), or UI actions (Actions) |
|
||||
| 🔗 **MCP support** | Native Streamable HTTP for Model Context Protocol servers |
|
||||
| 🌐 **OpenAPI servers** | Auto-discover and expose tools from any OpenAPI-compatible endpoint |
|
||||
| 🔧 **Pipelines** | Modular plugin framework running on a separate worker for heavy or sensitive processing |
|
||||
| 📝 **Skills** | Markdown instruction sets that teach models how to approach specific tasks |
|
||||
| ⚡ **Prompts** | Slash-command templates with typed input variables and versioning |
|
||||
| 🏪 **Community library** | One-click import of community-built Tools and Functions |
|
||||
|
||||
---
|
||||
|
||||
## Architecture at a Glance
|
||||
|
||||
Understanding which layer to use saves time:
|
||||
|
||||
| Layer | Runs where | Best for | Trade-off |
|
||||
|-------|-----------|----------|-----------|
|
||||
| **Tools & Functions** | Inside Open WebUI process | Real-time data, filters, UI actions, new providers | Shares resources with the main server |
|
||||
| **OpenAPI / MCP** | Any HTTP endpoint | Connecting existing services, third-party APIs | Requires a running external server |
|
||||
| **Pipelines** | Separate Docker container | GPU workloads, heavy dependencies, sandboxed execution | Additional infrastructure to manage |
|
||||
|
||||
Most users start with **Tools & Functions**. They require no extra setup, have a built-in code editor, and cover the majority of use cases.
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Real-time data enrichment
|
||||
|
||||
A sales team builds a Tool that queries their CRM API. When a rep asks *"What's the latest on the Acme deal?"*, the model calls the tool, retrieves the pipeline stage, last activity, and deal value, and synthesizes a briefing with live data, not stale training knowledge.
|
||||
|
||||
### Enterprise compliance filters
|
||||
|
||||
A healthcare organization deploys a Filter Function that scans every outbound message for PHI patterns (SSN, MRN, dates of birth). Matches are redacted before the response reaches the user, and the original is logged to their SIEM. No model configuration changes required. The filter runs transparently on every conversation.
|
||||
|
||||
### Multi-provider model routing
|
||||
|
||||
An engineering team uses Pipe Functions to add Anthropic, Google Vertex AI, and a self-hosted vLLM instance alongside their existing Ollama models. Users see all providers in a single model selector with no separate logins and no API key juggling.
|
||||
|
||||
### Heavy-compute pipelines
|
||||
|
||||
A research group runs a Retrieval-Augmented Generation pipeline that re-ranks with a cross-encoder model requiring GPU. They deploy it as a Pipeline on a dedicated GPU node. Open WebUI routes relevant queries to the pipeline automatically while keeping the main instance on commodity hardware.
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
### Security
|
||||
|
||||
Tools, Functions, and Pipelines execute **arbitrary Python code** on your server. Only install extensions from trusted sources, review code before importing, and restrict Workspace access to administrators. See the [Security Policy](/security) for details.
|
||||
|
||||
### Resource sharing
|
||||
|
||||
In-process Tools and Functions share CPU and memory with Open WebUI. Computationally expensive plugins should be moved to Pipelines or external services.
|
||||
|
||||
### MCP transport
|
||||
|
||||
Native MCP support is **Streamable HTTP only**. For stdio or SSE-based MCP servers, use [mcpo](https://github.com/open-webui/mcpo) as a translation proxy.
|
||||
|
||||
---
|
||||
|
||||
## Dive Deeper
|
||||
|
||||
| Topic | What you'll learn |
|
||||
|-------|-------------------|
|
||||
| [**Tools & Functions**](plugin) | Writing Python Tools, Functions (Pipes, Filters, Actions), and the development API |
|
||||
| [**MCP**](mcp) | Connecting Model Context Protocol servers, OAuth setup, troubleshooting |
|
||||
| [**Pipelines**](pipelines) | Deploying the pipeline worker, building custom pipelines, directory structure |
|
||||
@@ -127,7 +127,7 @@ The chat shows "Failed to connect to MCP server" when using a tool, even if the
|
||||
**Solutions**:
|
||||
1. **Check Authentication**: Ensure you haven't selected `Bearer` without a key. Switch to `None` if no token is needed.
|
||||
2. **Filter List Bug**: If the "Function Name Filter List" is empty, try adding a comma (`,`) to it.
|
||||
3. **OAuth 2.1 Default Tool**: If the failing tool uses OAuth 2.1 and is set as a default tool on the model, this is a [known limitation](#oauth-21-tools-cannot-be-set-as-default-tools). Remove it from the model's default tools and have users enable it manually per-chat.
|
||||
3. **OAuth 2.1 Default Tool**: If the failing tool uses OAuth 2.1 and is set as a default tool on the model, this is a known limitation. Remove it from the model's default tools and have users enable it manually per-chat.
|
||||
|
||||
### Infinite loading screen after adding External Tool
|
||||
|
||||
|
||||
@@ -175,7 +175,7 @@ When `allowSameOrigin` is **off** (default), the Rich UI iframe is heavily sandb
|
||||
|
||||
If your Rich UI embed needs to trigger downloads, interact with Open WebUI's frontend, or execute JavaScript that impacts the parent page, **enabling same-origin iframe access is required**. Enable it in **Settings → Interface → Iframe Same-Origin Access**.
|
||||
|
||||
As an alternative for ephemeral interactions that need full page access, consider using the [`execute` event](/features/extensibility/plugin/development/events#execute-requires-__event_call__) instead, which runs unsandboxed in the main page context.
|
||||
As an alternative for ephemeral interactions that need full page access, consider using the [`execute` event](/features/extensibility/plugin/development/events#execute-works-with-both-__event_call__-and-__event_emitter__) instead, which runs unsandboxed in the main page context.
|
||||
:::
|
||||
|
||||
## Rendering Position
|
||||
@@ -290,7 +290,7 @@ This means your Rich UI embed can include interactive buttons (e.g., "Explain th
|
||||
|
||||
## Rich UI Embeds vs Execute Event
|
||||
|
||||
Rich UI embeds and the [`execute` event](/features/extensibility/plugin/development/events#execute-requires-__event_call__) are complementary ways to create interactive experiences. Choose based on your needs:
|
||||
Rich UI embeds and the [`execute` event](/features/extensibility/plugin/development/events#execute-works-with-both-__event_call__-and-__event_emitter__) are complementary ways to create interactive experiences. Choose based on your needs:
|
||||
|
||||
| | Rich UI Embed | `execute` Event |
|
||||
|---|---|---|
|
||||
|
||||
@@ -6,7 +6,7 @@ title: "Action Function"
|
||||
Action functions allow you to write custom buttons that appear in the message toolbar for end users to interact with. This feature enables more interactive messaging, allowing users to grant permission before a task is performed, generate visualizations of structured data, download an audio snippet of chats, and many other use cases.
|
||||
|
||||
:::danger ⚠️ Critical Security Warning
|
||||
**Action Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/#-critical-security-warning).
|
||||
**Action Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/).
|
||||
:::
|
||||
|
||||
:::warning Use Async Functions for Future Compatibility
|
||||
|
||||
@@ -4,7 +4,7 @@ title: "Filter Function"
|
||||
---
|
||||
|
||||
:::danger ⚠️ Critical Security Warning
|
||||
**Filter Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/#-critical-security-warning).
|
||||
**Filter Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/).
|
||||
:::
|
||||
|
||||
# 🪄 Filter Function: Modify Inputs and Outputs
|
||||
|
||||
@@ -12,7 +12,7 @@ Unlike external tools that may require complex integrations, **Functions are bui
|
||||
Think of Functions as **modular building blocks** that let you enhance how the WebUI works, tailored exactly to what you need. They’re lightweight, highly customizable, and written in **pure Python**, so you have the freedom to create anything—from new AI-powered workflows to integrations with anything you use, like Google Search or Home Assistant.
|
||||
|
||||
:::danger ⚠️ Critical Security Warning
|
||||
**Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/#-critical-security-warning).
|
||||
**Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/).
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
@@ -4,7 +4,7 @@ title: "Pipe Function"
|
||||
---
|
||||
|
||||
:::danger ⚠️ Critical Security Warning
|
||||
**Pipe Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/#-critical-security-warning).
|
||||
**Pipe Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/).
|
||||
:::
|
||||
|
||||
# 🚰 Pipe Function: Create Custom "Agents/Models"
|
||||
|
||||
@@ -4,7 +4,7 @@ title: "Development"
|
||||
---
|
||||
|
||||
:::danger ⚠️ Critical Security Warning
|
||||
**Workspace Tools execute arbitrary Python code on your server.** Only install from trusted sources, review code before importing, and restrict Workspace access to trusted administrators only. Granting a user the ability to create or import Tools is equivalent to giving them shell access to the server. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/#-critical-security-warning).
|
||||
**Workspace Tools execute arbitrary Python code on your server.** Only install from trusted sources, review code before importing, and restrict Workspace access to trusted administrators only. Granting a user the ability to create or import Tools is equivalent to giving them shell access to the server. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/).
|
||||
:::
|
||||
|
||||
## Writing A Custom Toolkit
|
||||
|
||||
@@ -8,7 +8,7 @@ title: "Tools"
|
||||
⚙️ Tools are the various ways you can extend an LLM's capabilities beyond simple text generation. When enabled, they allow your chatbot to do amazing things — like search the web, scrape data, generate images, talk back using AI voices, and more.
|
||||
|
||||
:::danger ⚠️ Critical Security Warning
|
||||
**Workspace Tools and Functions execute arbitrary Python code on your server.** Only install from trusted sources, review code before importing, and restrict Workspace access to trusted administrators only. Granting a user the ability to create or import Tools is equivalent to giving them shell access to the server. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/#-critical-security-warning).
|
||||
**Workspace Tools and Functions execute arbitrary Python code on your server.** Only install from trusted sources, review code before importing, and restrict Workspace access to trusted administrators only. Granting a user the ability to create or import Tools is equivalent to giving them shell access to the server. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/).
|
||||
:::
|
||||
|
||||
Because there are several ways to integrate "Tools" in Open WebUI, it's important to understand which type you are using.
|
||||
@@ -366,7 +366,7 @@ The native `query_knowledge_files` tool uses **hybrid search + reranking** when
|
||||
2. **Or disable Native Function Calling** for that model to restore automatic RAG injection.
|
||||
3. **Or use "Full Context" mode** for attached knowledge (click on the attachment and select "Use Entire Document") which always injects the full content.
|
||||
|
||||
See [Knowledge Scoping with Native Function Calling](/features/ai-knowledge/knowledge#knowledge-scoping-with-native-function-calling) for more details.
|
||||
See [Knowledge Scoping with Native Function Calling](/features/workspace/knowledge#scoped-access-keeps-things-organized) for more details.
|
||||
:::
|
||||
|
||||
**Why use these?** It allows for **Deep Research** (searching the web multiple times, or querying knowledge bases), **Contextual Awareness** (looking up previous chats or notes), **Dynamic Personalization** (saving facts), and **Precise Automation** (generating content based on existing notes or documents).
|
||||
|
||||
+114
-413
@@ -3,486 +3,187 @@ sidebar_position: 200
|
||||
title: "⭐ Features"
|
||||
---
|
||||
|
||||
# What You Can Do with Open WebUI
|
||||
|
||||
## Key Features of Open WebUI ⭐
|
||||
**One interface for every AI model. Private, extensible, and built for teams.**
|
||||
|
||||
- 🚀 **Effortless Setup**: Install seamlessly using Docker, Kubernetes, Podman, Helm Charts (`kubectl`, `kustomize`, `podman`, or `helm`) for a hassle-free experience with support for both `:ollama` image with bundled Ollama and `:cuda` with CUDA support. [Learn more in our Quick Start Guide](/getting-started/quick-start).
|
||||
|
||||
- 🛠️ **Guided Initial Setup**: Complete the setup process with clarity, including an explicit indication of creating an admin account during the first-time setup.
|
||||
|
||||
- 🤝 **Universal API Compatibility**: Effortlessly integrate with any backend that follows the **OpenAI Chat Completions protocol**. This includes official OpenAI endpoints alongside dozens of third-party and local providers. The API URL can be customized to integrate Open WebUI seamlessly into your existing infrastructure. [See Setup Guide](/getting-started/quick-start).
|
||||
|
||||
- 🛡️ **Granular Permissions and User Groups**: By allowing administrators to create detailed user roles, user groups, and permissions across the workspace, we ensure a secure user environment for all users involved. This granularity not only enhances security, but also allows for customized user experiences, fostering a sense of ownership and responsibility amongst users. [Learn more about RBAC](/features/access-security/rbac).
|
||||
|
||||
- 🔐 **SCIM 2.0 Provisioning**: Enterprise-grade user and group provisioning through SCIM 2.0 protocol, enabling seamless integration with identity providers like Okta, Azure AD, and Google Workspace for automated user lifecycle management. [Read the SCIM Guide](/features/access-security/auth/scim).
|
||||
|
||||
- 📂 **Centralized File Management**: A unified dashboard to search, view, and manage all your uploaded documents in one place. Includes automated cleanup of Knowledge Base associations and vector embeddings when deleting files. [Learn about File Management](/features/chat-conversations/data-controls/files).
|
||||
|
||||
- 💬 **Shared Chat Management**: A centralized interface to audit every conversation you've ever shared. Easily search through your shared history, re-copy links, or revoke (unshare) access instantly from a single location. [Learn about Shared Chats](/features/chat-conversations/data-controls/shared-chats).
|
||||
|
||||
- 📱 **Responsive Design**: Enjoy a seamless experience across desktop PCs, laptops, and mobile devices.
|
||||
|
||||
- 📱 **Progressive Web App for Mobile**: Enjoy a native progressive web application experience on your mobile device with offline access on `localhost` or a personal domain, and a smooth user interface. In order for our PWA to be installable on your device, it must be delivered in a secure context. This usually means that it must be served over HTTPS.
|
||||
|
||||
:::info
|
||||
|
||||
- To set up a PWA, you'll need some understanding of technologies like Linux, Docker, and reverse proxies such as `Nginx`, `Caddy`, or `Traefik`. Using these tools can help streamline the process of building and deploying a PWA tailored to your needs. While there's no "one-click install" option available, and your available option to securely deploy your Open WebUI instance over HTTPS requires user experience, using these resources can make it easier to create and deploy a PWA tailored to your needs.
|
||||
|
||||
:::
|
||||
|
||||
- ✒️🔢 **Full Markdown and LaTeX Support**: Elevate your LLM experience with comprehensive Markdown, LaTex, and Rich Text capabilities for enriched interaction. [Explore Interface Features](/category/interface).
|
||||
|
||||
- 🧩 **Model Builder**: Easily create custom models from base Ollama models directly from Open WebUI. Create and add custom characters and agents, customize model elements, and import models effortlessly through [Open WebUI Community](https://openwebui.com/) integration. [Learn more about Models](/features/ai-knowledge/models).
|
||||
|
||||
- 📚 **Advanced RAG Integration with Multiple Vector Databases**: Dive into the future of chat interactions with cutting-edge Retrieval Augmented Generation (RAG) technology. Choose from 9 vector database options: ChromaDB (default), PostgreSQL with PGVector, Qdrant, Milvus, Elasticsearch, OpenSearch, Pinecone, S3Vector, and Oracle 23ai. Documents can be loaded into the `Documents` tab of the Workspace and accessed using the pound key [`#`] before a query, or by starting the prompt with [`#`] followed by a URL for webpage content integration. [Learn more about RAG](/features/chat-conversations/rag).
|
||||
|
||||
- 📄 **Advanced Document Extraction with Multiple Engines**: Extract text and data from various document formats including PDFs, Word documents, Excel spreadsheets, PowerPoint presentations, and more using your choice of extraction engines: Apache Tika, Docling, Azure Document Intelligence, Mistral OCR, or external custom (self-built) content extraction engines/document loaders. Advanced document processing capabilities enable seamless integration with your knowledge base, preserving structure and formatting while supporting OCR for scanned documents and images. [Read about Document Extraction](/features/chat-conversations/rag/document-extraction).
|
||||
|
||||
- 🔍 **Web Search for RAG & Agentic Research**: Perform web searches using 15+ providers including SearXNG, Google PSE, Brave Search, Kagi, Mojeek, Bocha, Tavily, Perplexity, and more. When using **Native Function Calling**, models can perform multiple searches sequentially and use the `fetch_url` tool to read full page content for deep research. [Learn about Agentic Search](/features/chat-conversations/web-search/agentic-search).
|
||||
|
||||
- ✅ **Agentic Task Management**: Enable true multi-step execution by letting models maintain an explicit task/todo list in chat (pending, in progress, completed, cancelled) for transparent progress tracking and better reliability on complex work. [Learn about Task Management](/features/chat-conversations/chat-features/task-management).
|
||||
|
||||
- 🌐 **Web Browsing & URL Fetching**: Integrate websites by using the `#` command or allow the model to independently visit links using the `fetch_url` tool in Native Mode, extracting full text content for precise analysis.
|
||||
|
||||
- 🎨 **Image Generation & Editing Integration**: Seamlessly create and edit images using engines like DALL-E, Gemini, ComfyUI, and AUTOMATIC1111. Supports **Native Tool Calling**, allowing models to independently generate and refine images during a conversation. [Learn more about Image Gen](/category/create--edit-images).
|
||||
|
||||
- ⚙️ **Concurrent Model Utilization**: Effortlessly engage with multiple models simultaneously, harnessing their unique strengths for optimal responses. Leverage a diverse set of model modalities in parallel to enhance your experience.
|
||||
|
||||
- 🔐 **Role-Based Access Control (RBAC)**: Ensure secure access with restricted permissions. Only authorized individuals can access your Ollama, while model creation and pulling rights are exclusively reserved for administrators. [Learn more about RBAC](/features/access-security/rbac).
|
||||
|
||||
- 🌐🌍 **Multilingual Support**: Experience Open WebUI in your preferred language with our internationalization (`i18n`) support. We invite you to join us in expanding our supported languages! We're actively seeking contributors!
|
||||
|
||||
- 💾 **Persistent Artifact Storage**: Built-in key-value storage API for artifacts, enabling features like journals, trackers, leaderboards, and collaborative tools with both personal and shared data scopes that persist across sessions. [Explore Chat Features](/features/chat-conversations/chat-features).
|
||||
|
||||
- ☁️ **Cloud Storage Integration**: Native support for cloud storage backends including Amazon S3 (with S3-compatible providers), Google Cloud Storage, and Microsoft Azure Blob Storage for scalable file storage and data management. [See Storage Config](/reference/env-configuration#cloud-storage).
|
||||
|
||||
- ☁️ **Enterprise Cloud Integration**: Seamlessly import documents from Google Drive and OneDrive/SharePoint directly through the file picker interface, enabling smooth workflows with enterprise cloud storage solutions. [Learn more in Environment Config](/reference/env-configuration#onedrive) and check out the [SharePoint Guide](/tutorials/integrations/onedrive-sharepoint/).
|
||||
|
||||
- 📊 **Production Observability with OpenTelemetry**: Built-in OpenTelemetry support for comprehensive monitoring with traces, metrics, and logs export to your existing observability stack (Prometheus, Grafana, Jaeger, etc.), enabling production-grade monitoring and debugging. [See Observability Config](/reference/env-configuration/#opentelemetry-configuration).
|
||||
|
||||
- 🔒 **Encrypted Database Support**: Optional at-rest encryption for SQLite databases using SQLCipher, providing enhanced security for sensitive data in smaller deployments without requiring PostgreSQL infrastructure. [See Database Encryption](/reference/env-configuration#encrypted-sqlite-with-sqlcipher).
|
||||
|
||||
- ⚖️ **Horizontal Scalability for Production**: Redis-backed session management and WebSocket support enabling multi-worker and multi-node deployments behind load balancers for high-availability production environments. [See Advanced Topics](/getting-started/advanced-topics) and our [Multi-Replica Guide](/troubleshooting/multi-replica).
|
||||
|
||||
- 🌟 **Continuous Updates**: We are committed to improving Open WebUI with regular updates, fixes, and new features.
|
||||
|
||||
## And many more remarkable features including... ⚡️
|
||||
Open WebUI replaces the patchwork of AI tools your team juggles daily - ChatGPT for writing, a separate app for image generation, another for document search, spreadsheets full of prompts nobody can find. Everything lives in one place: conversations, knowledge, tools, and the models that power them.
|
||||
|
||||
---
|
||||
|
||||
### 🔧 Pipelines Support
|
||||
## 💬 Chat & Conversations
|
||||
|
||||
- 🔧 **Pipelines Framework**: Seamlessly integrate and customize your Open WebUI experience with our modular plugin framework for enhanced customization and functionality (https://github.com/open-webui/pipelines). Our framework allows for the easy addition of custom logic and integration of Python libraries, from AI agents to home automation APIs. Perfect for plugin and tool development, as well as creating custom functions and filters. [Learn more about Pipelines](/features/extensibility/pipelines).
|
||||
**Talk to any model, switch mid-conversation, and never lose context.**
|
||||
|
||||
- �️ **Native Python Function Calling**: Access the power of Python directly within Open WebUI with native function calling. Easily integrate custom code to build unique features like custom RAG pipelines, web search tools, and even agent-like actions via a built-in code editor to seamlessly develop and integrate function code within the `Tools` and `Functions` workspace. [Learn more about Tools](/features/extensibility/plugin/tools).
|
||||
Your conversations are the core of Open WebUI. Chat with Ollama, OpenAI, Anthropic, or any OpenAI-compatible provider from a single interface. Attach files, search the web, execute code, and let the AI use tools - all without leaving the chat.
|
||||
|
||||
- �📥 **Upload Pipeline**: Pipelines can be uploaded directly from the `Admin Panel` > `Settings` > `Pipelines` menu, streamlining the pipeline management process.
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🔀 **Multi-model chats** | Run two models side-by-side and compare responses |
|
||||
| 📎 **File & image uploads** | Attach documents, images, and code for the AI to analyze |
|
||||
| 🔍 **Web search** | AI searches the web and cites sources in real time |
|
||||
| 🐍 **Code execution** | Run Python directly in the browser or via [Open Terminal](/features/open-terminal) |
|
||||
| 📝 **Message queue** | Keep typing while the AI responds - messages send automatically |
|
||||
| 🧠 **Memory** | The AI remembers facts about you across conversations |
|
||||
| 🗂️ **Folders, tags, pins** | Organize conversations however you work |
|
||||
| 🎤 **Voice & audio** | Speech-to-text, text-to-speech, hands-free voice & video calls |
|
||||
| 🖼️ **Image generation** | Create and edit images with DALL-E, Gemini, ComfyUI, and more |
|
||||
| ⏱️ **Automations** | Schedule prompts to run automatically on recurring schedules |
|
||||
| ✅ **Task management** | Models maintain structured task lists for multi-step workflows |
|
||||
|
||||
#### The possibilities with our Pipelines framework knows no bounds and are practically limitless. Start with a few pre-built pipelines to help you get started!
|
||||
|
||||
- 🔗 **Function Calling**: Integrate [Function Calling](https://github.com/open-webui/pipelines/blob/main/examples/filters/function_calling_filter_pipeline.py) seamlessly through Pipelines to enhance your LLM interactions with advanced function calling capabilities.
|
||||
|
||||
- 📚 **Custom RAG**: Integrate a [custom Retrieval Augmented Generation (RAG)](https://github.com/open-webui/pipelines/tree/main/examples/pipelines/rag) pipeline seamlessly to enhance your LLM interactions with custom RAG logic.
|
||||
|
||||
- 📊 **Message Monitoring with Langfuse**: Monitor and analyze message interactions in real-time usage statistics via [Langfuse](https://github.com/open-webui/pipelines/blob/main/examples/filters/langfuse_filter_pipeline.py) pipeline.
|
||||
|
||||
- ⚖️ **User Rate Limiting**: Manage API usage efficiently by controlling the flow of requests sent to LLMs to prevent exceeding rate limits with [Rate Limit](https://github.com/open-webui/pipelines/blob/main/examples/filters/rate_limit_filter_pipeline.py) pipeline.
|
||||
|
||||
- 🌍 **Real-Time LibreTranslate Translation**: Integrate real-time translations into your LLM interactions using [LibreTranslate](https://github.com/open-webui/pipelines/blob/main/examples/filters/libretranslate_filter_pipeline.py) pipeline, enabling cross-lingual communication.
|
||||
- Please note that this pipeline requires further setup with LibreTranslate in a Docker container to work.
|
||||
|
||||
- 🛡️ **Toxic Message Filtering**: Our [Detoxify](https://github.com/open-webui/pipelines/blob/main/examples/filters/detoxify_filter_pipeline.py) pipeline automatically filters out toxic messages to maintain a clean and safe chat environment.
|
||||
|
||||
- 🔒 **LLM-Guard**: Ensure secure LLM interactions with [LLM-Guard](https://github.com/open-webui/pipelines/blob/main/examples/filters/llmguard_prompt_injection_filter_pipeline.py) pipeline, featuring a Prompt Injection Scanner that detects and mitigates crafty input manipulations targeting large language models. This protects your LLMs from data leakage and adds a layer of resistance against prompt injection attacks.
|
||||
|
||||
- 🕒 **Conversation Turn Limits**: Improve interaction management by setting limits on conversation turns with [Conversation Turn Limit](https://github.com/open-webui/pipelines/blob/main/examples/filters/conversation_turn_limit_filter.py) pipeline.
|
||||
|
||||
- 📈 **OpenAI Generation Stats**: Our [OpenAI](https://github.com/open-webui/pipelines/blob/main/examples/pipelines/providers/openai_manifold_pipeline.py) pipeline provides detailed generation statistics for OpenAI models.
|
||||
|
||||
- **🚀 Multi-Model Support**: Our seamless integration with various AI models from [various providers](https://github.com/open-webui/pipelines/tree/main/examples/pipelines/providers) expands your possibilities with a wide range of language models to select from and interact with.
|
||||
|
||||
#### In addition to the extensive features and customization options, we also provide [a library of example pipelines ready to use](https://github.com/open-webui/pipelines/tree/main/examples) along with [a practical example scaffold pipeline](https://github.com/open-webui/pipelines/blob/main/examples/scaffolds/example_pipeline_scaffold.py) to help you get started. These resources will streamline your development process and enable you to quickly create powerful LLM interactions using Pipelines and Python. Happy coding! 💡
|
||||
[**Explore chat features →**](/features/chat-conversations/chat-features) · [**Audio →**](/features/chat-conversations/audio) · [**Image Generation →**](/features/chat-conversations/image-generation-and-editing)
|
||||
|
||||
---
|
||||
|
||||
### 🖥️ User Experience
|
||||
## 📚 Knowledge & RAG
|
||||
|
||||
- 🖥️ **Intuitive Interface**: The chat interface has been designed with the user in mind, drawing inspiration from the user interface of ChatGPT.
|
||||
**Give your AI access to your documents - and let it find what matters.**
|
||||
|
||||
- ⚡ **Swift Responsiveness**: Enjoy reliably fast and responsive performance.
|
||||
Upload files, build knowledge bases, and let the AI retrieve exactly the information it needs. Choose between vector search (RAG) for large collections or full-content injection for precision. With native function calling, models autonomously search, browse, and synthesize across your entire knowledge base.
|
||||
|
||||
- 🎨 **Splash Screen**: A simple loading splash screen for a smoother user experience.
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 📄 **9 vector databases** | ChromaDB, PGVector, Qdrant, Milvus, Elasticsearch, and more |
|
||||
| 🔍 **Hybrid search** | BM25 + vector search with cross-encoder reranking |
|
||||
| 📑 **5 extraction engines** | Tika, Docling, Azure, Mistral OCR, custom loaders |
|
||||
| 🤖 **Agentic retrieval** | Models search and read your documents autonomously |
|
||||
| 📄 **Full context mode** | Inject entire documents - no chunking, no guessing |
|
||||
|
||||
- 🌐 **Personalized Interface**: Choose between a freshly designed search landing page and the classic chat UI from Settings > Interface, allowing for a tailored experience. [Explore Interface Options](/category/interface).
|
||||
|
||||
- 📦 **Pip Install Method**: Installation of Open WebUI can be accomplished via the command `pip install open-webui`, which streamlines the process and makes it more accessible to new users. For further information, please visit: https://pypi.org/project/open-webui/.
|
||||
|
||||
- 🌈 **Theme Customization**: Personalize your Open WebUI experience with a range of options, including a variety of solid, yet sleek themes, customizable chat background images, and three mode options: Light, Dark, or OLED Dark mode - or let *Her* choose for you! ;)
|
||||
|
||||
- 🖼️ **Custom Background Support**: Set a custom background from Settings > Interface to personalize your experience.
|
||||
|
||||
- 📝 **Rich Banners with Markdown**: Create visually engaging announcements with markdown support in banners, enabling richer and more dynamic content. [See Banners Documentation](/features/access-security/interface/banners).
|
||||
|
||||
- 💻 **Code Syntax Highlighting**: Our syntax highlighting feature enhances code readability, providing a clear and concise view of your code.
|
||||
|
||||
- 🗨️ **Markdown Rendering in User Messages**: User messages are now rendered in Markdown, enhancing readability and interaction.
|
||||
|
||||
- 🎨 **Flexible Text Input Options**: Switch between rich text input and legacy text area input for chat, catering to user preferences and providing a choice between advanced formatting and simpler text input.
|
||||
|
||||
- 👆 **Effortless Code Sharing** : Streamline the sharing and collaboration process with convenient code copying options, including a floating copy button in code blocks and click-to-copy functionality from code spans, saving time and reducing frustration.
|
||||
|
||||
- 🎨 **Interactive Artifacts**: Render web content and SVGs directly in the interface, supporting quick iterations and live changes for enhanced creativity and productivity.
|
||||
|
||||
- 🖊️ **Live Code Editing**: Supercharged code blocks allow live editing directly in the LLM response, with live reloads supported by artifacts, streamlining coding and testing.
|
||||
|
||||
- 🔍 **Enhanced SVG Interaction**: Pan and zoom capabilities for SVG images, including Mermaid diagrams, enable deeper exploration and understanding of complex concepts.
|
||||
|
||||
- 🔍 **Text Select Quick Actions**: Floating buttons appear when text is highlighted in LLM responses, offering deeper interactions like "Ask a Question" or "Explain", and enhancing overall user experience.
|
||||
|
||||
- ↕️ **Bi-Directional Chat Support**: You can easily switch between left-to-right and right-to-left chat directions to accommodate various language preferences.
|
||||
|
||||
- 📱 **Mobile Accessibility**: The sidebar can be opened and closed on mobile devices with a simple swipe gesture.
|
||||
|
||||
- 🤳 **Haptic Feedback on Supported Devices**: Android devices support haptic feedback for an immersive tactile experience during certain interactions.
|
||||
|
||||
- 🔍 **User Settings Search**: Quickly search for settings fields, improving ease of use and navigation.
|
||||
|
||||
- 📜 **Offline Swagger Documentation**: Access developer-friendly Swagger API documentation offline, ensuring full accessibility wherever you are.
|
||||
|
||||
- 💾 **Performance Optimizations**: Lazy loading of large dependencies minimizes initial memory usage, boosting performance and reducing loading times.
|
||||
|
||||
- 🚀 **Persistent and Scalable Configuration**: Open WebUI configurations are stored in a database (webui.db), allowing for seamless load balancing, high-availability setups, and persistent settings across multiple instances, making it easy to access and reuse your configurations.
|
||||
|
||||
- 🔄 **Portable Import/Export**: Easily import and export Open WebUI configurations, simplifying the process of replicating settings across multiple systems.
|
||||
|
||||
- ❓ **Quick Access to Documentation & Shortcuts**: The question mark button located at the bottom right-hand corner of the main UI screen (available on larger screens like desktop PCs and laptops) provides users with easy access to the Open WebUI documentation page and available keyboard shortcuts.
|
||||
|
||||
- 📜 **Changelog & Check for Updates**: Users can access a comprehensive changelog and check for updates in the `Settings` > `About` > `See What's New` menu, which provides a quick overview of the latest features, improvements, and bug fixes, as well as the ability to check for updates.
|
||||
[**Learn about Knowledge →**](/features/workspace/knowledge)
|
||||
|
||||
---
|
||||
|
||||
### 💬 Conversations
|
||||
## 🤖 Models & Agents
|
||||
|
||||
- 💬 **True Asynchronous Chat**: Enjoy uninterrupted multitasking with true asynchronous chat support, allowing you to create chats, navigate away, and return anytime with responses ready.
|
||||
**Wrap any model with custom instructions, tools, and knowledge to build specialized agents.**
|
||||
|
||||
- 🔔 **Chat Completion Notifications**: Stay updated with instant in-UI notifications when a chat finishes in a non-active tab, ensuring you never miss a completed response.
|
||||
Create a "Python Tutor" that always uses your style guide. A "Meeting Summarizer" with your company's template. A "Code Reviewer" with your linting rules baked in. Every agent is a configuration wrapper - pick any base model, bind knowledge, tools, and a system prompt.
|
||||
|
||||
- 📝 **Message Queue**: Continue composing messages while the AI is generating a response. Your messages are queued and automatically sent together when the current response completes. Edit, delete, or send queued messages immediately. [Learn about Message Queue](/features/chat-conversations/chat-features/message-queue).
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🧩 **Model presets** | System prompts, tools, knowledge, and parameters in one package |
|
||||
| 🏷️ **Dynamic variables** | `{{ USER_NAME }}`, `{{ CURRENT_DATE }}` injected automatically |
|
||||
| 🔧 **Bound tools** | Force-enable specific tools per model |
|
||||
| 👥 **Access control** | Restrict models to specific users or groups |
|
||||
| 📊 **Global defaults** | Set baseline capabilities and parameters for all models |
|
||||
|
||||
- 🌐 **Notification Webhook Integration**: Receive timely updates for long-running chats or external integration needs with configurable webhook notifications, even when your tab is closed. [Learn more about Webhooks](/features/access-security/interface/webhooks).
|
||||
|
||||
- 📚 **Channels (Beta)**: Explore real-time collaboration between users and AIs with Discord/Slack-style chat rooms, build bots for channels, and unlock asynchronous communication for proactive multi-agent workflows. [See Channels](/features/channels).
|
||||
|
||||
- 🖊️ **Typing Indicators in Channels**: Enhance collaboration with real-time typing indicators in channels, keeping everyone engaged and informed.
|
||||
|
||||
- 👤 **User Status Indicators**: Quickly view a user's status by clicking their profile image in channels, providing better coordination and availability insights. This feature can be globally disabled by an administrator (Admin > Settings > General).
|
||||
|
||||
- 💬 **Chat Controls**: Easily adjust parameters for each chat session, offering more precise control over your interactions.
|
||||
|
||||
- 💖 **Favorite Response Management**: Easily mark and organize favorite responses directly from the chat overview, enhancing ease of retrieval and access to preferred responses.
|
||||
|
||||
- 📌 **Pinned Chats**: Support for pinned chats, allowing you to keep important conversations easily accessible.
|
||||
|
||||
- 🔍 **RAG Embedding Support**: Change the Retrieval Augmented Generation (RAG) embedding model directly in the `Admin Panel` > `Settings` > `Documents` menu, enhancing document processing. This feature supports Ollama and OpenAI models.
|
||||
|
||||
- 📜 **Citations in RAG Feature**: The Retrieval Augmented Generation (RAG) feature allows users to easily track the context of documents fed to LLMs with added citations for reference points.
|
||||
|
||||
- 🌟 **Enhanced RAG Pipeline**: A togglable hybrid search sub-feature for our RAG embedding feature that enhances the RAG functionality via `BM25`, with re-ranking powered by `CrossEncoder`, and configurable relevance score thresholds.
|
||||
|
||||
- 📹 **YouTube RAG Pipeline**: The dedicated Retrieval Augmented Generation (RAG) pipeline for summarizing YouTube videos via video URLs enables smooth interaction with video transcriptions directly.
|
||||
|
||||
- 📁 **Comprehensive Document Retrieval**: Toggle between full document retrieval and traditional snippets, enabling comprehensive tasks like summarization and supporting enhanced document capabilities.
|
||||
|
||||
- 🌟 **RAG Citation Relevance**: Easily assess citation accuracy with the addition of relevance percentages in RAG results.
|
||||
|
||||
- 🗂️ **Advanced RAG**: Improve RAG accuracy with smart pre-processing of chat history to determine the best queries before retrieval.
|
||||
|
||||
- 📚 **Inline Citations for RAG**: Benefit from seamless inline citations for Retrieval-Augmented Generation (RAG) responses, improving traceability and providing source clarity for newly uploaded files.
|
||||
|
||||
- 📁 **Large Text Handling**: Optionally convert large pasted text into a file upload to be used directly with RAG, keeping the chat interface cleaner.
|
||||
|
||||
- 🔄 **Multi-Modal Support**: Effortlessly engage with models that support multi-modal interactions, including images (`e.g., LLaVA`).
|
||||
|
||||
- 🤖 **Multiple Model Support**: Quickly switch between different models for diverse chat interactions.
|
||||
|
||||
- 🔀 **Merge Responses in Many Model Chat**: Enhances the dialogue by merging responses from multiple models into a single, coherent reply.
|
||||
|
||||
- ✅ **Multiple Instances of Same Model in Chats**: Enhanced many model chat to support adding multiple instances of the same model.
|
||||
|
||||
- 💬 **Temporary Chat Feature**: Introduced a temporary chat feature, deprecating the old chat history setting to enhance user interaction flexibility. Please note that **document processing in temporary chats is performed entirely in the browser** to ensure privacy and data minimization. This means specific file types requiring backend processing (like complex DOCX parsing) may have limited functionality in temporary mode.
|
||||
|
||||
- 🖋️ **User Message Editing**: Enhanced the user chat editing feature to allow saving changes without sending.
|
||||
|
||||
- 💬 **Efficient Conversation Editing**: Create new message pairs quickly and intuitively using the Cmd/Ctrl+Shift+Enter shortcut, streamlining conversation length tests.
|
||||
|
||||
- 🖼️ **Client-Side Image Compression**: Save bandwidth and improve performance with client-side image compression, allowing you to compress images before upload from Settings > Interface.
|
||||
|
||||
- 👥 **'@' Model Integration**: By seamlessly switching to any accessible local or external model during conversations, users can harness the collective intelligence of multiple models in a single chat. This can done by using the `@` command to specify the model by name within a chat.
|
||||
|
||||
- 🏷️ **Conversation Tagging** : Effortlessly categorize and locate tagged chats for quick reference and streamlined data collection using our efficient 'tag:' query system, allowing you to manage, search, and organize your conversations without cluttering the interface.
|
||||
|
||||
- 🧠 **Auto-Tagging**: Conversations can optionally be automatically tagged for improved organization, mirroring the efficiency of auto-generated titles.
|
||||
|
||||
- 👶 **Chat Cloning**: Easily clone and save a snapshot of any chat for future reference or continuation. This feature makes it easy to pick up where you left off or share your session with others. To create a copy of your chat, simply click on the `Clone` button in the chat's dropdown options. Can you keep up with your clones?
|
||||
|
||||
- ⭐ **Visualized Conversation Flows**: Interactive messages diagram for improved visualization of conversation flows, enhancing understanding and navigation of complex discussions.
|
||||
|
||||
- 📁 **Chat Folders**: Organize your chats into folders, drag and drop them for easy management, and export them seamlessly for sharing or analysis.
|
||||
|
||||
- 📤 **Easy Chat Import**: Import chats into your workspace by simply dragging and dropping chat exports (JSON) onto the sidebar.
|
||||
|
||||
- 📜 **Prompt Preset Support**: Instantly access custom preset prompts using the `/` command in the chat input. Load predefined conversation starters effortlessly and expedite your interactions. Import prompts with ease through [Open WebUI Community](https://openwebui.com/) integration or create your own!
|
||||
|
||||
- 📅 **Prompt Variables Support**: Prompt variables such as `{{CLIPBOARD}}`, `{{CURRENT_DATE}}`, `{{CURRENT_DATETIME}}`, `{{CURRENT_TIME}}`, `{{CURRENT_TIMEZONE}}`, `{{CURRENT_WEEKDAY}}`, `{{USER_NAME}}`, `{{USER_LANGUAGE}}`, and `{{USER_LOCATION}}` can be utilized in the system prompt or by using a slash command to select a prompt directly within a chat.
|
||||
- Please note that the `{{USER_LOCATION}}` prompt variable requires a secure connection over HTTPS. To utilize this particular prompt variable, please ensure that `{{USER_LOCATION}}` is toggled on from the `Settings` > `Interface` menu.
|
||||
- Please note that the `{{CLIPBOARD}}` prompt variables requires access to your device's clipboard.
|
||||
|
||||
- 🧠 **Memory Feature & Tools (Experimental)**: Manage information you want your LLMs to remember via `Settings` > `Personalization` > `Memory`. Capable models can now use `add_memory`, `search_memories`, and `replace_memory_content` tools to dynamically store, retrieve, and update facts about you during chat sessions. [Learn more about Memory](/features/chat-conversations/memory).
|
||||
[**Learn about Models →**](/features/workspace/models)
|
||||
|
||||
---
|
||||
|
||||
### 💻 Model Management
|
||||
## 📝 Notes
|
||||
|
||||
- 🛠️ **Model Builder**: All models can be built and edited with a persistent model builder mode within the models edit page.
|
||||
**Write, think, and refine with AI by your side.**
|
||||
|
||||
- 📚 **Knowledge Support for Models**: The ability to attach tools, functions, and knowledge collections directly to models from a model's edit page, enhancing the information available to each model.
|
||||
A dedicated workspace for content that lives outside of any single conversation. Draft with a rich editor, use AI to rewrite text in place, and attach notes to any chat for precise context injection - no chunking, no vector search.
|
||||
|
||||
- 🗂️ **Model Presets**: Create and manage model presets for both the Ollama and OpenAI API.
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| ✍️ **Rich editor** | Markdown and Rich Text with a floating formatting toolbar |
|
||||
| 🤖 **AI Enhance** | Rewrite or improve selected text in place |
|
||||
| 📎 **Context injection** | Attach notes to any chat for full-fidelity context |
|
||||
| 🔍 **Agentic access** | Models can search, read, and update notes autonomously |
|
||||
|
||||
- 🏷️ **Model Tagging**: The models workspace enables users to organize their models using tagging.
|
||||
|
||||
- 📋 **Model Selector Dropdown Ordering**: Models can be effortlessly organized by dragging and dropping them into desired positions within the model workspace, which will then reflect the changes in the model dropdown menu.
|
||||
|
||||
- 🔍 **Model Selector Dropdown**: Easily find and select your models with fuzzy search and detailed model information with model tags and model descriptions.
|
||||
|
||||
- ⌨️ **Arrow Keys Model Selection**: Use arrow keys for quicker model selection, enhancing accessibility.
|
||||
|
||||
- 🔧 **Quick Actions in Model Workspace**: Enhanced Shift key quick actions for hiding/displaying and deleting models in the model workspace.
|
||||
|
||||
- 😄 **Transparent Model Usage**: Stay informed about the system's state during queries with knowledge-augmented models, thanks to visible status displays.
|
||||
|
||||
- ⚙️ **Fine-Tuned Control with Advanced Parameters**: Gain a deeper level of control by adjusting model parameters such as `seed`, `temperature`, `frequency penalty`, `context length`, `seed`, and more.
|
||||
|
||||
- 🔄 **Seamless Integration**: Copy any `ollama run {model:tag}` CLI command directly from a model's page on [Ollama library](https://ollama.com/library/) and paste it into the model dropdown to easily select and pull models.
|
||||
|
||||
- 🗂️ **Create Ollama Modelfile**: To create a model file for Ollama, navigate to the `Admin Panel` > `Settings` > `Models` > `Create a model` menu.
|
||||
|
||||
- ⬆️ **GGUF File Model Creation**: Effortlessly create Ollama models by uploading GGUF files directly from Open WebUI from the `Admin Settings` > `Settings` > `Model` > `Experimental` menu. The process has been streamlined with the option to upload from your machine or download GGUF files from Hugging Face.
|
||||
|
||||
- ⚙️ **Default Model Setting**: The default model preference for new chats can be set in the `Settings` > `Interface` menu on mobile devices, or can more easily be set in a new chat under the model selector dropdown on desktop PCs and laptops.
|
||||
|
||||
- 💡 **LLM Response Insights**: Details of every generated response can be viewed, including external model API insights and comprehensive local model info.
|
||||
|
||||
- 🕒 **Model Details at a Glance**: View critical model details, including model hash and last modified timestamp, directly in the Models workspace for enhanced tracking and management.
|
||||
|
||||
- 📥🗑️ **Download/Delete Models**: Models can be downloaded or deleted directly from Open WebUI with ease.
|
||||
|
||||
- 🔄 **Update All Ollama Models**: A convenient button allows users to update all their locally installed models in one operation, streamlining model management.
|
||||
|
||||
- 🍻 **TavernAI Character Card Integration**: Experience enhanced visual storytelling with TavernAI Character Card Integration in our model builder. Users can seamlessly incorporate TavernAI character card PNGs directly into their model files, creating a more immersive and engaging user experience.
|
||||
|
||||
- 🎲 **Model Playground (Beta)**: Try out models with the model playground area (`beta`), which enables users to test and explore model capabilities and parameters with ease in a sandbox environment before deployment in a live chat environment. Export your playground conversations in JSON format (compatible with Open WebUI chat import) or as plain text for easy sharing and documentation.
|
||||
[**Learn about Notes →**](/features/notes)
|
||||
|
||||
---
|
||||
|
||||
### 👥 Collaboration
|
||||
## 💬 Channels
|
||||
|
||||
- 🗨️ **Local Chat Sharing**: Generate and share chat links between users in an efficient and seamless manner. Includes a **centralized management interface** in Settings to view, copy links, or unshare conversations at any time. [Learn more about Chat Sharing](/features/chat-conversations/chat-features/chatshare).
|
||||
**Where your team and AI think together, in real time.**
|
||||
|
||||
- 👍👎 **RLHF Annotation**: Enhance the impact of your messages by rating them with either a thumbs up or thumbs down AMD provide a rating for the response on a scale of 1-10, followed by the option to provide textual feedback, facilitating the creation of datasets for Reinforcement Learning from Human Feedback (`RLHF`). Utilize your messages to train or fine-tune models, all while ensuring the confidentiality of locally saved data.
|
||||
Persistent, shared spaces where humans and AI models participate in the same conversation. Tag `@gpt-4o` to draft a plan, then tag `@claude` to critique it - your whole team sees both responses in one timeline.
|
||||
|
||||
- 🔧 **Comprehensive Feedback Export**: Export feedback history data to JSON for seamless integration with RLHF processing and further analysis, providing valuable insights for improvement.
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🤖 **@model tagging** | Summon any AI model into the conversation on demand |
|
||||
| 🧵 **Threads & reactions** | Replies, pins, and emoji reactions |
|
||||
| 🔒 **Access control** | Public, private, group-based, and direct message channels |
|
||||
| 🧠 **AI channel awareness** | Models search and synthesize across channels autonomously |
|
||||
|
||||
- 🤝 **Community Sharing**: Share your chat sessions with the [Open WebUI Community](https://openwebui.com/) by clicking the `Share to Open WebUI Community` button. This feature allows you to engage with other users and collaborate on the platform.
|
||||
- To utilize this feature, please sign-in to your Open WebUI Community account. Sharing your chats fosters a vibrant community, encourages knowledge sharing, and facilitates joint problem-solving. Please note that community sharing of chat sessions is an optional feature. Only Admins can toggle this feature on or off in the `Admin Settings` > `Settings` > `General` menu.
|
||||
|
||||
- 🏆 **Community Leaderboard**: Compete and track your performance in real-time with our leaderboard system, which utilizes the ELO rating system and allows for optional sharing of feedback history.
|
||||
|
||||
- ⚔️ **Model Evaluation Arena**: Conduct blind A/B testing of models directly from the Admin Settings for a true side-by-side comparison, making it easier to find the best model for your needs.
|
||||
|
||||
- 🎯 **Topic-Based Rankings**: Discover more accurate rankings with our experimental topic-based re-ranking system, which adjusts leaderboard standings based on tag similarity in feedback. [Learn more about Evaluation](/features/access-security/evaluation).
|
||||
|
||||
- 📂 **Unified and Collaborative Workspace** : Access and manage all your model files, prompts, documents, tools, and functions in one convenient location, while also enabling multiple users to collaborate and contribute to models, knowledge, prompts, or tools, streamlining your workflow and enhancing teamwork.
|
||||
[**Learn about Channels →**](/features/channels)
|
||||
|
||||
---
|
||||
|
||||
### 📚 History & Archive
|
||||
## ⚡ Open Terminal
|
||||
|
||||
- 📜 **Chat History**: Access and manage your conversation history with ease via the chat navigation sidebar. Toggle off chat history in the `Settings` > `Chats` menu to prevent chat history from being created with new interactions.
|
||||
**Give your AI a real computer to work on.**
|
||||
|
||||
- 🔄 **Regeneration History Access**: Easily revisit and explore your entire LLM response regeneration history.
|
||||
Connect a real computing environment to Open WebUI. The AI writes code, executes it, reads the output, fixes errors, and iterates - all from the chat. Handles files, installs packages, runs servers, and returns results.
|
||||
|
||||
- 📬 **Archive Chats**: Effortlessly store away completed conversations you've had with models for future reference or interaction, maintaining a tidy and clutter-free chat interface.
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🖥️ **Code execution** | Runs real commands and returns output |
|
||||
| 📁 **File browser** | Browse, upload, download, and edit files in the sidebar |
|
||||
| 🌐 **Website preview** | Live preview of web projects inside Open WebUI |
|
||||
| 🔒 **Isolation optional** | Docker container or bare metal |
|
||||
|
||||
- 🗃️ **Archive All Chats**: This feature allows you to quickly archive all of your chats at once.
|
||||
|
||||
- 📦 **Export All Archived Chats as JSON**: This feature enables users to easily export all their archived chats in a single JSON file, which can be used for backup or transfer purposes.
|
||||
|
||||
- 📄 **Download Chats as JSON/PDF/TXT**: Easily download your chats individually in your preferred format of `.json`, `.pdf`, or `.txt` format.
|
||||
|
||||
- 📤📥 **Import/Export Chat History**: Seamlessly move your chat data in and out of the platform via `Import Chats` and `Export Chats` options.
|
||||
|
||||
- 🗑️ **Delete All Chats**: This option allows you to permanently delete all of your chats, ensuring a fresh start.
|
||||
[**Learn about Open Terminal →**](/features/open-terminal)
|
||||
|
||||
---
|
||||
|
||||
### 🎙️ Audio, Voice, & Accessibility
|
||||
## 🔌 Extensibility
|
||||
|
||||
- 🗣️ **Voice Input Support with Multiple Providers**: Engage with your model through voice interactions using multiple Speech-to-Text providers: Local Whisper (default, with VAD filtering), OpenAI-compatible endpoints, Deepgram, and Azure Speech Services. Enjoy the convenience of talking to your model directly with automatic voice input after 3 seconds of silence for a streamlined experience. [Explore Audio Features](/category/speech-to-text--text-to-speech).
|
||||
- Microphone access requires manually setting up a secure connection over HTTPS to work, or [manually whitelisting your URL at your own risk](/troubleshooting/audio#solutions-for-non-https-connections).
|
||||
**Add any capability with Python tools, pipelines, MCP, or OpenAPI servers.**
|
||||
|
||||
- 😊 **Emoji Call**: Toggle this feature on from the `Settings` > `Interface` menu, allowing LLMs to express emotions using emojis during voice calls for a more dynamic interaction.
|
||||
- Microphone access requires manually setting up a secure connection over HTTPS to work, or [manually whitelisting your URL at your own risk](/troubleshooting/audio#solutions-for-non-https-connections).
|
||||
Open WebUI is a platform, not a locked-down product. Write Python tools that run inside the chat. Connect external services via OpenAPI or MCP. Build pipelines that filter, transform, or route every message. Import community-built extensions with one click.
|
||||
|
||||
- 🎙️ **Hands-Free Voice Call Feature**: Initiate voice calls without needing to use your hands, making interactions more seamless.
|
||||
- Microphone access requires manually setting up a secure connection over HTTPS to work, or [manually whitelisting your URL at your own risk](/troubleshooting/audio#solutions-for-non-https-connections).
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🐍 **Tools & Functions** | Python scripts that run in the chat - built-in code editor included |
|
||||
| 🔧 **Pipelines** | Modular plugin framework for filters, providers, and custom logic |
|
||||
| 🔗 **MCP support** | Native Streamable HTTP for Model Context Protocol servers |
|
||||
| 🌐 **OpenAPI servers** | Auto-discover tools from any OpenAPI-compatible endpoint |
|
||||
| 📝 **Skills** | Markdown instruction sets that teach models how to approach tasks |
|
||||
| ⚡ **Prompts** | Slash-command templates with typed input variables and versioning |
|
||||
|
||||
- 📹 **Video Call Feature**: Enable video calls with supported vision models like LlaVA and GPT-4o, adding a visual dimension to your communications.
|
||||
- Both Camera & Microphone access is required using a secure connection over HTTPS for this feature to work, or [manually whitelisting your URL at your own risk](/troubleshooting/audio#solutions-for-non-https-connections).
|
||||
|
||||
- 👆 **Tap to Interrupt**: Stop the AI’s speech during voice conversations with a simple tap on mobile devices, ensuring seamless control over the interaction.
|
||||
|
||||
- 🎙️ **Voice Interrupt**: Stop the AI’s speech during voice conversations with your voice on mobile devices, ensuring seamless control over the interaction.
|
||||
|
||||
- 🔊 **Multiple Text-to-Speech Providers**: Customize your Text-to-Speech experience with multiple providers: OpenAI-compatible endpoints, Azure Speech Services, ElevenLabs (with EU residency support), local Transformers models, and browser-based WebAPI for reading aloud LLM responses.
|
||||
|
||||
- 🔗 **Direct Call Mode Access**: Activate call mode directly from a URL, providing a convenient shortcut for mobile device users.
|
||||
|
||||
- ✨ **Customizable Text-to-Speech**: Control how message content is segmented for Text-to-Speech (TTS) generation requests, allowing for flexible speech output options.
|
||||
|
||||
- 🔊 **Azure Speech Services Integration**: Supports Azure Speech services for Text-to-Speech (TTS), providing users with a wider range of speech synthesis options.
|
||||
|
||||
- 🎚️ **Customizable Audio Playback**: Allows users to adjust audio playback speed to their preferences in Call mode settings, enhancing accessibility and usability.
|
||||
|
||||
- 🎵 **Broad Audio Compatibility**: Enjoy support for a wide range of audio file format transcriptions with RAG, including 'audio/x-m4a', to broaden compatibility with audio content within the platform.
|
||||
|
||||
- 🎤 **Deepgram Speech-to-Text Integration**: Leverage Deepgram's advanced speech recognition capabilities for high-accuracy voice transcription, providing an additional STT option beyond local Whisper and OpenAI.
|
||||
|
||||
- 🔊 **ElevenLabs Text-to-Speech Integration**: Access ElevenLabs' premium voice synthesis with support for EU residency API endpoints, offering high-quality and natural-sounding voice output for enhanced user experiences.
|
||||
|
||||
- 🔊 **Audio Compression**: Experimental audio compression allows navigating around the 25MB limit for OpenAI's speech-to-text processing, expanding the possibilities for audio-based interactions.
|
||||
|
||||
- 🗣️ **Experimental SpeechT5 TTS**: Enjoy local SpeechT5 support for improved text-to-speech capabilities.
|
||||
[**Learn about Extensibility →**](/features/extensibility)
|
||||
|
||||
---
|
||||
|
||||
### 🐍 Code Execution
|
||||
## 🔐 Authentication & Access
|
||||
|
||||
- 🚀 **Versatile, UI-Agnostic, OpenAI-Compatible Plugin Framework**: Seamlessly integrate and customize [Open WebUI Pipelines](https://github.com/open-webui/pipelines) for efficient data processing and model training, ensuring ultimate flexibility and scalability.
|
||||
- 🐍 **Python Code Execution**: Execute Python code locally in the browser via Pyodide with a range of libraries supported by Pyodide.
|
||||
**Control who gets in, what they can do, and how it connects to your identity stack.**
|
||||
|
||||
- 🌊 **Mermaid Rendering**: Create visually appealing diagrams and flowcharts directly within Open WebUI using the [Mermaid Diagramming and charting tool](https://mermaid.js.org/intro/), which supports Mermaid syntax rendering.
|
||||
|
||||
- 🔗 **Iframe Support**: Enables rendering HTML directly into your chat interface using functions and tools.
|
||||
Open WebUI is multi-user from day one. Define roles, create user groups, set per-model access, and integrate with your identity provider. From a solo install to an organization with thousands of seats.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 👥 **RBAC** | Roles, groups, and per-resource permissions |
|
||||
| 🔐 **SSO/OIDC/LDAP** | Federated authentication with any identity provider |
|
||||
| 📋 **SCIM 2.0** | Automated user and group provisioning |
|
||||
| 🔑 **API Keys** | Programmatic access for scripts, bots, and integrations |
|
||||
|
||||
[**Learn about Authentication & Access →**](/features/authentication-access)
|
||||
|
||||
---
|
||||
|
||||
### 🔒 Integration & Security
|
||||
## 🔧 Administration
|
||||
|
||||
- ✨ **Multiple OpenAI-Compatible API Support**: Seamlessly integrate and customize various OpenAI-compatible APIs, enhancing the versatility of your chat interactions.
|
||||
**Monitor usage, evaluate models, and communicate with your users.**
|
||||
|
||||
- 🔑 **Simplified API Key Management**: Easily generate and manage secret keys to leverage Open WebUI with OpenAI libraries, streamlining integration and development.
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 📊 **Analytics** | Usage dashboards with message volume, token consumption, and cost tracking |
|
||||
| 🏆 **Evaluation** | Model arena, A/B testing, and ELO-based leaderboards |
|
||||
| 📢 **Banners** | Customizable system-wide announcements |
|
||||
| 🔔 **Webhooks** | Notifications for sign-ups, chat completion, and external integrations |
|
||||
|
||||
- 🌐 **HTTP/S Proxy Support**: Configure network settings easily using the `http_proxy` or `https_proxy` environment variable. These variables, if set, should contain the URLs for HTTP and HTTPS proxies, respectively. For web search content fetching behind a proxy, enable **Trust Proxy Environment** in Admin Panel > Settings > Web Search (or set `WEB_SEARCH_TRUST_ENV=True`).
|
||||
|
||||
- 🌐🔗 **External Ollama Server Connectivity**: Seamlessly link to an external Ollama server hosted on a different address by configuring the environment variable.
|
||||
|
||||
- 🛢️ **Flexible Database Integration**: Seamlessly connect to custom databases, including SQLite, Postgres, and multiple vector databases like Milvus, using environment variables for flexible and scalable data management.
|
||||
|
||||
- 🗄️ **Multiple Vector Database Support**: Choose from 9 vector database options for optimal RAG performance: ChromaDB (default), PostgreSQL with PGVector, Qdrant, Milvus, Elasticsearch, OpenSearch, Pinecone, S3Vector, and Oracle 23ai. Each option provides different scaling characteristics and performance profiles to match your deployment needs.
|
||||
|
||||
- ☁️ **Enterprise Cloud Storage Backends**: Configure cloud storage backends including Amazon S3 (with S3-compatible providers like MinIO), Google Cloud Storage, and Microsoft Azure Blob Storage for scalable file storage, enabling stateless instances and distributed deployments.
|
||||
|
||||
- 📂 **Cloud File Picker Integration**: Import documents directly from Google Drive and OneDrive/SharePoint through native file picker interfaces, streamlining workflows for users working with enterprise cloud storage solutions.
|
||||
|
||||
- 🌐🗣️ **External Speech-to-Text Support**: The addition of external speech-to-text (`STT`) services provides enhanced flexibility, allowing users to choose their preferred provider for seamless interaction.
|
||||
|
||||
- 🌐 **Remote ChromaDB Support**: Extend the capabilities of your database by connecting to remote ChromaDB servers.
|
||||
|
||||
- 🔀 **Multiple Ollama Instance Load Balancing**: Effortlessly distribute chat requests across multiple Ollama instances for enhanced performance and reliability.
|
||||
|
||||
- 🚀 **Advanced Load Balancing and Reliability**: Utilize enhanced load balancing capabilities, stateless instances with full Redis support, and automatic web socket re-connection to promote better performance, reliability, and scalability in WebUI, ensuring seamless and uninterrupted interactions across multiple instances.
|
||||
|
||||
- ☁️ **Cloud Storage Backend Support**: Enable stateless Open WebUI instances with cloud storage backends (Amazon S3, Google Cloud Storage, Microsoft Azure Blob Storage) for enhanced scalability, high availability, and balancing heavy workloads across multiple instances.
|
||||
|
||||
- 🛠️ **OAuth Management for User Groups**: Enhance control and scalability in collaborative environments with group-level management via OAuth integration.
|
||||
|
||||
- 🔐 **SCIM 2.0 Automated Provisioning**: Enterprise-grade user and group provisioning through SCIM 2.0 protocol, enabling seamless integration with identity providers like Okta, Azure AD, and Google Workspace for automated user lifecycle management, reducing administrative overhead.
|
||||
|
||||
- 📊 **OpenTelemetry Observability**: Export traces, metrics, and logs to your observability stack using OpenTelemetry protocol (OTLP), supporting both gRPC and HTTP exporters with configurable endpoints, authentication, and sampling strategies for comprehensive production monitoring.
|
||||
[**Learn about Administration →**](/features/administration)
|
||||
|
||||
---
|
||||
|
||||
### 👑 Administration
|
||||
## 🏗️ Deploy Anywhere
|
||||
|
||||
- 👑 **Super Admin Assignment**: Automatically assigns the first sign-up as a super admin with an unchangeable role that cannot be modified by anyone else, not even other admins.
|
||||
**Docker, Kubernetes, pip, bare metal - with horizontal scaling and production observability.**
|
||||
|
||||
- 🛡️ **Granular User Permissions**: Restrict user actions and access with customizable role-based permissions, ensuring that only authorized individuals can perform specific tasks.
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🐳 **Docker & Compose** | One-command deploy with GPU support |
|
||||
| ☸️ **Kubernetes & Helm** | Production-ready orchestration |
|
||||
| 📦 **pip install** | `pip install open-webui && open-webui serve` |
|
||||
| ☁️ **Cloud storage** | S3, GCS, Azure Blob for stateless instances |
|
||||
| 📊 **OpenTelemetry** | Traces, metrics, and logs to your observability stack |
|
||||
| ⚖️ **Horizontal scaling** | Redis-backed sessions, multi-worker, multi-node |
|
||||
|
||||
- 👥 **Multi-User Management**: Intuitive admin panel with pagination allows you to seamlessly manage multiple users, streamlining user administration and simplifying user life-cycle management.
|
||||
|
||||
- 🔧 **Admin Panel**: The user management system is designed to streamline the on-boarding and management of users, offering the option to add users directly or in bulk via CSV import.
|
||||
|
||||
- 👥 **Active Users Indicator**: Monitor the number of active users and which models are being utilized by whom to assist in gauging when performance may be impacted due to a high number of users.
|
||||
|
||||
- 📊 **Analytics Dashboard**: Comprehensive usage insights for administrators including message volume, token consumption, user activity, and model performance metrics with interactive time-series charts and detailed breakdowns. Track costs, identify trends, and make data-driven decisions about resource allocation. [Learn more about Analytics](/features/access-security/analytics).
|
||||
|
||||
- 🔒 **Default Sign-Up Role**: Specify the default role for new sign-ups to `pending`, `user`, or `admin`, providing flexibility in managing user permissions and access levels for new users.
|
||||
|
||||
- 🤖 **Bulk Model Management & Filtering**: Administrators can effortlessly manage large model collections from external providers with tools to bulk enable/disable models and filter the admin list by status (Enabled, Disabled, Hidden, etc.) to maintain a clean workspace. [Learn about Admin Models](/features/ai-knowledge/models#global-model-management-admin).
|
||||
|
||||
- 🔒 **Prevent New Sign-Ups**: Enable the option to disable new user sign-ups, restricting access to the platform and maintaining a fixed number of users.
|
||||
|
||||
- 🔒 **Prevent Chat Deletion**: Ability for admins to toggle a setting that prevents all users from deleting their chat messages, ensuring that all chat messages are retained for audit or compliance purposes.
|
||||
|
||||
- 🔗 **Webhook Integration**: Subscribe to new user sign-up events via webhook (compatible with `Discord`, `Google Chat`, `Slack` and `Microsoft Teams`), providing real-time notifications and automation capabilities. [See Webhook Guide](/features/access-security/interface/webhooks).
|
||||
|
||||
- ⏱️ **Scheduled Automations**: Create recurring prompt automations that run in the background using schedule rules (including RRULE) and can be managed per user via RBAC permissions. [Learn more about Automations](/features/chat-conversations/chat-features/automations).
|
||||
|
||||
- 📣 **Configurable Notification Banners**: Admins can create customizable banners with persistence in config.json, featuring options for content, background color (`info`, `warning`, `error`, or `success`), and dismissibility. Banners are accessible only to logged-in users, ensuring the confidentiality of sensitive information.
|
||||
|
||||
- 🛡️ **Model Whitelisting**: Enhance security and access control by allowing admins to whitelist models for users with the `user` role, ensuring that only authorized models can be accessed.
|
||||
|
||||
- 🔑 **Admin Control for Community Sharing**: Admins can enable or disable community sharing for all users via a toggle in the `Admin Panel` > `Settings` menu. This toggle allows admins to manage accessibility and privacy, ensuring a secure environment. Admins have the option of enabling or disabling the `Share on Community` button for all users, which allows them to control community engagement and collaboration.
|
||||
|
||||
- 📧 **Trusted Email Authentication**: Optionally authenticate using a trusted email header, adding an extra layer of security and authentication to protect your Open WebUI instance.
|
||||
|
||||
- 🔒 **Backend Reverse Proxy Support**: Bolster security through direct communication between Open WebUI's backend and Ollama. This key feature eliminates the need to expose Ollama over the local area network (LAN). Requests made to the `/ollama/api` route from Open WebUI are seamlessly redirected to Ollama from the backend, enhancing overall system security and providing an additional layer of protection.
|
||||
|
||||
- 🔒 **Authentication**: Please note that Open WebUI does not natively support federated authentication schemes such as SSO, OAuth, SAML, or OIDC. However, it can be configured to delegate authentication to an authenticating reverse proxy, effectively achieving a Single Sign-On (`SSO`) experience. This setup allows you to centralize user authentication and management, enhancing security and user convenience. By integrating Open WebUI with an authenticating reverse proxy, you can leverage existing authentication systems and streamline user access to Open WebUI. For more information on configuring this feature, please refer to the [Federated Authentication Support](https://docs.openwebui.com/features/auth).
|
||||
|
||||
- 🔓 **Optional Authentication**: Enjoy the flexibility of disabling authentication by setting `WEBUI_AUTH` to `False`. This is an ideal solution for fresh installations without existing users or can be useful for demonstration purposes.
|
||||
|
||||
- 🚫 **Advanced API Security**: Block API users based on customized model filters, enhancing security and control over API access.
|
||||
|
||||
- ❗ **Administrator Updates**: Ensure administrators stay informed with immediate update notifications upon login, keeping them up-to-date on the latest changes and system statuses.
|
||||
|
||||
- 👥 **User Group Management**: Create and manage user groups for seamless organization and control.
|
||||
|
||||
- 🔐 **Group-Based Access Control**: Set granular access to models, knowledge, prompts, and tools based on user groups, allowing for more controlled and secure environments.
|
||||
|
||||
- 🛠️ **Granular User Permissions**: Easily manage workspace permissions, including file uploads, deletions, edits, and temporary chats, as well as model, knowledge, prompt, and tool creation. [See User Permissions Config](/reference/env-configuration/#user-permissions).
|
||||
|
||||
- 🔑 **LDAP Authentication**: Enhance security and scalability with LDAP support for user management. [Learn more about LDAP](/features/access-security/auth/ldap).
|
||||
|
||||
- 🔐 **SCIM 2.0 Provisioning**: Automate user and group lifecycle management through SCIM 2.0 protocol integration with identity providers like Okta, Azure AD, and Google Workspace, reducing administrative overhead and ensuring synchronized user management across systems.
|
||||
|
||||
- 🌐 **Customizable OpenAI Connections**: Enjoy smooth operation with custom OpenAI setups, including prefix ID support and explicit model ID support for APIs.
|
||||
|
||||
- 🔐 **Ollama API Key Management**: Manage Ollama credentials, including prefix ID support, for secure and efficient operation.
|
||||
|
||||
- 🔄 **Connection Management**: Easily enable or disable individual OpenAI and Ollama connections as needed.
|
||||
|
||||
- 🎨 **Intuitive Model Workspace**: Manage models across users and groups with a redesigned and user-friendly interface.
|
||||
|
||||
- 🔑 **API Key Authentication**: Tighten security by easily enabling or disabling API key authentication.
|
||||
|
||||
- 🔄 **Unified Model Reset**: Reset and remove all models from the Admin Settings with a one-click option.
|
||||
|
||||
- 🔓 **Flexible Model Access Control**: Easily bypass model access controls for user roles when not required, using the 'BYPASS_MODEL_ACCESS_CONTROL' environment variable, simplifying workflows in trusted environments.
|
||||
|
||||
- 🔒 **Configurable API Key Authentication Restrictions**: Flexibly configure endpoint restrictions for API key authentication, now off by default for a smoother setup in trusted environments.
|
||||
|
||||
---
|
||||
[**Quick Start →**](/getting-started/quick-start) · [**Advanced Topics →**](/getting-started/advanced-topics)
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
{
|
||||
"label": "🎨 Media & Generation",
|
||||
"position": 50,
|
||||
"collapsible": true,
|
||||
"collapsed": true
|
||||
}
|
||||
@@ -1,7 +0,0 @@
|
||||
{
|
||||
"label": "Create & Edit Images",
|
||||
"position": 400,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
}
|
||||
@@ -110,8 +110,8 @@ flowchart LR
|
||||
|
||||
Two deployment backends are available:
|
||||
|
||||
- **[Docker Backend](./terminals/docker-backend)** - runs on a single Docker host. Best for small-to-medium teams or environments without Kubernetes.
|
||||
- **[Kubernetes Operator](./terminals/kubernetes-operator)** - production-grade deployment using a CRD-based operator. Deploys alongside Open WebUI via the Helm chart.
|
||||
- **[Docker Backend](./terminals/docker-backend)** — runs on a single Docker host. Best for small-to-medium teams or environments without Kubernetes.
|
||||
- **[Kubernetes Operator](./terminals/kubernetes-operator)** — production-grade deployment using a CRD-based operator. Deploys alongside Open WebUI via the Helm chart.
|
||||
|
||||
:::info Enterprise license required
|
||||
Terminals requires an [Open WebUI Enterprise License](https://openwebui.com/enterprise). See the [Terminals repository](https://github.com/open-webui/terminals) for license details.
|
||||
|
||||
@@ -196,13 +196,13 @@ The `Terminal` custom resource is the declarative API for managing terminal inst
|
||||
### Printer columns
|
||||
|
||||
```bash
|
||||
kubectl get terminals -n open-webui
|
||||
kubectl get terminals -n open-webui -o wide
|
||||
```
|
||||
|
||||
```
|
||||
NAME USER PHASE SERVICE URL LAST ACTIVITY AGE
|
||||
terminal-a1b2c3-default user-123 Running http://terminal-a1b2c3-default-svc.open-webui.svc:8000 2026-04-01T10:30:00Z 5m
|
||||
terminal-d4e5f6-datascience user-456 Idle http://terminal-d4e5f6-datascience-svc.open-webui.svc:8000 2026-04-01T09:45:00Z 1h
|
||||
NAME USER PHASE SERVICE URL LAST ACTIVITY AGE
|
||||
terminal-a1b2c3-default user-123 Running http://terminal-a1b2c3-default-svc.open-webui.svc:8000 5m 5m
|
||||
terminal-d4e5f6-datascience user-456 Idle http://terminal-d4e5f6-datascience-svc.open-webui.svc:8000 1h 1h
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,151 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: "Knowledge"
|
||||
---
|
||||
|
||||
# 📚 Knowledge
|
||||
|
||||
**Give your AI access to your documents and let it find what matters.**
|
||||
|
||||
Knowledge is where you store the files and collections that your AI can search, read, and reason over. Upload PDFs, spreadsheets, code, or any text-based document. Build collections around projects, teams, or topics. When a model needs an answer, it pulls from your knowledge base instead of guessing.
|
||||
|
||||
Unlike [Notes](/features/notes), which inject full content into every message, Knowledge uses retrieval (RAG) to find the relevant chunks on demand. This makes it the right choice for large document sets where injecting everything would exceed the context window.
|
||||
|
||||
---
|
||||
|
||||
## Why Knowledge?
|
||||
|
||||
### Your documents become searchable by AI
|
||||
|
||||
Upload a folder of contracts, technical specs, or research papers. The AI searches them by meaning, not just keywords, and cites where it found the answer.
|
||||
|
||||
### Two retrieval modes for different needs
|
||||
|
||||
Choose **Focused Retrieval** (RAG) to let the AI search large collections efficiently, or **Full Context** to inject an entire document word-for-word when precision matters.
|
||||
|
||||
### Autonomous exploration with native function calling
|
||||
|
||||
With [native function calling](/features/extensibility/plugin/tools#tool-calling-modes-default-vs-native) enabled, models don't just search. They browse your knowledge bases, read files page by page, and synthesize across multiple documents without manual prompting.
|
||||
|
||||
### Scoped access keeps things organized
|
||||
|
||||
Attach specific knowledge bases to a model so it only searches what's relevant. Or leave it unscoped and let the model discover everything the user has access to.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 📄 **9 vector databases** | ChromaDB, PGVector, Qdrant, Milvus, OpenSearch, Elasticsearch, and more |
|
||||
| 🔍 **Hybrid search** | BM25 keyword search + vector search with cross-encoder reranking |
|
||||
| 📑 **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 |
|
||||
| 📦 **Export and API** | Back up knowledge bases as zip files, manage via REST API |
|
||||
|
||||
---
|
||||
|
||||
## Retrieval Modes
|
||||
|
||||
When attaching files or knowledge bases to a model, click on the attached item to toggle between modes:
|
||||
|
||||
### 🔍 Focused Retrieval (default)
|
||||
|
||||
Uses RAG to find and inject the most relevant chunks based on the user's query. When hybrid search is enabled (`ENABLE_RAG_HYBRID_SEARCH`), retrieval combines BM25 keyword search with vector search, plus reranking for accuracy.
|
||||
|
||||
Best for large document sets where only specific sections are relevant.
|
||||
|
||||
### 📄 Full Context
|
||||
|
||||
Injects the complete content of the file into every message. No chunking, no semantic search. Always injected regardless of native function calling settings, so the model doesn't need to call any tools to access it.
|
||||
|
||||
Best for short reference documents, style guides, or context that's always relevant.
|
||||
|
||||
---
|
||||
|
||||
## Agentic Knowledge Tools
|
||||
|
||||
With [native function calling](/features/extensibility/plugin/tools#tool-calling-modes-default-vs-native) enabled, models interact with your knowledge bases using built-in tools. Which tools appear depends on whether specific knowledge is attached to the model:
|
||||
|
||||
| Tool | Attached KB | No KB attached | Description |
|
||||
|------|:-----------:|:--------------:|-------------|
|
||||
| `list_knowledge` | ✅ | ❌ | List all KBs, files, and notes attached to the model |
|
||||
| `list_knowledge_bases` | ❌ | ✅ | Browse available knowledge bases with file counts |
|
||||
| `search_knowledge_bases` | ❌ | ✅ | Find knowledge bases by name or description |
|
||||
| `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) |
|
||||
| `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.
|
||||
|
||||
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).
|
||||
|
||||
:::warning Knowledge is NOT auto-injected with native function calling
|
||||
|
||||
When native function calling is enabled, attached knowledge is **not automatically injected**. The model must call the knowledge tools to search and retrieve. If your model isn't using attached knowledge:
|
||||
|
||||
1. **Add system prompt instructions** telling the model to use `list_knowledge` and `query_knowledge_files`.
|
||||
2. **Disable native function calling** for that model to restore automatic RAG injection.
|
||||
3. **Switch to Full Context mode** for the attachment to bypass RAG entirely.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Setting Up a Knowledge Base
|
||||
|
||||
1. Click **Workspace** in the sidebar, then select **Knowledge**.
|
||||
2. Click **+ New Knowledge** and give it a name and description.
|
||||
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 `#`.
|
||||
|
||||
### 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.
|
||||
|
||||
### API access
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Project documentation
|
||||
|
||||
Upload your team's technical specs, architecture docs, and runbooks into a knowledge base. Attach it to a "Project Assistant" model. The AI answers questions grounded in your actual documentation instead of generic training data.
|
||||
|
||||
### Legal and compliance review
|
||||
|
||||
Load contracts, policies, and regulatory documents. Ask the AI to find specific clauses, compare terms across agreements, or flag inconsistencies.
|
||||
|
||||
### Research synthesis
|
||||
|
||||
Add dozens of papers to a knowledge base. The AI searches across all of them to answer questions, find supporting evidence, or identify contradictions between studies.
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
### Context window with Full Context mode
|
||||
|
||||
"Using Entire Document" injects the full text. A large document attached to a model with a small context window will crowd out conversation history.
|
||||
|
||||
### Processing delay for API uploads
|
||||
|
||||
Files uploaded via API are processed asynchronously. Attempting to use a file before processing completes will fail silently or return empty results.
|
||||
|
||||
### Native function calling changes behavior
|
||||
|
||||
Enabling native function calling changes how knowledge bases work. If your KB suddenly stops producing results, check whether `function_calling: native` was set in global model defaults. See [Knowledge Base troubleshooting](/troubleshooting/rag#13-knowledge-base-attached-to-model-not-working) for details.
|
||||
@@ -0,0 +1,195 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: "Models"
|
||||
sidebar_label: "Models"
|
||||
---
|
||||
|
||||
# 🤖 Models
|
||||
|
||||
**Wrap any model with custom instructions, tools, and knowledge to build specialized agents.**
|
||||
|
||||
The Models workspace lets you create configuration presets that sit on top of any base model. Pick GPT-4o, Claude, Llama 3, or anything else connected to Open WebUI, then bind a system prompt, knowledge bases, tools, skills, and parameter overrides to it. The result is a purpose-built agent that behaves exactly the way you need without modifying the underlying model.
|
||||
|
||||
A "Python Tutor" that always uses your style guide. A "Meeting Summarizer" with your company's template. A "Code Reviewer" with your linting rules baked in. Every agent is a thin wrapper: pick a base model, configure it, and share it with your team.
|
||||
|
||||
---
|
||||
|
||||
## Why Models?
|
||||
|
||||
### One base model, many personas
|
||||
|
||||
The same GPT-4o can power a coding assistant, a customer support bot, and a creative writer. Each preset has its own system prompt, tools, and knowledge, so the model behaves differently depending on which preset is selected.
|
||||
|
||||
### Knowledge and tools come pre-attached
|
||||
|
||||
Instead of manually attaching documents and enabling tools every chat, bind them once to the model preset. Users get a fully configured agent out of the box.
|
||||
|
||||
### Granular access control
|
||||
|
||||
Restrict models to specific users or groups. A finance team sees their models; engineering sees theirs. Admins control what's available instance-wide.
|
||||
|
||||
### Dynamic system prompts
|
||||
|
||||
Use Jinja2-style variables like `{{ USER_NAME }}` and `{{ CURRENT_DATE }}` so the system prompt adapts to each user and session automatically.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🧩 **Model presets** | System prompt, tools, knowledge, skills, and parameters in one package |
|
||||
| 🏷️ **Dynamic variables** | `{{ USER_NAME }}`, `{{ CURRENT_DATE }}`, `{{ CURRENT_TIME }}` injected automatically |
|
||||
| 🔧 **Bound tools** | Force-enable specific tools per model |
|
||||
| 📚 **Attached knowledge** | Knowledge bases and files always available via RAG or full context |
|
||||
| 🎭 **Skills** | Bind markdown instruction sets loaded on-demand via `view_skill` |
|
||||
| 👥 **Access control** | Restrict to specific users or groups |
|
||||
| 📊 **Global defaults** | Set baseline capabilities and parameters for all models at once |
|
||||
| 🔊 **Per-model TTS voice** | Give each persona its own voice |
|
||||
|
||||
---
|
||||
|
||||
## Creating a Model
|
||||
|
||||
Click **+ New Model** in **Workspace > Models**, or click the ellipsis (**...**) on an existing model and select **Edit**.
|
||||
|
||||
### Core configuration
|
||||
|
||||
| Field | Description |
|
||||
| :--- | :--- |
|
||||
| **Avatar** | Upload a custom image. Animated GIF and WebP are supported |
|
||||
| **Name and ID** | Display name and unique identifier |
|
||||
| **Base Model** | The actual model that powers this agent |
|
||||
| **Description** | Short summary shown in the model selector |
|
||||
| **Tags** | Organize models in the dropdown |
|
||||
| **Visibility** | Private (specific users/groups) or public |
|
||||
|
||||
### System prompt and variables
|
||||
|
||||
The system prompt defines the behavior and persona. Use dynamic variables for context-aware instructions:
|
||||
|
||||
| Variable | Output example |
|
||||
| :--- | :--- |
|
||||
| `{{ CURRENT_DATE }}` | `2024-10-27` |
|
||||
| `{{ CURRENT_TIME }}` | `14:30:05` |
|
||||
| `{{ USER_NAME }}` | `Admin` |
|
||||
|
||||
```
|
||||
You are a helpful assistant for {{ USER_NAME }}.
|
||||
The current date is {{ CURRENT_DATE }}.
|
||||
```
|
||||
|
||||
### Capabilities and bindings
|
||||
|
||||
Toggle what the model can do and bind resources:
|
||||
|
||||
| Setting | What it controls |
|
||||
| :--- | :--- |
|
||||
| **Knowledge** | Bind collections or files. Click attached items to toggle between Focused Retrieval and Full Context. See [Retrieval Modes](/features/workspace/knowledge#retrieval-modes) |
|
||||
| **Tools** | Force-enable specific tools (e.g., Calculator for a Math Bot) |
|
||||
| **Skills** | Bind [Skills](/features/workspace/skills) so their manifests are always injected |
|
||||
| **Filters** | Attach pipeline filters (e.g., PII redaction) |
|
||||
| **Actions** | Attach action scripts (e.g., "Add to Memories") |
|
||||
| **Vision** | Enable image analysis (requires a vision-capable base model) |
|
||||
| **Web Search** | Enable the configured search provider |
|
||||
| **Code Interpreter** | Enable Python code execution |
|
||||
| **Image Generation** | Enable image generation |
|
||||
| **Builtin Tools** | Control which tool categories are available: Time, Memory, Chats, Notes, Knowledge, Channels |
|
||||
| **File Context** | When enabled, attached files are processed via RAG. When disabled, no file content is extracted |
|
||||
| **TTS Voice** | Set a specific voice for this model's responses |
|
||||
|
||||
### Advanced parameters
|
||||
|
||||
- **Stop Sequences**: Force-stop generation on specific strings (e.g., `<|end_of_text|>`, `User:`). Press Enter after each.
|
||||
- **Temperature, Top P, etc.**: Adjust creativity and determinism.
|
||||
|
||||
### Prompt suggestions
|
||||
|
||||
Clickable starter chips that appear when a user opens a fresh chat with this model. Add phrases like "Explain this code step-by-step" or "Summarize this document" to guide users.
|
||||
|
||||
---
|
||||
|
||||
## Model Management
|
||||
|
||||
From the model list, click the ellipsis (**...**) on any model:
|
||||
|
||||
| Action | Description |
|
||||
| :--- | :--- |
|
||||
| **Edit** | Open the configuration panel |
|
||||
| **Hide** | Remove from the model selector without deleting |
|
||||
| **Clone** | Create a copy (appends `-clone`) |
|
||||
| **Copy Link** | Copy a direct URL to the model settings |
|
||||
| **Export** | Download the configuration as `.json` |
|
||||
| **Share** | Share to the Open WebUI community |
|
||||
| **Delete** | Permanently remove the preset |
|
||||
|
||||
### Import and export
|
||||
|
||||
- **Import**: From `.json` files or Open WebUI community links
|
||||
- **Export**: Download all custom model configurations as a single `.json`
|
||||
- **Discover**: Browse community presets at the bottom of the page
|
||||
|
||||
:::info Downloading base models
|
||||
To download new base models, go to **Settings > Connections > Ollama** or type `ollama run hf.co/{username}/{repository}:{quantization}` in the model selector.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Global Model Defaults (Admin)
|
||||
|
||||
Administrators can set baseline capabilities and parameters that apply to all models via **Admin Panel > Settings > Models > ⚙️ (gear icon)**.
|
||||
|
||||
- **Default Model Metadata** (`DEFAULT_MODEL_METADATA`): Baseline capabilities (vision, web search, file context, code interpreter, builtin tools). Per-model overrides always win on conflicts.
|
||||
- **Default Model Params** (`DEFAULT_MODEL_PARAMS`): Baseline inference parameters (temperature, top_p, max_tokens, function_calling). Per-model values take precedence when explicitly set. This value is loaded from the environment as JSON; invalid JSON is ignored and falls back to `{}`.
|
||||
|
||||
### Merge behavior
|
||||
|
||||
| Setting type | Strategy | Example |
|
||||
|---|---|---|
|
||||
| **Capabilities** | Deep merge | Global sets `file_context: false`, model sets `vision: true` > model gets both |
|
||||
| **Other metadata** | Fill-only | Global sets description, model has none > model gets the global value |
|
||||
| **Parameters** | Simple merge | Global sets `temperature: 0.7`, model sets `0.3` > model gets `0.3` |
|
||||
|
||||
:::warning Knowledge base + function calling interaction
|
||||
Setting `function_calling: native` in global params changes how **all** models handle attached knowledge bases. In native mode, model-attached KBs are not auto-injected. The model must call builtin tools to retrieve knowledge. If your knowledge bases suddenly stop working, check global defaults first.
|
||||
|
||||
See [Knowledge Base troubleshooting](/troubleshooting/rag#13-knowledge-base-attached-to-model-not-working).
|
||||
:::
|
||||
|
||||
### Bulk management
|
||||
|
||||
Filter the admin model list by status (Enabled, Disabled, Visible, Hidden) and use **Bulk Actions** to enable or disable all models in the current view at once. Useful when external providers expose hundreds of models.
|
||||
|
||||
---
|
||||
|
||||
## Model Switching in Chat
|
||||
|
||||
Switch models mid-conversation without losing context. Select up to two models simultaneously to compare responses side-by-side, using the arrow buttons to navigate between them.
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Team-specific agents
|
||||
|
||||
Create a "Sales Assistant" with your CRM knowledge base, objection-handling prompts, and email drafting tools. Share it with the sales group. Engineering never sees it.
|
||||
|
||||
### Onboarding new users
|
||||
|
||||
Build models with descriptive prompt suggestions ("Ask me about our company policies", "Help me set up my development environment") so new team members know exactly what to ask.
|
||||
|
||||
### Enforcing organizational standards
|
||||
|
||||
Set global defaults to disable code interpreter across all models, enforce a consistent temperature, or require function calling. Individual models can override when needed.
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
### Preset, not fine-tune
|
||||
|
||||
Model presets configure behavior through system prompts and tool bindings. They do not modify the underlying model weights. For deep behavioral changes, you need actual fine-tuning.
|
||||
|
||||
### Fallback requires configuration
|
||||
|
||||
If a base model becomes unavailable, the preset will fail unless `ENABLE_CUSTOM_MODEL_FALLBACK` is set to `True` and a default model is configured in Admin Panel > Settings > Models.
|
||||
@@ -0,0 +1,267 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "Prompts"
|
||||
---
|
||||
|
||||
# 📝 Prompts
|
||||
|
||||
**Reusable slash commands that turn complex instructions into one-click forms.**
|
||||
|
||||
Prompts let you save frequently used instructions as slash commands. Type `/summarize` in any chat and the full prompt fires instantly. Add custom input variables and users get a popup form with dropdowns, date pickers, and text fields before the prompt is sent. No one needs to remember the exact wording or structure.
|
||||
|
||||
Every change is tracked with full version history. Roll back to a previous version, compare changes, and share prompts across your team with access controls.
|
||||
|
||||
---
|
||||
|
||||
## Why Prompts?
|
||||
|
||||
### Stop retyping the same instructions
|
||||
|
||||
Save the prompt once, use it with `/command`. Bug report templates, meeting minutes, code reviews, content briefs: anything you type more than twice should be a prompt.
|
||||
|
||||
### Turn prompts into interactive forms
|
||||
|
||||
Add typed input variables (dropdowns, date pickers, number fields, checkboxes) and users get a clean form instead of editing raw text. Non-technical users can run complex prompts without understanding the syntax.
|
||||
|
||||
### Version history with rollback
|
||||
|
||||
Every change creates a new version. Compare versions side-by-side, restore a previous version to production, and track who changed what.
|
||||
|
||||
### Controlled sharing
|
||||
|
||||
Share prompts with specific users or groups. Public prompts appear in everyone's `/` suggestions. Private prompts stay in your own workspace.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| ⚡ **Slash commands** | Type `/command` to insert the full prompt |
|
||||
| 📋 **Input variable forms** | Typed fields (text, dropdown, date, number, checkbox, and more) generate a popup form |
|
||||
| 🕑 **Version history** | Full change tracking with commit messages, rollback, and production pinning |
|
||||
| 🔄 **System variables** | `{{CURRENT_DATE}}`, `{{USER_NAME}}`, `{{CLIPBOARD}}` auto-replaced at runtime |
|
||||
| 🔒 **Access control** | Share with specific users, groups, or make public |
|
||||
| 🔀 **Enable/Disable toggle** | Deactivate prompts without deleting them |
|
||||
| 🏷️ **Tags** | Organize and filter your prompt library |
|
||||
|
||||
---
|
||||
|
||||
## Creating a Prompt
|
||||
|
||||
Navigate to **Workspace > Prompts** and click **+ New Prompt**.
|
||||
|
||||
| Field | Description |
|
||||
| :--- | :--- |
|
||||
| **Name** | Descriptive title for identification |
|
||||
| **Tags** | Categorize for filtering |
|
||||
| **Access** | Control who can view and use the prompt |
|
||||
| **Command** | The slash command trigger (e.g., `/summarize`) |
|
||||
| **Prompt Content** | The actual text sent to the model, with variables |
|
||||
| **Commit Message** | Optional description of changes for version tracking |
|
||||
|
||||
Use clear variable names (`{{your_name}}` not `{{var1}}`), add descriptive `placeholder` text, provide `default` values where sensible, and mark only truly essential fields as `:required`. Public prompts appear in every user's `/` suggestions, so be selective about what you make public. Use the enable/disable toggle to shelve prompts you're not actively using.
|
||||
|
||||
---
|
||||
|
||||
## Variables
|
||||
|
||||
### System variables
|
||||
|
||||
Automatically replaced with their value at runtime:
|
||||
|
||||
| Variable | Description |
|
||||
| :--- | :--- |
|
||||
| `{{CLIPBOARD}}` | Content from your clipboard (requires clipboard permission) |
|
||||
| `{{CURRENT_DATE}}` | Current date |
|
||||
| `{{CURRENT_DATETIME}}` | Current date and time |
|
||||
| `{{CURRENT_TIME}}` | Current time |
|
||||
| `{{CURRENT_TIMEZONE}}` | Current timezone |
|
||||
| `{{CURRENT_WEEKDAY}}` | Current day of the week |
|
||||
| `{{USER_NAME}}` | Your display name |
|
||||
| `{{USER_EMAIL}}` | Your email address |
|
||||
| `{{USER_BIO}}` | Bio from Settings > Account > User Profile (unreplaced if not set) |
|
||||
| `{{USER_GENDER}}` | Gender from Settings > Account > User Profile (unreplaced if not set) |
|
||||
| `{{USER_BIRTH_DATE}}` | Birth date from Settings > Account > User Profile (unreplaced if not set) |
|
||||
| `{{USER_AGE}}` | Age calculated from birth date (unreplaced if not set) |
|
||||
| `{{USER_LANGUAGE}}` | Your selected language |
|
||||
| `{{USER_LOCATION}}` | Your location (requires HTTPS + Settings > Interface toggle) |
|
||||
|
||||
### Custom input variables
|
||||
|
||||
Add variables to your prompt content and users get a popup form when they use the slash command.
|
||||
|
||||
**Simple input** creates a single-line text field:
|
||||
```
|
||||
{{variable_name}}
|
||||
```
|
||||
|
||||
**Typed input** creates a specific field type with configured properties:
|
||||
```
|
||||
{{variable_name | type:property="value"}}
|
||||
```
|
||||
|
||||
All custom variables are **optional by default**. Add `:required` to make a field mandatory:
|
||||
```
|
||||
{{title | text:required}}
|
||||
{{notes | textarea:placeholder="Additional context (optional)"}}
|
||||
```
|
||||
|
||||
### Available input types
|
||||
|
||||
| Type | Description | Example |
|
||||
| :--- | :--- | :--- |
|
||||
| **text** | Single-line text (default) | `{{name \| text:placeholder="Enter name":required}}` |
|
||||
| **textarea** | Multi-line text | `{{description \| textarea:required}}` |
|
||||
| **select** | Dropdown menu | `{{priority \| select:options=["High","Medium","Low"]:required}}` |
|
||||
| **number** | Numeric input | `{{count \| number:min=1:max=100:default=5}}` |
|
||||
| **checkbox** | Boolean toggle | `{{include_details \| checkbox:label="Include analysis"}}` |
|
||||
| **date** | Date picker | `{{start_date \| date:required}}` |
|
||||
| **datetime-local** | Date and time picker | `{{appointment \| datetime-local}}` |
|
||||
| **color** | Color picker | `{{brand_color \| color:default="#FFFFFF"}}` |
|
||||
| **email** | Email field with validation | `{{email \| email:required}}` |
|
||||
| **range** | Slider | `{{rating \| range:min=1:max=10}}` |
|
||||
| **tel** | Phone number | `{{phone \| tel}}` |
|
||||
| **time** | Time picker | `{{meeting_time \| time}}` |
|
||||
| **url** | URL with validation | `{{website \| url:required}}` |
|
||||
| **month** | Month and year (Chrome/Edge only, falls back to text in Firefox/Safari) | `{{billing_month \| month}}` |
|
||||
| **map** | Interactive map for coordinates (experimental) | `{{location \| map}}` |
|
||||
|
||||
---
|
||||
|
||||
## Message and Prompt Modifiers
|
||||
|
||||
These modifiers are especially useful for task model prompts (title generation, tag generation, follow-up suggestions) where conversations contain long messages like pasted documents or code.
|
||||
|
||||
### Prompt truncation
|
||||
|
||||
The `{{prompt}}` variable supports character-based truncation:
|
||||
|
||||
| Modifier | What it does |
|
||||
| :--- | :--- |
|
||||
| `{{prompt:start:N}}` | First N characters |
|
||||
| `{{prompt:end:N}}` | Last N characters |
|
||||
| `{{prompt:middletruncate:N}}` | First half + last half, N characters total |
|
||||
|
||||
### Message selectors vs pipe filters
|
||||
|
||||
The `{{MESSAGES}}` variable has two distinct modifier types that work at different levels:
|
||||
|
||||
**Message selectors** (colon `:`) control **how many messages** to include:
|
||||
|
||||
| Selector | What it does | Example |
|
||||
| :--- | :--- | :--- |
|
||||
| `START:N` | First N messages | `{{MESSAGES:START:5}}` |
|
||||
| `END:N` | Last N messages | `{{MESSAGES:END:5}}` |
|
||||
| `MIDDLETRUNCATE:N` | First N/2 + last N/2 messages | `{{MESSAGES:MIDDLETRUNCATE:6}}` |
|
||||
|
||||
With 20 messages, `{{MESSAGES:MIDDLETRUNCATE:6}}` keeps messages 1-3 and 18-20, skipping the 14 in the middle.
|
||||
|
||||
**Pipe filters** (pipe `|`) truncate the **content of each individual message** to a character limit:
|
||||
|
||||
| Filter | What it does | Example |
|
||||
| :--- | :--- | :--- |
|
||||
| `\|start:N` | First N characters of each message | `\{\{MESSAGES\|start:300\}\}` |
|
||||
| `\|end:N` | Last N characters of each message | `\{\{MESSAGES\|end:300\}\}` |
|
||||
| `\|middletruncate:N` | First + last half of each message | `\{\{MESSAGES\|middletruncate:500\}\}` |
|
||||
|
||||
**Combine both** to control which messages are included and how long each one is:
|
||||
|
||||
| Syntax | What it does |
|
||||
| :--- | :--- |
|
||||
| `\{\{MESSAGES:END:2\|middletruncate:500\}\}` | Last 2 messages, each capped at 500 characters |
|
||||
| `\{\{MESSAGES:START:5\|start:200\}\}` | First 5 messages, each capped at 200 characters |
|
||||
| `\{\{MESSAGES:MIDDLETRUNCATE:10\|middletruncate:50\}\}` | First 5 + last 5 messages, each capped at 50 characters |
|
||||
|
||||
:::warning Selectors count messages, not characters
|
||||
`{{MESSAGES:MIDDLETRUNCATE:500}}` selects **500 messages**. To limit characters per message, use a pipe filter: `\{\{MESSAGES\|middletruncate:500\}\}`. Without pipe filters, a single pasted document can consume the entire context window.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
Every save creates a new version. When editing a prompt, the **History sidebar** shows all versions with the commit message, author, timestamp, and a "Live" badge on the active production version.
|
||||
|
||||
**Preview** any version by clicking it. **Set as Production** to restore it as the active version. **Delete** old versions from the menu (the current production version cannot be deleted).
|
||||
|
||||
:::note Migration
|
||||
Prompts created before the versioning update were automatically migrated with their content preserved as the initial "Live" version. The URL structure changed from command-based to ID-based, so existing bookmarks may need updating. As of v0.5.0, all variables are optional by default.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Bug report generator (`/bug_report`)
|
||||
|
||||
A structured form with required summary, priority dropdown, and reproduction steps, plus optional context fields:
|
||||
|
||||
```txt
|
||||
Generate a bug report with the following details:
|
||||
|
||||
**Summary:** {{summary | text:placeholder="A brief summary of the issue":required}}
|
||||
**Priority:** {{priority | select:options=["Critical","High","Medium","Low"]:default="Medium":required}}
|
||||
**Steps to Reproduce:**
|
||||
{{steps | textarea:placeholder="1. Go to...\n2. Click on...\n3. See error...":required}}
|
||||
|
||||
**Additional Context:** {{additional_context | textarea:placeholder="Browser version, OS, screenshots, etc."}}
|
||||
**Workaround:** {{workaround | textarea:placeholder="Any temporary solutions found"}}
|
||||
|
||||
Please format this into a clear and complete bug report document.
|
||||
```
|
||||
|
||||
### Meeting minutes (`/meeting_minutes`)
|
||||
|
||||
Date and time pickers, required attendees and agenda, optional decisions and action items:
|
||||
|
||||
```txt
|
||||
# Meeting Minutes
|
||||
|
||||
**Date:** {{meeting_date | date:required}}
|
||||
**Time:** {{meeting_time | time:required}}
|
||||
**Title:** {{title | text:placeholder="e.g., Weekly Team Sync":required}}
|
||||
**Attendees:** {{attendees | text:placeholder="Comma-separated list of names":required}}
|
||||
|
||||
## Agenda / Key Discussion Points
|
||||
{{agenda_items | textarea:placeholder="Paste the agenda or list the key topics discussed.":required}}
|
||||
|
||||
## Decisions Made
|
||||
{{decisions | textarea:placeholder="Key decisions and outcomes"}}
|
||||
|
||||
## Action Items
|
||||
{{action_items | textarea:placeholder="Action item, assignee, and deadline for each."}}
|
||||
|
||||
## Next Meeting
|
||||
**Date:** {{next_meeting | date}}
|
||||
**Topics:** {{next_topics | text:placeholder="Items to discuss next time"}}
|
||||
|
||||
Please format this into a clean and professional meeting summary.
|
||||
```
|
||||
|
||||
### Title generation (task model template)
|
||||
|
||||
Uses message selectors + pipe filters to keep context small:
|
||||
|
||||
```txt
|
||||
Chat history:
|
||||
<chat_history>
|
||||
{{MESSAGES:END:2|middletruncate:500}}
|
||||
</chat_history>
|
||||
|
||||
Generate a short title for this conversation.
|
||||
```
|
||||
|
||||
Sends only the last 2 messages, each capped at 500 characters.
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
### Slash command namespace
|
||||
|
||||
Public prompts appear in every user's `/` suggestions. Too many public prompts clutter the menu. Use the enable/disable toggle to keep inactive prompts out of suggestions.
|
||||
|
||||
### Optional by default
|
||||
|
||||
All custom input variables are optional unless marked `:required`. If your prompt depends on a field, add `:required` explicitly.
|
||||
@@ -0,0 +1,184 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
title: "Skills"
|
||||
sidebar_label: "Skills"
|
||||
---
|
||||
|
||||
# 🧩 Skills
|
||||
|
||||
**Teach your AI how to approach a task with plain-text instructions.**
|
||||
|
||||
Skills are reusable, markdown-based instruction sets that you attach to models or invoke on-the-fly in chat. Unlike [Tools](/features/extensibility/plugin/tools) (executable Python scripts), Skills are plain-text instructions: code review guidelines, writing style rules, troubleshooting playbooks, data analysis workflows. The model reads them and follows them.
|
||||
|
||||
Mention a skill with `$` in chat to inject its full content immediately. Or bind skills to a model so they're always available, loaded on-demand to keep the context window efficient.
|
||||
|
||||
---
|
||||
|
||||
## Why Skills?
|
||||
|
||||
### Instructions without code
|
||||
|
||||
Write guidelines in Markdown. No Python, no API calls, no deployment. If you can write a document, you can create a skill.
|
||||
|
||||
### On-demand context loading
|
||||
|
||||
Model-attached skills use lazy loading. Only a lightweight manifest (name + description) is injected by default. The model loads the full instructions only when it needs them via the `view_skill` tool.
|
||||
|
||||
### Reusable across models
|
||||
|
||||
Create one "Code Review Guidelines" skill and attach it to every coding model. Update the skill once, and every model gets the new version.
|
||||
|
||||
### Composable with tools
|
||||
|
||||
Pair a skill with [Open Terminal](/features/open-terminal) or any tool server. The skill teaches the model *how* to use the tool (check exit codes, handle errors, use streaming for long-running commands), while the tool provides the *capability*.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 📝 **Markdown content** | Write instructions in plain Markdown |
|
||||
| ⚡ **$ mention in chat** | Type `$` to inject a skill's full content into the current message |
|
||||
| 🤖 **Model binding** | Attach skills to models so they're always available |
|
||||
| 📦 **Lazy loading** | Model-attached skills inject only a manifest; full content loads on-demand |
|
||||
| 📥 **Import/Export** | Import `.md` files with YAML frontmatter; export as JSON |
|
||||
| 🔒 **Access control** | Private by default, shareable with users or groups |
|
||||
| 🔀 **Active/Inactive toggle** | Deactivate skills without deleting them |
|
||||
|
||||
---
|
||||
|
||||
## How Skills Work
|
||||
|
||||
### User-selected skills ($ mention)
|
||||
|
||||
Type `$` in the chat input to open the skill picker. Select a skill, and its **full content is injected directly** into the system prompt. The model has immediate access to the complete instructions.
|
||||
|
||||
### Model-attached skills
|
||||
|
||||
Skills bound to a model use lazy loading:
|
||||
|
||||
1. **Manifest injection** - Only the skill's name and description are added to 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(skill_name)` to load them.
|
||||
|
||||
This means many skills can be attached to a model without consuming context window space until actually needed.
|
||||
|
||||
---
|
||||
|
||||
## Creating a Skill
|
||||
|
||||
Navigate to **Workspace > Skills** and click **+ New Skill**.
|
||||
|
||||
| Field | Description |
|
||||
| :--- | :--- |
|
||||
| **Name** | Human-readable display name (e.g., "Code Review Guidelines") |
|
||||
| **Skill ID** | Unique slug, auto-generated from the name. Editable during creation, read-only afterwards |
|
||||
| **Description** | Short summary shown in the manifest. For model-attached skills, the model uses this to decide whether to load the full instructions |
|
||||
| **Content** | Full skill instructions in Markdown |
|
||||
|
||||
### Importing from Markdown
|
||||
|
||||
Click **Import** and select a `.md` file. If the file contains YAML frontmatter with `name` and/or `description` fields, those values are auto-populated:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-review-guidelines
|
||||
description: Step-by-step instructions for thorough code reviews
|
||||
---
|
||||
|
||||
# Code Review Guidelines
|
||||
|
||||
1. Check for correctness...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Binding Skills to a Model
|
||||
|
||||
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**.
|
||||
|
||||
The selected skills' manifests are automatically injected, and the model can load full content on-demand via `view_skill`.
|
||||
|
||||
---
|
||||
|
||||
## Skill Management
|
||||
|
||||
From the Skills workspace list, use the ellipsis menu (**...**):
|
||||
|
||||
| Action | Description |
|
||||
| :--- | :--- |
|
||||
| **Edit** | Modify content, name, or description |
|
||||
| **Clone** | Create a copy with `-clone` appended to the ID |
|
||||
| **Export** | Download as JSON |
|
||||
| **Delete** | Permanently remove (Shift+Click for quick deletion) |
|
||||
|
||||
**Bulk export**: Click the **Export** button at the top of the Skills page to export all accessible skills as a single JSON file.
|
||||
|
||||
**Active/Inactive toggle**: Inactive skills are excluded from manifests and cannot be loaded by the model, even if bound to one or mentioned in chat.
|
||||
|
||||
---
|
||||
|
||||
## Access Control
|
||||
|
||||
Skills use the same [Access Control](/features/authentication-access/rbac) system as other workspace resources:
|
||||
|
||||
- **Private by default**: Only the creator can see and edit a new skill.
|
||||
- **Share with users or groups**: Grant `read` or `write` access via the **Access** button.
|
||||
- **Read-only access**: Users with read access can view but not edit. The editor shows a "Read Only" badge.
|
||||
|
||||
:::caution Attached skills still require user access
|
||||
Attaching a skill to a model does **not** bypass access control. When a user chats with the model, Open WebUI checks whether that user has read access to each attached skill. Skills the user can't access are silently excluded.
|
||||
|
||||
**Example**: An admin creates a private skill and attaches it to a shared model. Regular users chatting with this model will not get the skill because they don't have read access.
|
||||
|
||||
**Solution**: Make sure users who need the model's skills also have read access to each skill (via access grants, group permissions, or by making the skill public).
|
||||
:::
|
||||
|
||||
### Required permissions
|
||||
|
||||
| Permission | What it controls |
|
||||
| :--- | :--- |
|
||||
| **Workspace > Skills Access** | Access the Skills workspace and create/manage skills |
|
||||
| **Sharing > Share Skills** | Share skills with individual users or groups |
|
||||
| **Sharing > Public Skills** | Make skills publicly accessible |
|
||||
|
||||
See [Permissions](/features/authentication-access/rbac/permissions) for configuration details.
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Code review standards
|
||||
|
||||
Write your team's review checklist as a skill: naming conventions, error handling patterns, test coverage requirements. Attach it to your coding models so every review follows the same bar.
|
||||
|
||||
### Writing style guide
|
||||
|
||||
Document tone, formatting rules, and terminology in a skill. Attach it to content-writing models. Every draft follows your brand voice.
|
||||
|
||||
### Troubleshooting playbooks
|
||||
|
||||
Encode your runbook for common issues: "check logs first, verify config, test connectivity, escalate if X." The model follows the same diagnostic steps your senior engineers would.
|
||||
|
||||
### Tool usage instructions
|
||||
|
||||
Pair a skill with Open Terminal to teach the model *how* to use it well. "Always check exit codes. Use `set -e` in scripts. Stream output for commands that take more than 10 seconds."
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
### Plain text only
|
||||
|
||||
Skills are instructions, not executable code. For actions that require computation, API calls, or system access, use [Tools](/features/extensibility/plugin/tools) instead.
|
||||
|
||||
### Context window with $ mention
|
||||
|
||||
When injected via `$` mention, the full skill content goes into the system prompt. A very long skill attached to a model with a small context window may crowd out conversation history.
|
||||
|
||||
### Lazy loading requires function calling
|
||||
|
||||
Model-attached skills depend on the `view_skill` builtin tool, which requires [native function calling](/features/extensibility/plugin/tools#tool-calling-modes-default-vs-native) to be enabled. Without it, the model receives only the manifest and cannot load the full instructions.
|
||||
@@ -0,0 +1,162 @@
|
||||
---
|
||||
sidebar_position: 10
|
||||
title: "Local Development"
|
||||
---
|
||||
|
||||
# Local Development
|
||||
|
||||
**Run Open WebUI from source for development and testing.**
|
||||
|
||||
This guide covers setting up a local development environment with the frontend (SvelteKit) and backend (Python/FastAPI) running side by side. You will need two terminal sessions, one for each.
|
||||
|
||||
:::tip Don't need a full dev environment?
|
||||
You can test the latest changes by running the [dev Docker image](/getting-started/quick-start) instead: `docker run -d -p 3000:8080 -v open-webui-dev:/app/backend/data --name open-webui-dev ghcr.io/open-webui/open-webui:dev`
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Version |
|
||||
|-------------|---------|
|
||||
| **Python** | 3.11+ |
|
||||
| **Node.js** | 22.10+ |
|
||||
| **Git** | Any recent version |
|
||||
|
||||
:::warning Separate your data
|
||||
Never share your database or data directory between dev and production. Dev builds may include database migrations that are not backward-compatible.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 1. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/open-webui/open-webui.git
|
||||
cd open-webui
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Frontend setup
|
||||
|
||||
In your **first terminal**, from the project root:
|
||||
|
||||
```bash
|
||||
cp -RPp .env.example .env
|
||||
npm install
|
||||
npm run build
|
||||
npm run dev
|
||||
```
|
||||
|
||||
`npm run build` compiles the frontend and catches build-time errors early. `npm run dev` then starts the dev server at [http://localhost:5173](http://localhost:5173). It will show a waiting screen until the backend is running.
|
||||
|
||||
:::tip
|
||||
If `npm install` fails with compatibility warnings, run `npm install --force`.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 3. Backend setup
|
||||
|
||||
In your **second terminal**:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
```
|
||||
|
||||
Create and activate a virtual environment (Conda or venv):
|
||||
|
||||
```bash
|
||||
# Option A: Conda
|
||||
conda create --name open-webui python=3.11
|
||||
conda activate open-webui
|
||||
|
||||
# Option B: venv
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
```
|
||||
|
||||
Install dependencies and start the server:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt -U
|
||||
sh dev.sh
|
||||
```
|
||||
|
||||
The backend starts at [http://localhost:8080](http://localhost:8080). API docs are available at [http://localhost:8080/docs](http://localhost:8080/docs).
|
||||
|
||||
Refresh the frontend at [http://localhost:5173](http://localhost:5173) and you should see the full application.
|
||||
|
||||
---
|
||||
|
||||
## Testing from another device
|
||||
|
||||
To access your dev instance from a phone or another computer on the same network:
|
||||
|
||||
1. Find your machine's LAN IP (e.g., `192.168.1.42`)
|
||||
2. Add the origin to CORS in `backend/dev.sh`:
|
||||
|
||||
```bash
|
||||
export CORS_ALLOW_ORIGIN="http://localhost:5173;http://localhost:8080;http://192.168.1.42:5173"
|
||||
```
|
||||
|
||||
3. Restart the backend and browse to `http://192.168.1.42:5173`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "FATAL ERROR: Reached Heap Limit"
|
||||
|
||||
Node.js is running out of memory during the build. Increase the heap size before running frontend commands:
|
||||
|
||||
```bash
|
||||
export NODE_OPTIONS="--max-old-space-size=4096"
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Ensure at least 4 GB of RAM is available.
|
||||
|
||||
### Port conflicts
|
||||
|
||||
If port `5173` or `8080` is already in use, find the conflicting process:
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
lsof -i :5173
|
||||
|
||||
# Windows (PowerShell)
|
||||
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess
|
||||
```
|
||||
|
||||
Terminate the process or change the port in `vite.config.js` (frontend) or `dev.sh` (backend).
|
||||
|
||||
### Icons not loading (CORS)
|
||||
|
||||
If static assets fail to load, configure `CORS_ALLOW_ORIGIN` in `backend/dev.sh` to include your frontend URL. See [CORS configuration](/reference/env-configuration#cors_allow_origin) for details.
|
||||
|
||||
### Hot reload not working
|
||||
|
||||
1. Verify both dev servers are running without errors
|
||||
2. Hard refresh the browser (Ctrl+Shift+R / Cmd+Shift+R)
|
||||
3. Reinstall frontend dependencies: `rm -rf node_modules && npm install`
|
||||
4. Backend changes may require manually restarting `sh dev.sh`
|
||||
|
||||
---
|
||||
|
||||
## Contributing workflow
|
||||
|
||||
1. **Open a discussion first** at [GitHub Discussions](https://github.com/open-webui/open-webui/discussions/new/choose) before writing code
|
||||
2. **Create a branch** from `dev` for your work. Never commit directly to `dev`.
|
||||
|
||||
```bash
|
||||
git checkout dev
|
||||
git pull origin dev
|
||||
git checkout -b my-feature-branch
|
||||
```
|
||||
|
||||
3. **Keep your branch synced** by periodically merging from `dev`
|
||||
4. **Submit a pull request** to the `dev` branch with a clear title and description
|
||||
|
||||
For contribution guidelines, see [Contributing](/contributing).
|
||||
@@ -5,9 +5,32 @@ title: "Advanced Topics"
|
||||
|
||||
# Advanced Topics
|
||||
|
||||
This section covers advanced deployment and operational topics for Open WebUI.
|
||||
**Go beyond the defaults: scale, debug, and develop Open WebUI for production and contribution.**
|
||||
|
||||
## Guides
|
||||
Open WebUI works out of the box for personal use, but real-world deployments need more: production databases, horizontal scaling, structured logging, observability. This section covers everything between "it runs on my laptop" and "it serves my entire organization."
|
||||
|
||||
- **[Scaling Open WebUI](/getting-started/advanced-topics/scaling)** — Scale from a single instance to a production-ready multi-replica deployment with PostgreSQL, Redis, shared storage, and observability.
|
||||
- **[Logging Configuration](/getting-started/advanced-topics/logging)** — Configure log levels, debug output, and structured JSON logging for production environments.
|
||||
---
|
||||
|
||||
## Why Advanced Topics?
|
||||
|
||||
### Scale beyond a single container
|
||||
|
||||
The default SQLite database and single-worker setup top out at small-team usage. Learn how to swap in PostgreSQL, add Redis for shared state, run multiple replicas behind a load balancer, and choose an external vector database, all without re-architecting your deployment.
|
||||
|
||||
### Debug with confidence
|
||||
|
||||
When something goes wrong at scale, the first question is always "what do the logs say?" Configure log levels, enable structured JSON output for log aggregators, and connect OpenTelemetry for end-to-end traces across your entire stack.
|
||||
|
||||
### Contribute to the project
|
||||
|
||||
Set up a local development environment with hot-reloading frontend and backend, understand the contribution workflow, and start shipping pull requests.
|
||||
|
||||
---
|
||||
|
||||
## What's Covered
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🚀 **[Scaling Open WebUI](scaling)** | Move from SQLite to PostgreSQL, add Redis, run multiple replicas, configure external vector databases, and set up shared storage and observability |
|
||||
| 🪵 **[Logging Configuration](logging)** | Configure log levels, enable debug output, and switch to structured JSON logging for production log aggregators |
|
||||
| 🛠️ **[Local Development](development)** | Clone the repo, run the frontend and backend side by side, test on other devices, and submit pull requests |
|
||||
|
||||
@@ -1,113 +1,88 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
title: "Logging in Open WebUI"
|
||||
title: "Logging Configuration"
|
||||
---
|
||||
|
||||
# Understanding Open WebUI Logging 🪵
|
||||
# Logging Configuration
|
||||
|
||||
Logging is essential for debugging, monitoring, and understanding how Open WebUI is behaving. This guide explains how logging works in both the **browser client** (frontend) and the **application server/backend**.
|
||||
**Control what Open WebUI logs, where it goes, and how it's formatted, from quick debugging to production log pipelines.**
|
||||
|
||||
## 🖥️ Browser Client Logging (Frontend)
|
||||
Open WebUI has two logging surfaces: the **browser console** for frontend debugging and the **Python backend** for server-side events. Most configuration happens on the backend, where you can adjust verbosity with a single environment variable or switch to structured JSON output for log aggregators like Loki, Datadog, or CloudWatch.
|
||||
|
||||
For frontend development and debugging, Open WebUI utilizes standard browser console logging. This means you can see logs directly within your web browser's built-in developer tools.
|
||||
---
|
||||
|
||||
**How to Access Browser Logs:**
|
||||
## Frontend Logging
|
||||
|
||||
1. **Open Developer Tools:** In most browsers, you can open developer tools by:
|
||||
- **Right-clicking** anywhere on the Open WebUI page and selecting "Inspect" or "Inspect Element".
|
||||
- Pressing **F12** (or Cmd+Opt+I on macOS).
|
||||
The frontend uses standard browser `console.log()` calls. Open your browser's developer tools (**F12** or **Cmd+Option+I** on macOS), navigate to the **Console** tab, and you'll see informational messages, warnings, and errors from the client application.
|
||||
|
||||
2. **Navigate to the "Console" Tab:** Within the developer tools panel, find and click on the "Console" tab.
|
||||
Browser-specific documentation:
|
||||
|
||||
**Types of Browser Logs:**
|
||||
- [Chrome/Chromium DevTools](https://developer.chrome.com/docs/devtools/)
|
||||
- [Firefox Developer Tools](https://firefox-source-docs.mozilla.org/devtools-user/)
|
||||
- [Safari Developer Tools](https://developer.apple.com/safari/tools/)
|
||||
|
||||
Open WebUI primarily uses [JavaScript's](https://developer.mozilla.org/en-US/docs/Web/API/console/log_static) `console.log()` for client-side logging. You'll see various types of messages in the console, including:
|
||||
---
|
||||
|
||||
- **Informational messages:** General application flow and status.
|
||||
- **Warnings:** Potential issues or non-critical errors.
|
||||
- **Errors:** Problems that might be affecting functionality.
|
||||
## Backend Logging
|
||||
|
||||
**Browser-Specific Developer Tools:**
|
||||
The backend uses Python's built-in `logging` module. By default, logs are written to **stdout** at the `INFO` level, making them visible in your terminal or container logs.
|
||||
|
||||
Different browsers offer slightly different developer tools, but they all provide a console for viewing JavaScript logs. Here are links to documentation for popular browsers:
|
||||
### Log Levels
|
||||
|
||||
- **[Blink] Chrome/Chromium (e.g., Chrome, Edge):** [Chrome DevTools Documentation](https://developer.chrome.com/docs/devtools/)
|
||||
- **[Gecko] Firefox:** [Firefox Developer Tools Documentation](https://firefox-source-docs.mozilla.org/devtools-user/)
|
||||
- **[WebKit] Safari:** [Safari Developer Tools Documentation](https://developer.apple.com/safari/tools/)
|
||||
| Level | Value | When to use |
|
||||
|---|---|---|
|
||||
| `CRITICAL` | 50 | Catastrophic failures; the application may terminate |
|
||||
| `ERROR` | 40 | Failed operations; the application continues but something broke |
|
||||
| `WARNING` | 30 | Unexpected situations worth investigating: deprecations, resource pressure |
|
||||
| `INFO` | 20 | Normal operation flow: startup, key events, request handling **(default)** |
|
||||
| `DEBUG` | 10 | Detailed diagnostic output: function calls, variable values, execution steps |
|
||||
|
||||
## ⚙️ Application Server/Backend Logging (Python)
|
||||
---
|
||||
|
||||
The backend of Open WebUI uses Python's built-in `logging` module to record events and information on the server side. These logs are crucial for understanding server behavior, diagnosing errors, and monitoring performance.
|
||||
### Setting the Global Log Level
|
||||
|
||||
**Key Concepts:**
|
||||
Set `GLOBAL_LOG_LEVEL` to change verbosity for the entire backend. This configures the root Python logger via `logging.basicConfig(force=True)`, affecting all Open WebUI loggers and most third-party libraries.
|
||||
|
||||
- **Python `logging` Module:** Open WebUI leverages the standard Python `logging` library. If you're familiar with Python logging, you'll find this section straightforward. (For more in-depth information, see the [Python Logging Documentation](https://docs.python.org/3/howto/logging.html#logging-levels)).
|
||||
- **Console Output:** By default, backend logs are sent to the console (standard output), making them visible in your terminal or Docker container logs.
|
||||
- **Logging Levels:** Logging levels control the verbosity of the logs. You can configure Open WebUI to show more or less detailed information based on these levels.
|
||||
**Docker:**
|
||||
|
||||
### 🚦 Logging Levels Explained
|
||||
```bash
|
||||
--env GLOBAL_LOG_LEVEL="DEBUG"
|
||||
```
|
||||
|
||||
Python logging uses a hierarchy of levels to categorize log messages by severity. Here's a breakdown of the levels, from most to least severe:
|
||||
**Docker Compose:**
|
||||
|
||||
| Level | Numeric Value | Description | Use Case |
|
||||
| ----------- | ------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `CRITICAL` | 50 | **Severe errors** that may lead to application termination. | Catastrophic failures, data corruption. |
|
||||
| `ERROR` | 40 | **Errors** that indicate problems but the application might still function. | Recoverable errors, failed operations. |
|
||||
| `WARNING` | 30 | **Potential issues** or unexpected situations that should be investigated. | Deprecation warnings, resource constraints. |
|
||||
| `INFO` | 20 | **General informational messages** about application operation. | Startup messages, key events, normal operation flow. |
|
||||
| `DEBUG` | 10 | **Detailed debugging information** for developers. | Function calls, variable values, detailed execution steps. |
|
||||
| `NOTSET` | 0 | **All messages are logged.** (Usually defaults to `WARNING` if not set). | Useful for capturing absolutely everything, typically for very specific debugging. |
|
||||
```yaml
|
||||
environment:
|
||||
- GLOBAL_LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
**Default Level:** Open WebUI's default logging level is `INFO`.
|
||||
:::tip
|
||||
Use `DEBUG` for development and troubleshooting. For production, stick with `INFO` or `WARNING` to keep log volume manageable.
|
||||
:::
|
||||
|
||||
### 🌍 Global Logging Level (`GLOBAL_LOG_LEVEL`)
|
||||
---
|
||||
|
||||
You can change the **global** logging level for the entire Open WebUI backend using the `GLOBAL_LOG_LEVEL` environment variable. This is the most straightforward way to control overall logging verbosity.
|
||||
### Structured JSON Logging
|
||||
|
||||
**How it Works:**
|
||||
For production environments using log aggregators, set `LOG_FORMAT=json` to switch all stdout output to single-line JSON objects.
|
||||
|
||||
Setting `GLOBAL_LOG_LEVEL` configures the root logger in Python, affecting all loggers in Open WebUI and potentially some third-party libraries that use [basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig). It uses `logging.basicConfig(force=True)`, which means it will override any existing root logger configuration.
|
||||
**Docker:**
|
||||
|
||||
**Example: Setting to `DEBUG`**
|
||||
```bash
|
||||
--env LOG_FORMAT="json"
|
||||
```
|
||||
|
||||
- **Docker Parameter:**
|
||||
**Docker Compose:**
|
||||
|
||||
```bash
|
||||
--env GLOBAL_LOG_LEVEL="DEBUG"
|
||||
```
|
||||
```yaml
|
||||
environment:
|
||||
- LOG_FORMAT=json
|
||||
```
|
||||
|
||||
- **Docker Compose (`docker-compose.yml`):**
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- GLOBAL_LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
**Impact:** Setting `GLOBAL_LOG_LEVEL` to `DEBUG` will produce the most verbose logs, including detailed information that is helpful for development and troubleshooting. For production environments, `INFO` or `WARNING` might be more appropriate to reduce log volume.
|
||||
|
||||
### 📋 JSON Logging (`LOG_FORMAT`)
|
||||
|
||||
For production environments using log aggregators (Loki, Fluentd, CloudWatch, Datadog, etc.), Open WebUI supports structured JSON logging. Set the `LOG_FORMAT` environment variable to `json` to switch all stdout logging to single-line JSON objects.
|
||||
|
||||
**How to Enable:**
|
||||
|
||||
- **Docker Parameter:**
|
||||
|
||||
```bash
|
||||
--env LOG_FORMAT="json"
|
||||
```
|
||||
|
||||
- **Docker Compose (`docker-compose.yml`):**
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- LOG_FORMAT=json
|
||||
```
|
||||
|
||||
**JSON Log Fields:**
|
||||
**JSON fields:**
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
|---|---|
|
||||
| `ts` | ISO 8601 timestamp |
|
||||
| `level` | Log level (`debug`, `info`, `warn`, `error`, `fatal`) |
|
||||
| `msg` | Log message |
|
||||
@@ -116,18 +91,15 @@ For production environments using log aggregators (Loki, Fluentd, CloudWatch, Da
|
||||
| `error` | Error details (if applicable) |
|
||||
| `stacktrace` | Stack trace (if applicable) |
|
||||
|
||||
**Example Output:**
|
||||
**Example output:**
|
||||
|
||||
```json
|
||||
{"ts": "2026-02-22T20:14:53.386+00:00", "level": "info", "msg": "GLOBAL_LOG_LEVEL: INFO", "caller": "open_webui.env"}
|
||||
{"ts": "2026-02-22T20:15:02.245+00:00", "level": "info", "msg": "Context impl SQLiteImpl.", "caller": "alembic.runtime.migration"}
|
||||
```
|
||||
|
||||
:::info
|
||||
- Default behavior (no `LOG_FORMAT` set) is unchanged — plain-text output
|
||||
:::note
|
||||
- Default behavior (no `LOG_FORMAT` set) is unchanged: plain-text output
|
||||
- The ASCII banner is suppressed when `LOG_FORMAT=json` to keep the log stream parseable
|
||||
- JSON logging covers both early startup logs (stdlib `logging`) and runtime logs (Loguru)
|
||||
:::
|
||||
|
||||
|
||||
By understanding and utilizing these logging mechanisms, you can effectively monitor, debug, and gain insights into your Open WebUI instance.
|
||||
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 30
|
||||
sidebar_position: 50
|
||||
title: "Redis Websocket Support"
|
||||
---
|
||||
|
||||
@@ -78,7 +78,7 @@ ENABLE_WEBSOCKET_SUPPORT=true
|
||||
- A **single Redis instance** is sufficient for the vast majority of deployments, even with thousands of users. You almost certainly do not need Redis Cluster unless you have specific HA/bandwidth requirements. If you think you need Redis Cluster, first check whether your connection count and memory usage are caused by fixable configuration issues (see [Common Anti-Patterns](/troubleshooting/performance#%EF%B8%8F-common-anti-patterns)).
|
||||
- Without Redis in a multi-instance setup, you will experience [WebSocket 403 errors](/troubleshooting/multi-replica#2-websocket-403-errors--connection-failures), [configuration sync issues](/troubleshooting/multi-replica#3-model-not-found-or-configuration-mismatch), and intermittent authentication failures.
|
||||
|
||||
For a complete step-by-step Redis setup (Docker Compose, Sentinel, Cluster mode, verification), see the [Redis WebSocket Support](/tutorials/integrations/redis) tutorial. For WebSocket and CORS issues behind reverse proxies, see [Connection Errors](/troubleshooting/connection-error#-https-tls-cors--websocket-issues).
|
||||
For a complete step-by-step Redis setup (Docker Compose, Sentinel, Cluster mode, verification), see the [Redis WebSocket Support](/getting-started/advanced-topics/redis) tutorial. For WebSocket and CORS issues behind reverse proxies, see [Connection Errors](/troubleshooting/connection-error#-https-tls-cors--websocket-issues).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,386 +0,0 @@
|
||||
---
|
||||
sidebar_position: 998
|
||||
title: "Local Development Guide"
|
||||
---
|
||||
|
||||
# Ready to Contribute to Open WebUI? Let's Get Started! 🚀
|
||||
|
||||
Excited to dive into Open WebUI development? This comprehensive guide will walk you through setting up your **local development environment** quickly and easily. Whether you're a seasoned developer or just starting out, we'll get you ready to tweak the frontend, enhance the backend, and contribute to the future of Open WebUI! Let's get your development environment up and running in simple, detailed steps!
|
||||
|
||||
:::tip Help Us Build Better Software!
|
||||
|
||||
**Running the development setup is one of the most valuable ways to contribute.** You don't need to write code—just using and testing the latest changes helps us catch bugs before stable releases. Community testing makes a real difference in the quality of every release.
|
||||
|
||||
**Prefer Docker?** If setting up a local dev environment seems like too much, you can also test by running the [dev Docker image](/#using-the-dev-branch-) — it's the same code, just containerized.
|
||||
|
||||
**Keep your setup updated regularly** — run `git pull origin dev` frequently to stay current with the latest changes.
|
||||
|
||||
:::
|
||||
|
||||
:::warning Do Not Share Data with Production
|
||||
|
||||
**Never share your database or data directory between dev and production setups.** Dev builds may include database migrations that are not backward-compatible. If a dev migration runs on your production data and you later need to roll back, your production setup may break.
|
||||
|
||||
Keep your development data completely separate from production.
|
||||
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure your system meets these minimum requirements:
|
||||
|
||||
- **Operating System:** Linux (or WSL on Windows), Windows 11, or macOS. *(Recommended for best compatibility)*
|
||||
- **Python:** Version **3.11 or higher**. *(Required for backend services)*
|
||||
- **Node.js:** Version **22.10 or higher**. *(Required for frontend development)*
|
||||
- **IDE (Recommended):** We recommend using an IDE like [VS Code](https://code.visualstudio.com/) for code editing, debugging, and integrated terminal access. Feel free to use your favorite IDE if you have one!
|
||||
- **[Optional] GitHub Desktop:** For easier management of the Git repository, especially if you are less familiar with command-line Git, consider installing [GitHub Desktop](https://desktop.github.com/).
|
||||
|
||||
## Setting Up Your Local Environment
|
||||
|
||||
We'll set up both the frontend (user interface) and backend (API and server logic) of Open WebUI.
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
First, use `git clone` to download the Open WebUI repository to your local machine. This will create a local copy of the project on your computer.
|
||||
|
||||
1. **Open your terminal** (or Git Bash if you're on Windows and using Git Bash).
|
||||
2. **Navigate to the directory** where you want to store the Open WebUI project.
|
||||
3. **Clone the repository:** Run the following command:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/open-webui/open-webui.git
|
||||
cd open-webui
|
||||
```
|
||||
|
||||
The `git clone` command downloads the project files from GitHub. The `cd open-webui` command then navigates you into the newly created project directory.
|
||||
|
||||
### 2. Frontend Setup (User Interface)
|
||||
|
||||
Let's get the user interface (what you see in your browser) up and running first:
|
||||
|
||||
1. **Configure Environment Variables:**
|
||||
- Copy the example environment file to `.env`:
|
||||
|
||||
```bash
|
||||
cp -RPp .env.example .env
|
||||
```
|
||||
|
||||
This command copies the `.env.example` file to a new file named `.env`. The `.env` file is where you'll configure environment variables for the frontend.
|
||||
|
||||
- **Customize `.env`**: Open the `.env` file in your code editor (like VS Code). This file contains configuration variables for the frontend, such as API endpoints and other settings. For local development, the default settings in `.env.example` are usually sufficient to start with. However, you can customize them if needed.
|
||||
|
||||
**Important:** Do not commit sensitive information to `.env` if you are contributing back to the repository.
|
||||
|
||||
1. **Install Frontend Dependencies:**
|
||||
- **Navigate to the frontend directory:** If you're not already in the project root (`open-webui` directory), ensure you are there.
|
||||
|
||||
```bash
|
||||
# If you are not in the project root, run:
|
||||
cd open-webui
|
||||
```
|
||||
|
||||
- Install the required JavaScript packages:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
This will install all frontend dependencies listed in `package.json`.
|
||||
|
||||
*Note: Depending on your Open WebUI version, you might see compatibility warnings or errors. If so, just run:*
|
||||
|
||||
```bash
|
||||
npm install --force
|
||||
```
|
||||
|
||||
*Some setups need this to get around version issues.*
|
||||
|
||||
2. **Start the Frontend Development Server:**
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
This command launches the frontend development server. If the steps were followed successfully, it will usually indicate the server is running and provide a local URL.
|
||||
|
||||
🎉 **Access the Frontend:** Open your web browser and go to [http://localhost:5173](http://localhost:5173). You should see a message indicating that Open WebUI's frontend is running and is waiting for the backend to be available. Don't worry about that message yet! Let's set up the backend next. **Keep this terminal running** – it's serving your frontend!
|
||||
|
||||
### 2.5: Build the Frontend (Recommended)
|
||||
|
||||
Once you’ve verified that the frontend development server (`npm run dev`) is running correctly and you can see Open WebUI at [http://localhost:5173](http://localhost:5173), it's a **good practice to also build the frontend assets**. This step simulates the production environment and can help catch build-time errors that don't show up during development.
|
||||
|
||||
**In the same frontend terminal:**
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
- This command generates an optimized, production-ready build of the frontend and places the static files in the `build` directory.
|
||||
- If the build completes successfully (without errors), you're ready! If there are errors, address them before proceeding.
|
||||
- You don't need to do anything more with `build` for local development, but building ensures your code will not break in production or during deployment.
|
||||
|
||||
### 3. Backend Setup (API and Server)
|
||||
|
||||
We **require** you to use separate terminal instances for your frontend and backend processes. This keeps your workflows organized and makes it easier to manage each part of the application independently.
|
||||
|
||||
**Using VS Code Integrated Terminals:**
|
||||
|
||||
VS Code's integrated terminal feature makes managing multiple terminals incredibly easy. Here's how to leverage it for frontend and backend separation:
|
||||
|
||||
1. **Frontend Terminal (You likely already have this):** If you followed the Frontend Setup steps, you probably already have a terminal open in VS Code at the project root (`open-webui` directory). This is where you'll run your frontend commands (`npm run dev`, etc.). Ensure you are in the `open-webui` directory for the next steps if you are not already.
|
||||
|
||||
2. **Backend Terminal (Open a New One):**
|
||||
- In VS Code, go to **Terminal > New Terminal** (or use the shortcut `` Ctrl+Shift+` `` on Windows/Linux or `` Cmd+Shift+` `` on macOS). This will open a new integrated terminal panel.
|
||||
- **Navigate to the `backend` directory:** In this *new* terminal, use the `cd backend` command to change the directory to the `backend` folder within your project. This ensures all backend-related commands are executed in the correct context.
|
||||
|
||||
Now you have **two separate terminal instances within VS Code**: one for the frontend (likely in the `open-webui` directory) and one specifically for the backend (inside the `backend` directory). You can easily switch between these terminals within VS Code to manage your frontend and backend processes independently. This setup is highly recommended for a cleaner and more efficient development workflow.
|
||||
|
||||
**Backend Setup Steps (in your *backend* terminal):**
|
||||
|
||||
1. **Navigate to the Backend Directory:** (You should already be in the `backend` directory in your *new* terminal from the previous step). If not, run:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
```
|
||||
|
||||
2. **Create and Activate a Conda Environment (Recommended):**
|
||||
- We highly recommend using Conda to manage Python dependencies and isolate your project environment. This prevents conflicts with other Python projects on your system and ensures you have the correct Python version and libraries.
|
||||
|
||||
```bash
|
||||
conda create --name open-webui python=3.11
|
||||
conda activate open-webui
|
||||
```
|
||||
|
||||
- `conda create --name open-webui python=3.11`: This command creates a new Conda environment named `open-webui` using Python version 3.11. If you chose a different Python 3.11.x version, that's fine.
|
||||
- `conda activate open-webui`: This command activates the newly created Conda environment. Once activated, your terminal prompt will usually change to indicate you are in the `open-webui` environment (e.g., it might show `(open-webui)` at the beginning of the line).
|
||||
|
||||
**Make sure you activate the environment in your backend terminal before proceeding.**
|
||||
|
||||
*(Using Conda is optional but strongly recommended for managing Python dependencies and avoiding conflicts.)* If you choose not to use Conda, ensure you are using Python 3.11 or higher and proceed to the next step, but be aware of potential dependency conflicts.
|
||||
|
||||
2. **Alternative: Create and Activate a Python venv:**
|
||||
|
||||
If you prefer using Python's built-in `venv` module instead of Conda, follow these steps:
|
||||
|
||||
- **Create the virtual environment:**
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
```
|
||||
- **Activate the virtual environment:**
|
||||
- **Linux/macOS:**
|
||||
```bash
|
||||
source venv/bin/activate
|
||||
```
|
||||
- **Windows:**
|
||||
```powershell
|
||||
.\venv\Scripts\activate
|
||||
```
|
||||
|
||||
Once activated, your terminal prompt should show `(venv)`. You can now proceed to install dependencies.
|
||||
|
||||
1. **Install Backend Dependencies:**
|
||||
- In your *backend* terminal (and with the Conda environment activated if you are using Conda), run:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt -U
|
||||
```
|
||||
|
||||
This command uses `pip` (Python Package Installer) to read the `requirements.txt` file in the `backend` directory. `requirements.txt` lists all the Python libraries that the backend needs to run. `pip install` downloads and installs these libraries into your active Python environment (your Conda environment if you are using it, or your system-wide Python environment otherwise). The `-U` flag ensures you get the latest compatible versions of the libraries.
|
||||
|
||||
As of v0.8.10, **MariaDB** is a dependency, which requires you to install **MariaDB Connector/C** on your system.
|
||||
To do so, you can follow these steps:
|
||||
- Debian
|
||||
```bash
|
||||
apt install libmariadb3 libmariadb-dev
|
||||
```
|
||||
- Fedora
|
||||
```bash
|
||||
dnf install mariadb-connector-c mariadb-connector-c-devel
|
||||
```
|
||||
- Arch
|
||||
```bash
|
||||
pacman -S mariadb-libs
|
||||
```
|
||||
- macOS
|
||||
```bash
|
||||
brew install mariadb-connector-c
|
||||
```
|
||||
*You might also need to set the environment variable MARIADB_CONFIG or update your PATH as suggested by brew after installation*
|
||||
- Windows
|
||||
- Download and run the MSI installer from [https://mariadb.com/downloads/connectors/](https://mariadb.com/downloads/connectors/)
|
||||
|
||||
3. **Start the Backend Development Server:**
|
||||
- In your *backend* terminal, run:
|
||||
|
||||
```bash
|
||||
sh dev.sh
|
||||
```
|
||||
|
||||
This command executes the `dev.sh` script. This script likely contains the command to start the backend development server. *(You can open and examine the `dev.sh` file in your code editor to see the exact command being run if you are curious.)* The backend server will usually start and print some output to the terminal.
|
||||
|
||||
📄 **Explore the API Documentation:** Once the backend is running, you can access the automatically generated API documentation in your web browser at [http://localhost:8080/docs](http://localhost:8080/docs). This documentation is incredibly valuable for understanding the backend API endpoints, how to interact with the backend, and what data it expects and returns. Keep this documentation handy as you develop!
|
||||
|
||||
🎉 **Congratulations!** If you have followed all the steps, you should now have both the frontend and backend development servers running locally. Go back to your browser tab where you accessed the frontend (usually [http://localhost:5173](http://localhost:5173)). **Refresh the page.** You should now see the full Open WebUI application running in your browser, connected to your local backend!
|
||||
|
||||
## Testing From Another Device (Phone, Tablet, etc.)
|
||||
|
||||
Want to open your dev instance from your phone or another computer on the same Wi-Fi?
|
||||
|
||||
1. Find your dev-machine’s LAN IP, e.g. `192.168.1.42`.
|
||||
2. **Frontend only (quick check):**
|
||||
- Keep the backend on `localhost`.
|
||||
- From your phone browse to `http://192.168.1.42:5173`.
|
||||
3. **Full stack (frontend + backend):**
|
||||
- In `backend/dev.sh` **add your LAN address to the CORS list**, e.g.
|
||||
|
||||
```bash
|
||||
export CORS_ALLOW_ORIGIN="http://localhost:5173;http://localhost:8080;http://192.168.1.42:5173"
|
||||
```
|
||||
|
||||
- Restart the backend (`sh dev.sh`).
|
||||
- From your phone browse to `http://192.168.1.42:5173`.
|
||||
- All API calls will now be allowed from that origin.
|
||||
|
||||
> **Security note:** The wildcard `"*"` works too, but do **not** ship that to production.
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
Here are solutions to some common problems you might encounter during setup or development:
|
||||
|
||||
### 💥 "FATAL ERROR: Reached Heap Limit" (Frontend)
|
||||
|
||||
This error, often seen during frontend development, indicates that Node.js is running out of memory during the build process, especially when working with large frontend applications.
|
||||
|
||||
**Solution:** Increase the Node.js heap size. This gives Node.js more memory to work with. You have a couple of options:
|
||||
|
||||
1. **Using `NODE_OPTIONS` Environment Variable (Recommended for Development):**
|
||||
- This is a temporary way to increase the memory limit for the current terminal session. Before running `npm run dev` or `npm run build` in your *frontend* terminal, set the `NODE_OPTIONS` environment variable:
|
||||
|
||||
```bash
|
||||
export NODE_OPTIONS="--max-old-space-size=4096" # For Linux/macOS (bash, zsh)
|
||||
# set NODE_OPTIONS=--max-old-space-size=4096 # For Windows (Command Prompt)
|
||||
# $env:NODE_OPTIONS="--max-old-space-size=4096" # For Windows (PowerShell)
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Choose the command appropriate for your operating system and terminal. `4096` represents 4GB of memory. You can try increasing this value further if needed (e.g., `8192` for 8GB). This setting will only apply to commands run in the current terminal session.
|
||||
|
||||
2. **Modifying `Dockerfile` (For Dockerized Environments):**
|
||||
- If you are working with Docker, you can permanently set the `NODE_OPTIONS` environment variable within your `Dockerfile`. This is useful for consistent memory allocation in Dockerized environments, as shown in the original guide example:
|
||||
|
||||
```dockerfile
|
||||
ENV NODE_OPTIONS=--max-old-space-size=4096
|
||||
```
|
||||
|
||||
- **Allocate Sufficient RAM:** Regardless of the method, ensure your system or Docker container has enough RAM available for Node.js to use. **At least 4 GB of RAM is recommended**, and more might be needed for larger projects or complex builds. Close unnecessary applications to free up RAM.
|
||||
|
||||
### ⚠️ Port Conflicts (Frontend & Backend)
|
||||
|
||||
If you see errors related to ports, such as "Address already in use" or "Port already bound," it means another application on your system is already using port `5173` (default for frontend) or `8080` (default for backend). Only one application can use a specific port at a time.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Identify the Conflicting Process:** You need to find out which application is using the port you need.
|
||||
- **Linux/macOS:** Open a new terminal and use the `lsof` or `netstat` commands:
|
||||
- `lsof -i :5173` (or `:8080` for the backend port)
|
||||
- `netstat -tulnp | grep 5173` (or `8080`)
|
||||
These commands will list the process ID (PID) and the name of the process using the specified port.
|
||||
- **Windows:** Open Command Prompt or PowerShell as an administrator and use `netstat` or `Get-NetTCPConnection`:
|
||||
- `netstat -ano | findstr :5173` (or `:8080`) (Command Prompt)
|
||||
- `Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess` (PowerShell)
|
||||
These commands will also show the PID of the process using the port.
|
||||
|
||||
2. **Terminate the Conflicting Process:** Once you identify the process ID (PID), you can stop the application using that port. **Be careful when terminating processes, especially if you are unsure what they are.**
|
||||
- **Linux/macOS:** Use the `kill` command: `kill <PID>` (replace `<PID>` with the actual process ID). If the process doesn't terminate with `kill`, you can use `kill -9 <PID>` (force kill), but use this with caution.
|
||||
- **Windows:** Use the `taskkill` command in Command Prompt or PowerShell as administrator: `taskkill /PID <PID> /F` (replace `<PID>` with the process ID). The `/F` flag forces termination.
|
||||
|
||||
3. **Alternatively, Change Ports (Advanced):**
|
||||
- If you cannot terminate the conflicting process (e.g., it's a system service you need), you can configure Open WebUI to use different ports for the frontend and/or backend. This usually involves modifying configuration files.
|
||||
- **Frontend Port:** Check the frontend documentation or configuration files (often in `vite.config.js` or similar) for how to change the development server port. You might need to adjust the `.env` file as well if the frontend uses environment variables for the port.
|
||||
- **Backend Port:** Examine the `dev.sh` script or backend configuration files to see how the backend port is set. You might need to modify the startup command or a configuration file to change the backend port. If you change the backend port, you'll likely need to update the frontend's `.env` file to point to the new backend URL.
|
||||
|
||||
### 🔄 Hot Reload Not Working
|
||||
|
||||
Hot reload (or hot module replacement - HMR) is a fantastic development feature that automatically refreshes your browser when you make changes to the code. If it's not working, it can significantly slow down your development workflow.
|
||||
|
||||
**Troubleshooting Steps:**
|
||||
|
||||
1. **Verify Development Servers are Running:** Double-check that both `npm run dev` (frontend) and `sh dev.sh` (backend) are running in their respective terminals and haven't encountered any errors. Look for messages in the terminal output indicating they are running and in "watch mode" or "development mode." If there are errors, address them first.
|
||||
2. **Check for Watch Mode/HMR Messages:** When the development servers start, they should usually print messages in the terminal indicating that hot reload or watch mode is enabled. Look for phrases like "HMR enabled," "watching for file changes," or similar. If you don't see these messages, there might be a configuration issue.
|
||||
3. **Browser Cache:** Sometimes, your browser's cache can prevent you from seeing the latest changes, even if hot reload is working. Try a **hard refresh** in your browser:
|
||||
- **Windows/Linux:** Ctrl+Shift+R
|
||||
- **macOS:** Cmd+Shift+R
|
||||
- Alternatively, you can try clearing your browser cache or opening the frontend in a private/incognito browser window.
|
||||
4. **Dependency Issues (Frontend):** Outdated or corrupted frontend dependencies can sometimes interfere with hot reloading. Try refreshing your frontend dependencies:
|
||||
- In your *frontend* terminal, run:
|
||||
|
||||
```bash
|
||||
rm -rf node_modules && npm install
|
||||
```
|
||||
|
||||
If `npm install` fails, try `npm install --force`.
|
||||
|
||||
|
||||
This command deletes the `node_modules` directory (where dependencies are stored) and then reinstalls them from scratch. This can resolve issues caused by corrupted or outdated packages.
|
||||
5. **Backend Restart Required (For Backend Changes):** Hot reload typically works best for frontend code changes (UI, styling, components). For significant backend code changes (especially changes to server logic, API endpoints, or dependencies), you might need to **manually restart the backend server** (by stopping `sh dev.sh` in your backend terminal and running it again). Hot reload for backend changes is often less reliable or not automatically configured in many backend development setups.
|
||||
6. **IDE/Editor Issues:** In rare cases, issues with your IDE or code editor might prevent file changes from being properly detected by the development servers. Try restarting your IDE or ensuring that files are being saved correctly.
|
||||
7. **Configuration Problems (Advanced):** If none of the above steps work, there might be a more complex configuration issue with the frontend or backend development server setup. Consult the project's documentation, configuration files (e.g., `vite.config.js` for frontend, backend server configuration files), or seek help from the Open WebUI community or maintainers.
|
||||
|
||||
### 🖼️ Icons Not Loading? (CORS Issues)
|
||||
|
||||
If you find that **icons or other static assets are failing to load**, it is often due to **Cross-Origin Resource Sharing (CORS)** restrictions. This happens when the frontend (running on one port, e.g., `5173`) tries to request resources from the backend (running on another port, e.g., `8080`) without explicit permission.
|
||||
|
||||
**Solution:**
|
||||
You need to configure the `CORS_ALLOW_ORIGIN` environment variable in your backend.
|
||||
- Check the [Environment Configuration](/reference/env-configuration#cors_allow_origin) guide for details on how to set `CORS_ALLOW_ORIGIN` to allow requests from your frontend's URL (e.g., `http://localhost:5173`).
|
||||
- In a development environment, you can often set this in your `backend/dev.sh` script or your `.env` file.
|
||||
|
||||
## Contributing to Open WebUI
|
||||
|
||||
We warmly welcome your contributions to Open WebUI! Your help is valuable in making this project even better. Here's a quick guide for a smooth and effective contribution workflow:
|
||||
|
||||
1. **Understand the Project Structure:** Take some time to familiarize yourself with the project's directory structure, especially the `frontend` and `backend` folders. Look at the code, configuration files, and documentation to get a sense of how things are organized.
|
||||
2. **Start with Small Contributions:** If you are new to the project, consider starting with smaller contributions like:
|
||||
- **Documentation improvements:** Fix typos, clarify explanations, add more details to the documentation.
|
||||
- **Bug fixes:** Address reported bugs or issues.
|
||||
- **Small UI enhancements:** Improve styling, fix minor layout issues.
|
||||
These smaller contributions are a great way to get familiar with the codebase and the contribution process.
|
||||
3. **Discuss Larger Changes First:** If you are planning to implement a significant new feature or make substantial changes, it's highly recommended to **discuss your ideas with the project maintainers or community first.** You can do this by:
|
||||
- **Opening an issue** on the GitHub repository to propose your feature or change.
|
||||
- **Joining the Open WebUI community channels** (if available, check the project's README or website for links) and discussing your ideas there.
|
||||
This helps ensure that your contribution aligns with the project's goals and avoids wasted effort on features that might not be merged.
|
||||
4. **Create a Separate Branch for Your Work:** **Never commit directly to the `dev` branch.** Always create a new branch for each feature or bug fix you are working on. This keeps your changes isolated and makes it easier to manage and submit pull requests.
|
||||
- To create a new branch (e.g., named `my-feature-branch`) based on the `dev` branch:
|
||||
|
||||
```bash
|
||||
git checkout dev
|
||||
git pull origin dev # Ensure your local dev branch is up-to-date
|
||||
git checkout -b my-feature-branch
|
||||
```
|
||||
|
||||
5. **Commit Changes Frequently and Write Clear Commit Messages:** Make small, logical commits as you develop features or fix bugs. **Write clear and concise commit messages** that explain what changes you made and why. Good commit messages make it easier to understand the history of changes and are essential for collaboration.
|
||||
- Example of a good commit message: `Fix: Corrected typo in documentation for backend setup`
|
||||
- Example of a good commit message: `Feat: Implemented user profile page with basic information display`
|
||||
6. **Stay Synced with the `dev` Branch Regularly:** While working on your branch, periodically sync your branch with the latest changes from the `dev` branch to minimize merge conflicts later:
|
||||
|
||||
```bash
|
||||
git checkout dev
|
||||
git pull origin dev
|
||||
git checkout my-feature-branch
|
||||
git merge dev
|
||||
```
|
||||
|
||||
Resolve any merge conflicts that arise during the `git merge` step.
|
||||
7. **Run Tests (If Available) Before Pushing:** While this guide doesn't detail specific testing procedures for Open WebUI, it's a good practice to run any available tests before pushing your code. Check the project's documentation or `package.json` (for frontend) and backend files for test-related commands (e.g., `npm run test`, `pytest`, etc.). Running tests helps ensure your changes haven't introduced regressions or broken existing functionality.
|
||||
8. **Submit a Pull Request (PR):** Once you have completed your work, tested it (if applicable), and are ready to contribute your changes, submit a pull request (PR) to the `dev` branch of the Open WebUI repository on GitHub.
|
||||
- **Go to the Open WebUI repository on GitHub.**
|
||||
- **Navigate to your branch.**
|
||||
- **Click the "Contribute" or "Pull Request" button** (usually green).
|
||||
- **Fill out the PR form:**
|
||||
- **Title:** Give your PR a clear and descriptive title that summarizes your changes (e.g., "Fix: Resolved issue with login form validation").
|
||||
- **Description:** Provide a more detailed description of your changes, the problem you are solving (if applicable), and any relevant context. Link to any related issues if there are any.
|
||||
- **Submit the PR.**
|
||||
|
||||
Project maintainers will review your pull request, provide feedback, and potentially merge your changes. Be responsive to feedback and be prepared to make revisions if requested.
|
||||
|
||||
**Thank you for reading this comprehensive guide and for your interest in contributing to Open WebUI! We're excited to see your contributions and help you become a part of the Open WebUI community!** 🎉 Happy coding!
|
||||
@@ -3,35 +3,77 @@ sidebar_position: 100
|
||||
title: "🚀 Getting Started"
|
||||
---
|
||||
|
||||
# Getting Started with Open WebUI
|
||||
|
||||
---
|
||||
**From zero to your first AI conversation in under five minutes.**
|
||||
|
||||
Welcome to the **Open WebUI Documentation Hub!** Below is a list of essential guides and resources to help you get started, manage, and develop with Open WebUI.
|
||||
Open WebUI runs anywhere (Docker, Kubernetes, pip, bare metal) and connects to any model provider out of the box. Pick an install method, connect a provider, and start chatting.
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ Quick Start
|
||||
|
||||
Get up and running quickly with our [Quick Start Guide](/getting-started/quick-start).
|
||||
**Install Open WebUI, connect a model, and start chatting.**
|
||||
|
||||
Everything you need for a working setup. Choose Docker for the fastest path, Python for lightweight installs, or Kubernetes for production orchestration. Each guide includes connecting your first model provider.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🐳 **Docker** | One-command deploy, the officially recommended path |
|
||||
| 📦 **Python (pip / uv)** | Lightweight install for low-resource or manual setups |
|
||||
| ☸️ **Kubernetes (Helm)** | Production-ready orchestration with scaling |
|
||||
| 🖥️ **Desktop app** | Native app (experimental), no Docker required |
|
||||
| 🔌 **Connect a provider** | Ollama, OpenAI, Anthropic, llama.cpp, vLLM, and more |
|
||||
| ⚙️ **Understanding settings** | Learn how Admin Settings and User Settings work together |
|
||||
|
||||
[**Start installing →**](/getting-started/quick-start)
|
||||
|
||||
---
|
||||
|
||||
## Sharing Open WebUI
|
||||
|
||||
**Bring AI to your entire organization with a single deployment.**
|
||||
|
||||
Open WebUI isn't just a local interface for AI. It is designed to be a centralized AI operating system for teams. Deploy it once to leverage frictionless onboarding, collaborative intelligence, resource pooling, and centralized security.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| **LAN & Tunnels** | Tailscale, Cloudflare Tunnels, and local IP access |
|
||||
| **Reverse Proxies** | Secure your instance with Nginx, Caddy, or HAProxy |
|
||||
| **Team Onboarding** | Admin approval flows and Enterprise SSO integrations |
|
||||
| **Shared Context** | Channels, shared chats, and common knowledge bases |
|
||||
|
||||
[**Learn how to share Open WebUI →**](/getting-started/sharing)
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Advanced Topics
|
||||
|
||||
Take a deeper dive into configurations and development tips in our [Advanced Topics Guide](/getting-started/advanced-topics).
|
||||
**Scale, observe, and customize your deployment.**
|
||||
|
||||
Go beyond the basics. Configure environment variables, connect external databases, add cloud storage, enable OpenTelemetry, or scale horizontally with Redis and multiple workers.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| ⚖️ **Scaling** | Multi-worker, multi-node, Redis-backed sessions |
|
||||
| 📊 **Logging & observability** | OpenTelemetry traces, metrics, and structured logs |
|
||||
| 🧪 **Development setup** | Run from source for local development and testing |
|
||||
|
||||
[**Explore advanced topics →**](/getting-started/advanced-topics)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Updating Open WebUI
|
||||
## 🔄 Updating
|
||||
|
||||
Stay current with the latest features and security patches with our [Updating Open WebUI](./updating) guide.
|
||||
**Stay current with the latest features and security patches.**
|
||||
|
||||
---
|
||||
Update manually with a single Docker or pip command, or automate with Watchtower, WUD, or Diun. Includes backup/restore procedures and version pinning for production.
|
||||
|
||||
## 🧪 Help Test Open WebUI
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🔄 **Manual update** | Docker pull + recreate, or pip upgrade |
|
||||
| 🤖 **Automated updates** | Watchtower, WUD, or Diun |
|
||||
| 📌 **Version pinning** | Lock to a specific release for stability |
|
||||
| 💾 **Backup & restore** | One-command volume backup and recovery |
|
||||
|
||||
**Want to help improve Open WebUI?** Run the [development branch](/#using-the-dev-branch-)! Testing dev builds is one of the most valuable contributions you can make—no code required. Just use it and report issues you find.
|
||||
|
||||
---
|
||||
|
||||
Happy exploring! 🎉 If you have questions, join our [community](https://discord.gg/5rJgQTnV4s) or raise an issue on [GitHub](https://github.com/open-webui/open-webui).
|
||||
[**Update guide →**](/getting-started/updating)
|
||||
|
||||
@@ -18,33 +18,20 @@ import WSL from './tab-docker/WSL.md';
|
||||
import DockerUpdating from './tab-docker/DockerUpdating.md';
|
||||
import Helm from './tab-kubernetes/Helm.md';
|
||||
import Venv from './tab-python/Venv.md';
|
||||
import Pip from './tab-python/Pip.md';
|
||||
import Uv from './tab-python/Uv.md';
|
||||
import Conda from './tab-python/Conda.md';
|
||||
import PythonUpdating from './tab-python/PythonUpdating.md';
|
||||
|
||||
|
||||
# Quick Start
|
||||
|
||||
:::info
|
||||
Get Open WebUI running on your machine. Pick your preferred method below.
|
||||
|
||||
### Platform Compatibility
|
||||
Open WebUI works on macOS, Linux (x86_64 and ARM64, including Raspberry Pi and other ARM boards like NVIDIA DGX Spark), and Windows.
|
||||
Open WebUI works on **macOS, Linux** (x86_64 and ARM64, including Raspberry Pi and NVIDIA DGX Spark), and **Windows**.
|
||||
|
||||
:::
|
||||
|
||||
:::tip User Roles and Privacy
|
||||
|
||||
- **Admin Creation:** The first account created on Open WebUI gains **Administrator privileges**, controlling user management and system settings.
|
||||
- **User Registrations:** Subsequent sign-ups start with **Pending** status, requiring Administrator approval for access.
|
||||
- **Privacy and Data Security:** **All your data**, including login details, is **locally stored** on your device. Open WebUI ensures **strict confidentiality** and **no external requests** for enhanced privacy and security.
|
||||
- **All models are private by default.** Models must be explicitly shared via groups or by being made public. If a model is assigned to a group, only members of that group can see it. If a model is made public, anyone on the instance can see it.
|
||||
|
||||
:::
|
||||
|
||||
Choose your preferred installation method below:
|
||||
|
||||
- **Docker:** **Officially supported and recommended for most users**
|
||||
- **Python:** Suitable for low-resource environments or those wanting a manual setup
|
||||
- **Kubernetes:** Ideal for enterprise deployments that require scaling and orchestration
|
||||
- **Docker:** Officially supported and recommended for most users. Requires [Docker](https://docs.docker.com/get-docker/) installed.
|
||||
- **Python:** Suitable for low-resource environments or manual setups
|
||||
- **Kubernetes:** Ideal for enterprise deployments requiring scaling and orchestration
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="docker" label="Docker">
|
||||
@@ -101,6 +88,13 @@ Choose your preferred installation method below:
|
||||
</TabItem>
|
||||
<TabItem value="python" label="Python">
|
||||
<Tabs>
|
||||
<TabItem value="pip" label="pip">
|
||||
<div className='mt-5'>
|
||||
<Pip />
|
||||
</div>
|
||||
<PythonUpdating />
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="uv" label="uv">
|
||||
<div className='mt-5'>
|
||||
<Uv />
|
||||
@@ -138,12 +132,10 @@ Choose your preferred installation method below:
|
||||
|
||||
### Desktop App
|
||||
|
||||
Download the desktop app from [**github.com/open-webui/desktop**](https://github.com/open-webui/desktop). It offers a convenient way to run Open WebUI natively on your system without Docker or manual setup.
|
||||
Download the desktop app from [**github.com/open-webui/desktop**](https://github.com/open-webui/desktop). It runs Open WebUI natively on your system without Docker or manual setup.
|
||||
|
||||
:::warning Experimental
|
||||
|
||||
The desktop app is actively a **work in progress** and is not yet stable. For production use, we recommend installing via **Docker** or **Python (`uv` or `pip`)**.
|
||||
|
||||
The desktop app is a **work in progress** and is not yet stable. For production use, install via **Docker** or **Python**.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
@@ -153,46 +145,53 @@ The desktop app is actively a **work in progress** and is not yet stable. For pr
|
||||
<TabItem value="pinokio-computer" label="Pinokio.computer">
|
||||
### Pinokio.computer Installation
|
||||
|
||||
For installation via Pinokio.computer, please visit their website:
|
||||
For installation via Pinokio.computer, visit their website:
|
||||
|
||||
[https://pinokio.computer/](https://pinokio.computer/)
|
||||
|
||||
Support for this installation method is provided through their website.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Additional Third-Party Integrations
|
||||
|
||||
*(Add information about third-party integrations as they become available.)*
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Next Steps
|
||||
---
|
||||
|
||||
After installing, visit:
|
||||
## After You Install
|
||||
|
||||
- [http://localhost:3000](http://localhost:3000) to access Open WebUI.
|
||||
- or [http://localhost:8080/](http://localhost:8080/) when using a Python deployment.
|
||||
:::tip First Login
|
||||
|
||||
You are now ready to start using Open WebUI!
|
||||
- **Admin account:** The first account created gets **Administrator privileges** and controls user management and system settings.
|
||||
- **New sign-ups:** Subsequent registrations start with **Pending** status and require Administrator approval.
|
||||
- **Privacy:** All data, including login details, is stored locally on your device. Open WebUI makes no external requests. All models are private by default and must be explicitly shared.
|
||||
|
||||
## Using Open WebUI with Ollama
|
||||
If you're using Open WebUI with Ollama, be sure to check out our [Starting with Ollama Guide](/getting-started/quick-start/connect-a-provider/starting-with-ollama) to learn how to manage your Ollama instances with Open WebUI.
|
||||
:::
|
||||
|
||||
## Experimental: Open Responses
|
||||
Open WebUI has experimental support for the [Open Responses](https://www.openresponses.org/) specification. See the [Starting with Open Responses Guide](/getting-started/quick-start/connect-a-provider/starting-with-open-responses) to learn how to enable it.
|
||||
### Connect a model provider
|
||||
|
||||
Open WebUI needs at least one model provider to start chatting. Choose yours:
|
||||
|
||||
| Provider | Guide |
|
||||
|----------|-------|
|
||||
| **Ollama** (local models) | [Starting with Ollama →](/getting-started/quick-start/connect-a-provider/starting-with-ollama) |
|
||||
| **OpenAI** | [Starting with OpenAI →](/getting-started/quick-start/connect-a-provider/starting-with-openai) |
|
||||
| **Any OpenAI-compatible API** | [OpenAI-Compatible Providers →](/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible) |
|
||||
| **Anthropic** | [Starting with Anthropic →](/getting-started/quick-start/connect-a-provider/starting-with-anthropic) |
|
||||
| **llama.cpp** | [Starting with llama.cpp →](/getting-started/quick-start/connect-a-provider/starting-with-llama-cpp) |
|
||||
| **vLLM** | [Starting with vLLM →](/getting-started/quick-start/connect-a-provider/starting-with-vllm) |
|
||||
|
||||
## Help Us Improve Open WebUI 🧪
|
||||
### Explore features
|
||||
|
||||
**Want to help make Open WebUI better?** Consider running the [development branch](/#using-the-dev-branch-)! Testing dev builds is one of the most valuable contributions you can make—no code required. Just use it and report any issues you find on [GitHub](https://github.com/open-webui/open-webui/issues).
|
||||
Once connected, explore what Open WebUI can do: [Features Overview →](/features)
|
||||
|
||||
## Join the Community
|
||||
### Experimental: Open Responses
|
||||
|
||||
Need help? Have questions? Join our community:
|
||||
Open WebUI has experimental support for the [Open Responses](https://www.openresponses.org/) specification. See the [Starting with Open Responses Guide](/getting-started/quick-start/connect-a-provider/starting-with-open-responses) to learn more.
|
||||
|
||||
- [Open WebUI Discord](https://discord.gg/5rJgQTnV4s)
|
||||
- [GitHub Issues](https://github.com/open-webui/open-webui/issues)
|
||||
---
|
||||
|
||||
Stay updated with the latest features, troubleshooting tips, and announcements!
|
||||
## Community
|
||||
|
||||
- [**Discord**](https://discord.gg/5rJgQTnV4s) for questions, discussion, and support
|
||||
- [**GitHub Issues**](https://github.com/open-webui/open-webui/issues) for bug reports and feature requests
|
||||
- **Want to help?** Test the [development branch](/contributing) and report issues. No code required.
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
sidebar_position: 100
|
||||
title: "Understanding Settings"
|
||||
---
|
||||
|
||||
# Understanding Settings
|
||||
|
||||
**Open WebUI has two separate settings areas, not one.**
|
||||
|
||||
Open WebUI is multi-user from day one. Even if you are the only person using it, the architecture assumes there could be many users on the same instance. That means the platform needs two layers of configuration: one for the administrator who controls the instance, and one for each individual user who controls their own experience.
|
||||
|
||||
---
|
||||
|
||||
## The Two Settings Areas
|
||||
|
||||
### Admin Settings (Global)
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| **Location** | Profile avatar > **Admin Settings**, or **Admin Panel > Settings** |
|
||||
| **Access** | Administrators only |
|
||||
| **Scope** | The entire instance and all users |
|
||||
|
||||
Admin Settings control everything about the Open WebUI instance itself: API connections, feature toggles, security policies, and default behaviors. Think of this as the **control panel for the building**. It determines what is installed and available for everyone.
|
||||
|
||||
**Examples of what lives here:**
|
||||
|
||||
- Connections to Ollama, OpenAI, and other providers
|
||||
- Enabling or disabling web search, image generation, and code execution
|
||||
- Default model selection and parameter presets
|
||||
- RBAC policies, SSO configuration, and signup restrictions
|
||||
|
||||
---
|
||||
|
||||
### User Settings (Personal)
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| **Location** | Profile avatar > **Settings** |
|
||||
| **Access** | Every user (including admins) |
|
||||
| **Scope** | Only the individual user |
|
||||
|
||||
User Settings control personal preferences: your default model, interface theme, language, notification preferences, and per-feature toggles for features the admin has already enabled. Think of this as the **thermostat in your own room**. You can adjust things for yourself, but only within what the building provides.
|
||||
|
||||
**Examples of what lives here:**
|
||||
|
||||
- Preferred default model and system prompt
|
||||
- Interface theme and language
|
||||
- Personal API keys (if [Direct Connections](/features/chat-conversations/direct-connections) are enabled)
|
||||
- Per-feature toggles like autocomplete or rich text input
|
||||
|
||||
---
|
||||
|
||||
## How They Work Together
|
||||
|
||||
Many features follow a **two-layer pattern**:
|
||||
|
||||
1. The admin decides whether a feature is **available** (Admin Settings)
|
||||
2. Each user decides whether they **personally want to use it** (User Settings)
|
||||
|
||||
**Example: Autocomplete (AI-powered typing suggestions)**
|
||||
|
||||
| Layer | Setting Location | Effect |
|
||||
|-------|-----------------|--------|
|
||||
| Admin enables it | Admin Settings > Interface | Makes autocomplete **available** on the instance |
|
||||
| User enables it | Settings > Interface | Turns autocomplete **on for you personally** |
|
||||
|
||||
:::important Key Rule
|
||||
If an admin **disables** a feature globally, users **cannot** enable it for themselves. The admin setting is always the ceiling.
|
||||
:::
|
||||
|
||||
This pattern applies across web search, image generation, direct connections, code interpreter, and more. The admin controls **what is possible**. Users control **what they want**.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| | Admin Settings | User Settings |
|
||||
|---|---|---|
|
||||
| **Scope** | Entire instance (all users) | Individual user only |
|
||||
| **Access** | Admins only | Everyone |
|
||||
| **Controls** | API connections, feature toggles, security, defaults | Theme, default model, personal preferences |
|
||||
| **Override behavior** | Cannot be overridden by users | Can customize within admin-allowed boundaries |
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
**"I enabled a feature in my settings but it is not working."**
|
||||
Check whether the admin has enabled it globally first. Your personal toggle only takes effect if the admin has made the feature available at the instance level.
|
||||
|
||||
**"I am the admin. Where do I configure connections to OpenAI or Ollama?"**
|
||||
Admin Settings > Connections. These are instance-wide and shared by all users.
|
||||
|
||||
**"I want to use my own API key without sharing it with the server."**
|
||||
If the admin has enabled **Direct Connections**, you can add personal API keys in User Settings > Connections. See [Direct Connections](/features/chat-conversations/direct-connections).
|
||||
|
||||
**"I set a system prompt but my admin's model settings override it."**
|
||||
Model-level settings configured by admins in the Workspace take precedence over personal settings. See [Chat Parameters](/features/chat-conversations/chat-features/chat-params) for the full precedence hierarchy.
|
||||
|
||||
:::tip First-Time Admin?
|
||||
Start with **Admin Settings > Connections** to connect your model providers (Ollama, OpenAI, etc.), then explore **Admin Settings > Interface** to enable or disable features for your users.
|
||||
:::
|
||||
@@ -2,20 +2,7 @@
|
||||
|
||||
To update your local Docker installation to the latest version, you can either use **Watchtower** or manually update the container.
|
||||
|
||||
### Option 1: Using Watchtower (Recommended Fork)
|
||||
|
||||
:::info Deprecation Notice
|
||||
The original `containrrr/watchtower` is **no longer maintained** and may fail with newer Docker versions. We recommend using the `nicholas-fedor/watchtower` fork.
|
||||
:::
|
||||
|
||||
:::warning Multi-Worker Environments
|
||||
If you run Open WebUI with `UVICORN_WORKERS > 1` (e.g., in a production environment), you **MUST** ensure the update migration runs on a single worker first to prevent database schema corruption.
|
||||
|
||||
**Steps for proper update:**
|
||||
1. Update and start your container with `UVICORN_WORKERS=1`.
|
||||
2. Wait for the application to fully start and complete migrations.
|
||||
3. Stop and restart the container with your desired number of workers.
|
||||
:::
|
||||
### Option 1: Using Watchtower
|
||||
|
||||
With [Watchtower](https://github.com/nicholas-fedor/watchtower), you can automate the update process:
|
||||
|
||||
@@ -42,7 +29,14 @@ docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock nickfedor/wat
|
||||
3. Start the container again:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
|
||||
-e WEBUI_SECRET_KEY="your-secret-key" \
|
||||
--name open-webui --restart always \
|
||||
ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
Both methods will get your Docker instance updated and running with the latest build.
|
||||
:::warning Set WEBUI_SECRET_KEY
|
||||
Without a persistent `WEBUI_SECRET_KEY`, you'll be logged out every time the container is recreated. Generate one with `openssl rand -hex 32`.
|
||||
:::
|
||||
|
||||
For version pinning, rollback, automated update tools, and backup procedures, see the [full update guide](/getting-started/updating).
|
||||
|
||||
@@ -1,82 +1,64 @@
|
||||
## Quick Start with Docker 🐳
|
||||
|
||||
Follow these steps to install Open WebUI with Docker.
|
||||
## Quick Start with Docker
|
||||
|
||||
:::info
|
||||
|
||||
**WebSocket** support is required for Open WebUI to function correctly. Ensure that your network configuration allows WebSocket connections.
|
||||
|
||||
**WebSocket** support is required. Ensure your network configuration allows WebSocket connections.
|
||||
:::
|
||||
|
||||
:::tip Docker Hub Now Available
|
||||
|
||||
Open WebUI images are now published to **both** registries:
|
||||
Open WebUI images are published to **both** registries:
|
||||
- **GitHub Container Registry:** `ghcr.io/open-webui/open-webui`
|
||||
- **Docker Hub:** `openwebui/open-webui`
|
||||
|
||||
Both registries contain identical images. You can use either one — simply replace `ghcr.io/open-webui/open-webui` with `openwebui/open-webui` in any command below.
|
||||
|
||||
Both contain identical images. Replace `ghcr.io/open-webui/open-webui` with `openwebui/open-webui` in any command below.
|
||||
:::
|
||||
|
||||
## Step 1: Pull the Open WebUI Image
|
||||
|
||||
Start by pulling the latest Open WebUI Docker image from the GitHub Container Registry (or use `openwebui/open-webui:main` from Docker Hub).
|
||||
### 1. Pull the image
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
### Slim Image Variant
|
||||
|
||||
For environments with limited storage or bandwidth, Open WebUI offers slim image variants that exclude pre-bundled models. These images are significantly smaller but download required models (whisper, embedding models) on first use.
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/open-webui/open-webui:main-slim
|
||||
```
|
||||
|
||||
### Specific release version
|
||||
|
||||
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.
|
||||
|
||||
Versioned images follow this format:
|
||||
|
||||
```
|
||||
ghcr.io/open-webui/open-webui:<RELEASE_VERSION>-<TYPE>
|
||||
# or equivalently:
|
||||
openwebui/open-webui:<RELEASE_VERSION>-<TYPE>
|
||||
```
|
||||
|
||||
Examples:
|
||||
```bash
|
||||
docker pull ghcr.io/open-webui/open-webui:v0.8.13
|
||||
docker pull ghcr.io/open-webui/open-webui:v0.8.13-ollama
|
||||
docker pull ghcr.io/open-webui/open-webui:v0.8.13-cuda
|
||||
```
|
||||
|
||||
If you want to always run the latest version, you can use the floating tags `:main`, `:cuda`, or `:ollama`. For production environments where stability and reproducibility are important, pin a specific release version instead.
|
||||
|
||||
## Step 2: Run the Container
|
||||
|
||||
Run the container with default settings. This command includes a volume mapping to ensure persistent data storage.
|
||||
### 2. Run the container
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
To use the slim variant instead:
|
||||
| Flag | Purpose |
|
||||
|------|---------|
|
||||
| `-v open-webui:/app/backend/data` | Persistent storage. Prevents data loss between restarts. |
|
||||
| `-p 3000:8080` | Exposes the UI on port 3000 of your machine. |
|
||||
|
||||
### 3. Open the UI
|
||||
|
||||
Visit [http://localhost:3000](http://localhost:3000).
|
||||
|
||||
---
|
||||
|
||||
## Image Variants
|
||||
|
||||
| Tag | Use case |
|
||||
|-----|----------|
|
||||
| `:main` | Standard image (recommended) |
|
||||
| `:main-slim` | Smaller image, downloads Whisper and embedding models on first use |
|
||||
| `:cuda` | Nvidia GPU support (add `--gpus all` to `docker run`) |
|
||||
| `:ollama` | Bundles Ollama inside the container for an all-in-one setup |
|
||||
|
||||
### Specific release versions
|
||||
|
||||
For production environments, pin a specific version instead of using floating tags:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main-slim
|
||||
docker pull ghcr.io/open-webui/open-webui:v0.8.13
|
||||
docker pull ghcr.io/open-webui/open-webui:v0.8.13-cuda
|
||||
docker pull ghcr.io/open-webui/open-webui:v0.8.13-ollama
|
||||
```
|
||||
|
||||
### Important Flags
|
||||
---
|
||||
|
||||
- **Volume Mapping (`-v open-webui:/app/backend/data`)**: Ensures persistent storage of your data. This prevents data loss between container restarts.
|
||||
- **Port Mapping (`-p 3000:8080`)**: Exposes the WebUI on port 3000 of your local machine.
|
||||
## Common Configurations
|
||||
|
||||
### Using GPU Support
|
||||
|
||||
For Nvidia GPU support, add `--gpus all` to the `docker run` command:
|
||||
### GPU support (Nvidia)
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 --gpus all -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:cuda
|
||||
@@ -84,104 +66,69 @@ docker run -d -p 3000:8080 --gpus all -v open-webui:/app/backend/data --name ope
|
||||
|
||||
### Bundled with Ollama
|
||||
|
||||
This installation method uses a single container image that bundles Open WebUI with Ollama, allowing for a streamlined setup via a single command.
|
||||
A single container with Open WebUI and Ollama together:
|
||||
|
||||
- **With GPU Support:**
|
||||
**With GPU:**
|
||||
```bash
|
||||
docker run -d -p 3000:8080 --gpus=all -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama
|
||||
```
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 --gpus=all -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama
|
||||
```
|
||||
**CPU only:**
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama
|
||||
```
|
||||
|
||||
- **CPU Only:**
|
||||
### Connecting to Ollama on a different server
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama
|
||||
```
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=https://example.com -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
#### Single-User Mode (Disabling Login)
|
||||
|
||||
To bypass the login page for a single-user setup, set the `WEBUI_AUTH` environment variable to `False`:
|
||||
### Single-user mode (no login)
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -e WEBUI_AUTH=False -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
:::warning
|
||||
|
||||
You cannot switch between single-user mode and multi-account mode after this change.
|
||||
|
||||
:::
|
||||
|
||||
#### Advanced Configuration: Connecting to Ollama on a Different Server
|
||||
---
|
||||
|
||||
To connect Open WebUI to an Ollama server located on another host, add the `OLLAMA_BASE_URL` environment variable:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=https://example.com -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
## Access the WebUI
|
||||
|
||||
After the container is running, access Open WebUI at:
|
||||
|
||||
[http://localhost:3000](http://localhost:3000)
|
||||
|
||||
For detailed help on each Docker flag, see [Docker's documentation](https://docs.docker.com/engine/reference/commandline/run/).
|
||||
|
||||
## Using the Dev Branch 🌙
|
||||
|
||||
:::tip Help Us Build Better Software!
|
||||
|
||||
**We encourage users to run the development branch!** Testing dev builds is one of the most valuable ways to contribute to Open WebUI. By running the latest development version, you help us catch bugs early, validate new features, and ensure stable releases for everyone.
|
||||
|
||||
**Community testing makes a real difference.** Early feedback from dev-branch users helps us catch bugs sooner, refine new features, and ship more polished stable releases. Every issue you report on dev is one fewer surprise in production.
|
||||
## Using the Dev Branch
|
||||
|
||||
:::tip
|
||||
Testing dev builds is one of the most valuable ways to contribute. Run it on a test instance and report issues on [GitHub](https://github.com/open-webui/open-webui/issues).
|
||||
:::
|
||||
|
||||
The `:dev` tag contains the latest features and changes before they reach a stable release. While it may occasionally have bugs or incomplete features, it's generally usable for day-to-day testing.
|
||||
The `:dev` tag contains the latest features before they reach a stable release.
|
||||
|
||||
**Standard dev image:**
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:dev
|
||||
```
|
||||
|
||||
**Slim variant (excludes bundled models):**
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:dev-slim
|
||||
```
|
||||
|
||||
**How to help:**
|
||||
- Run the dev image on a test instance (not your primary production setup)
|
||||
- **Keep it updated regularly** — the dev branch moves fast! Pull the latest image frequently
|
||||
- Report issues on [GitHub](https://github.com/open-webui/open-webui/issues) with clear reproduction steps
|
||||
- Join our [Discord](https://discord.gg/5rJgQTnV4s) to discuss findings
|
||||
|
||||
:::warning Do Not Share Data with Production
|
||||
|
||||
**Never share your database or data volume between dev and production setups.** Dev builds may include database migrations that are not backward-compatible. If a dev migration runs on your production data and you later need to roll back, your production setup may break.
|
||||
|
||||
Always use a separate data volume (e.g., `-v open-webui-dev:/app/backend/data`) for testing.
|
||||
|
||||
:::warning
|
||||
**Never share your data volume between dev and production.** Dev builds may include database migrations that are not backward-compatible. Always use a separate volume (e.g., `-v open-webui-dev:/app/backend/data`).
|
||||
:::
|
||||
|
||||
If Docker doesn't work for your environment, you can also run the latest development code using the [Local Development Guide](/getting-started/development).
|
||||
If Docker is not your preference, follow the [Local Development Guide](/getting-started/advanced-topics/development).
|
||||
|
||||
---
|
||||
|
||||
## Uninstall
|
||||
|
||||
To uninstall Open WebUI running with Docker, follow these steps:
|
||||
|
||||
1. **Stop and Remove the Container:**
|
||||
1. **Stop and remove the container:**
|
||||
```bash
|
||||
docker rm -f open-webui
|
||||
```
|
||||
|
||||
2. **Remove the Image (Optional):**
|
||||
2. **Remove the image (optional):**
|
||||
```bash
|
||||
docker rmi ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
3. **Remove the Volume (Optional, WARNING: Deletes all data):**
|
||||
If you want to completely remove your data (chats, settings, etc.):
|
||||
3. **Remove the volume (optional, deletes all data):**
|
||||
```bash
|
||||
docker volume rm open-webui
|
||||
```
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
### Installation with pip
|
||||
|
||||
The simplest way to install Open WebUI with Python.
|
||||
|
||||
#### 1. Install Open WebUI
|
||||
|
||||
```bash
|
||||
pip install open-webui
|
||||
```
|
||||
|
||||
#### 2. Start the server
|
||||
|
||||
```bash
|
||||
open-webui serve
|
||||
```
|
||||
|
||||
Open WebUI is now running at [http://localhost:8080](http://localhost:8080).
|
||||
|
||||
:::tip 'open-webui: command not found'?
|
||||
1. If you used a virtual environment, make sure it's activated.
|
||||
2. Try running directly: `python -m open_webui serve`
|
||||
3. To store data in a specific location: `DATA_DIR=./data open-webui serve`
|
||||
:::
|
||||
|
||||
## Uninstall
|
||||
|
||||
1. **Uninstall the package:**
|
||||
```bash
|
||||
pip uninstall open-webui
|
||||
```
|
||||
|
||||
2. **Remove data (optional, deletes all data):**
|
||||
```bash
|
||||
rm -rf ~/.open-webui
|
||||
```
|
||||
@@ -8,7 +8,11 @@ pip install -U open-webui
|
||||
|
||||
The `-U` (or `--upgrade`) flag ensures that `pip` upgrades the package to the latest available version.
|
||||
|
||||
That's it! Your **Open-WebUI** package is now updated and ready to use.
|
||||
After upgrading, restart the server and verify it starts correctly:
|
||||
|
||||
```bash
|
||||
open-webui serve
|
||||
```
|
||||
|
||||
:::warning Multi-Worker Environments
|
||||
If you run Open WebUI with `UVICORN_WORKERS > 1` (e.g., in a production environment), you **MUST** ensure the update migration runs on a single worker first to prevent database schema corruption.
|
||||
@@ -19,3 +23,5 @@ If you run Open WebUI with `UVICORN_WORKERS > 1` (e.g., in a production environm
|
||||
3. Wait for the application to fully start and complete migrations.
|
||||
4. Stop and restart the application with your desired number of workers.
|
||||
:::
|
||||
|
||||
For version pinning, rollback, and backup procedures, see the [full update guide](/getting-started/updating).
|
||||
|
||||
@@ -1,82 +0,0 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
title: "Understanding Settings"
|
||||
---
|
||||
|
||||
# Understanding Settings
|
||||
|
||||
When you first start using Open WebUI, you'll notice there are **two separate settings areas** — not one. This trips up almost everyone at first, so let's clear it up.
|
||||
|
||||
## Why Two Settings?
|
||||
|
||||
Open WebUI is designed to be **multi-user from day one**. Even if you're the only person using it right now, the architecture assumes there could be many users on the same instance — a team, a classroom, an entire organization.
|
||||
|
||||
That creates a fundamental problem: **an admin needs to control what's available on the instance** (which APIs are connected, which features are turned on, what the security policies are), while **each user needs to control their own experience** (which model they prefer, what their interface looks like, their personal defaults). A single settings page can't serve both purposes — what an admin configures for everyone is fundamentally different from what you configure for yourself.
|
||||
|
||||
So Open WebUI splits them:
|
||||
|
||||
## The Two Settings Areas
|
||||
|
||||
### ⚙️ Admin Settings (Global)
|
||||
|
||||
- **Where**: Click your profile avatar → **Admin Settings**, or **Admin Panel > Settings**
|
||||
- **Who can access**: Only **Administrators**
|
||||
- **What it controls**: Everything about the Open WebUI **instance itself** — the features available to all users, API connections, security policies, and default behaviors
|
||||
|
||||
Think of this as the **control panel for the building**. It determines what's installed and available for everyone.
|
||||
|
||||
### 🛠️ User Settings (Personal)
|
||||
|
||||
- **Where**: Click your profile avatar → **Settings**
|
||||
- **Who can access**: **Every user** (including admins)
|
||||
- **What it controls**: Your **personal preferences** — your default model, interface theme, language, notification preferences, and personal overrides for features the admin has enabled
|
||||
|
||||
Think of this as the **thermostat in your own room**. You can adjust things for yourself, but only within what the building provides.
|
||||
|
||||
## How They Work Together
|
||||
|
||||
Many features in Open WebUI follow a **two-layer pattern**:
|
||||
|
||||
1. **The admin decides if a feature is available** (Admin Settings)
|
||||
2. **Each user decides if they personally want to use it** (User Settings)
|
||||
|
||||
For example, consider **Autocomplete** (AI-powered typing suggestions):
|
||||
|
||||
| Layer | Setting Location | Effect |
|
||||
|-------|-----------------|--------|
|
||||
| Admin enables it | Admin Settings > Interface | Makes autocomplete **available** on the instance |
|
||||
| User enables it | Settings > Interface | Turns autocomplete **on for you personally** |
|
||||
|
||||
:::important Key Rule
|
||||
If an admin **disables** a feature globally, users **cannot** enable it for themselves. The admin setting is always the ceiling.
|
||||
:::
|
||||
|
||||
This pattern repeats across many features — web search, image generation, direct connections, code interpreter, and more. The admin controls the **what's possible**, and users control the **what I want**.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| | Admin Settings | User Settings |
|
||||
|---|---|---|
|
||||
| **Icon** | ⚙️ Admin Settings | 🛠️ Settings |
|
||||
| **Scope** | Entire instance (all users) | Just you |
|
||||
| **Access** | Admins only | Everyone |
|
||||
| **Controls** | API connections, feature toggles, security, defaults | Theme, default model, personal preferences |
|
||||
| **Overrides** | Cannot be overridden by users | Can customize within admin-allowed features |
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
**"I enabled a feature in my settings but it's not working."**
|
||||
→ Check if the admin has enabled it globally first. Your personal setting only works if the admin has made the feature available.
|
||||
|
||||
**"I'm the admin. Where do I configure connections to OpenAI/Ollama?"**
|
||||
→ Admin Settings > Connections. These are instance-wide and shared by all users.
|
||||
|
||||
**"I want to use my own API key without sharing it with the server."**
|
||||
→ If the admin has enabled **Direct Connections**, you can add personal API keys in your User Settings > Connections. See [Direct Connections](/features/chat-conversations/direct-connections).
|
||||
|
||||
**"I set a system prompt but my admin's model settings override it."**
|
||||
→ Model-level settings (configured by admins in the Workspace) take precedence over your personal settings. See [Chat Parameters](/features/chat-conversations/chat-features/chat-params) for the full hierarchy.
|
||||
|
||||
:::tip First-Time Admin?
|
||||
If you just installed Open WebUI, start with **Admin Settings > Connections** to connect your model providers (Ollama, OpenAI, etc.), then explore **Admin Settings > Interface** to enable or disable features for your users.
|
||||
:::
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
sidebar_position: 15
|
||||
title: "Sharing Open WebUI"
|
||||
---
|
||||
|
||||
# Sharing Open WebUI
|
||||
|
||||
**Deploy once, give your entire team access.**
|
||||
|
||||
Open WebUI is built to be shared. A single instance can serve your whole organization. Users just open a browser and start chatting. No per-seat installs, no client-side dependencies, no fragmented data across machines.
|
||||
|
||||
---
|
||||
|
||||
## Built for Teams
|
||||
|
||||
### Frictionless Onboarding
|
||||
|
||||
End users don't need to install anything, manage Docker, or touch a terminal. They open a browser, navigate to your instance URL, and log in.
|
||||
|
||||
### Collaborative Intelligence
|
||||
|
||||
A shared instance means shared knowledge.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| **[Channels](/features/channels)** | Persistent spaces where your team and AI models work together in real time |
|
||||
| **Shared Chats** | Send an exact conversation snapshot to a colleague |
|
||||
| **Global Prompts & Knowledge** | Build specialized agents and make them instantly available to everyone |
|
||||
|
||||
### Shared Compute
|
||||
|
||||
When running local models, a single powerful server (or cluster) serves your entire team instead of requiring capable hardware on every desk.
|
||||
|
||||
### Centralized Administration
|
||||
|
||||
Manage everything from one place: control which models users can access, configure [**Role-Based Access Control (RBAC)**](/features/authentication-access/rbac), review audit logs, and restrict features as needed.
|
||||
|
||||
---
|
||||
|
||||
## Opening Your Instance to the Team
|
||||
|
||||
To share your instance, you need to make it accessible over a network. There are three common approaches, from simple local access to production-grade public domains.
|
||||
|
||||
### 1. Zero-Config LAN (Local Network)
|
||||
|
||||
If your team is on the same local network or VPN, they can reach Open WebUI using your machine's local IP address and port.
|
||||
|
||||
> `http://192.168.1.100:3000`
|
||||
|
||||
### 2. Secure Private Networks (Recommended)
|
||||
|
||||
For remote teams that don't need public internet exposure. Overlay networks and secure tunnels provide encrypted access without opening firewall ports.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| **[Tailscale](/reference/https/tailscale)** | Private mesh network with MagicDNS (`https://open-webui.tailnet-name.ts.net`) |
|
||||
| **[Cloudflare Tunnels](/reference/https/cloudflare-tunnel)** | Expose via Cloudflare's edge, protected by Cloudflare Access (Zero Trust) |
|
||||
| **[ngrok](/reference/https/ngrok)** | Quick temporary sharing for development or testing |
|
||||
|
||||
### 3. Public HTTPS (Reverse Proxy)
|
||||
|
||||
For production deployments, place Open WebUI behind a reverse proxy for SSL/TLS termination on your own domain (e.g., `ai.yourcompany.com`).
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| **[Nginx](/reference/https/nginx)** | Industry standard web server and reverse proxy |
|
||||
| **[Caddy](/reference/https/caddy)** | Automatic HTTPS with minimal configuration |
|
||||
| **[HAProxy](/reference/https/haproxy)** | High-performance load balancing and proxying |
|
||||
|
||||
---
|
||||
|
||||
## Onboarding Your Team
|
||||
|
||||
Once your instance is network-accessible, you need to manage how users create accounts and log in.
|
||||
|
||||
### The Pending Queue
|
||||
|
||||
The first user to register becomes the **Administrator**. All subsequent sign-ups are placed in a **Pending** state and cannot access models or use the platform until an admin approves their account from the Admin Panel.
|
||||
|
||||
### Enterprise Single Sign-On (SSO)
|
||||
|
||||
For organizations where manual approval doesn't scale, Open WebUI integrates with your existing identity provider.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| **OAuth / OIDC** | Authenticate via **Google**, **Microsoft**, **Okta**, or **Keycloak** |
|
||||
| **Group mapping** | Map IdP groups directly to Open WebUI groups |
|
||||
| **[SCIM 2.0](/features/authentication-access/auth/scim)** | Automated user and group provisioning and deprovisioning |
|
||||
|
||||
[**Learn how to set up SSO →**](/features/authentication-access/auth/sso)
|
||||
@@ -6,16 +6,52 @@ title: "Updating Open WebUI"
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## Overview
|
||||
# Updating Open WebUI
|
||||
|
||||
Keeping Open WebUI updated ensures you have the latest features, security patches, and bug fixes. You can update manually or automate the process using container update tools.
|
||||
**Stay current without losing your data.**
|
||||
|
||||
:::info Before Updating
|
||||
- **Backup your data** — especially before releases that include database migrations, since they can be hard to undo. Check [release notes](https://github.com/open-webui/open-webui/releases) for breaking changes
|
||||
- **Clear browser cache** after updating (Ctrl+F5 / Cmd+Shift+R)
|
||||
- **Multiple workers/replicas?** Run migrations with `UVICORN_WORKERS=1` first, or set `ENABLE_DB_MIGRATIONS=False` on all but one instance
|
||||
Your data (chats, users, settings, uploads) lives in a Docker volume or local database, not inside the container. Updating Open WebUI means swapping the container image for a newer one. Your data stays exactly where it is.
|
||||
|
||||
---
|
||||
|
||||
## Choose Your Update Strategy
|
||||
|
||||
Before running any commands, decide how you want to track releases. The right choice depends on how you use Open WebUI.
|
||||
|
||||
| Scenario | Recommended approach |
|
||||
|---|---|
|
||||
| **Personal / homelab** | Use the `:main` tag and pull manually when you want the latest |
|
||||
| **Shared / team instance** | Pin a specific version (e.g. `:v0.8.6`) and use [Diun](#diun) for update notifications |
|
||||
| **Production / critical** | Pin a version, review [release notes](https://github.com/open-webui/open-webui/releases) before upgrading, test in staging first |
|
||||
|
||||
### `:main` vs. Pinned Versions
|
||||
|
||||
The `:main` tag always points to the **latest build**. It's convenient but can include breaking changes without warning.
|
||||
|
||||
For stability, pin a specific release tag:
|
||||
|
||||
```
|
||||
ghcr.io/open-webui/open-webui:v0.8.13
|
||||
ghcr.io/open-webui/open-webui:v0.8.13-cuda
|
||||
ghcr.io/open-webui/open-webui:v0.8.13-ollama
|
||||
```
|
||||
|
||||
Browse all available tags on the [GitHub releases page](https://github.com/open-webui/open-webui/releases).
|
||||
|
||||
---
|
||||
|
||||
## Before You Update
|
||||
|
||||
1. **Back up your data** (see [Backup & Restore](#backup--restore) below). Especially important before releases with database migrations, which can be hard to undo.
|
||||
2. **Check the [release notes](https://github.com/open-webui/open-webui/releases)** for breaking changes.
|
||||
3. **Clear your browser cache** after updating (`Ctrl+F5` / `Cmd+Shift+R`) to avoid stale frontend assets.
|
||||
|
||||
:::warning Running multiple workers or replicas?
|
||||
Run migrations on a single instance first: set `UVICORN_WORKERS=1` or `ENABLE_DB_MIGRATIONS=false` on all but one instance. See the [Scaling guide](/getting-started/advanced-topics/scaling) for details.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Manual Update
|
||||
|
||||
<Tabs groupId="setup-method">
|
||||
@@ -25,7 +61,7 @@ Keeping Open WebUI updated ensures you have the latest features, security patche
|
||||
# 1. Stop and remove the container (data in the volume is preserved)
|
||||
docker rm -f open-webui
|
||||
|
||||
# 2. Pull the latest image
|
||||
# 2. Pull the latest image (or replace :main with a pinned version)
|
||||
docker pull ghcr.io/open-webui/open-webui:main
|
||||
|
||||
# 3. Recreate the container
|
||||
@@ -64,87 +100,110 @@ volumes:
|
||||
open-webui:
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="python" label="Python (pip)">
|
||||
|
||||
```bash
|
||||
pip install -U open-webui
|
||||
```
|
||||
|
||||
The `-U` flag upgrades to the latest version. Then restart the server:
|
||||
|
||||
```bash
|
||||
open-webui serve
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::warning Set WEBUI_SECRET_KEY to avoid logout on every update
|
||||
Without a persistent `WEBUI_SECRET_KEY`, a new key is generated each time the container is recreated, invalidating all sessions. Generate one with `openssl rand -hex 32` and keep it across updates.
|
||||
Without a persistent `WEBUI_SECRET_KEY`, a new key is generated each time the container is recreated, invalidating all sessions. Generate one with `openssl rand -hex 32` and keep it across updates. See the [Environment Variable Reference](/reference/env-configuration) for details.
|
||||
:::
|
||||
|
||||
### Pinning a Version
|
||||
### Verify the Update
|
||||
|
||||
By default the `:main` tag always points to the latest build. For production, pin a specific release:
|
||||
After updating, confirm everything is working:
|
||||
|
||||
```
|
||||
ghcr.io/open-webui/open-webui:v0.8.13
|
||||
ghcr.io/open-webui/open-webui:v0.8.13-cuda
|
||||
ghcr.io/open-webui/open-webui:v0.8.13-ollama
|
||||
```
|
||||
1. **Check version in logs:**
|
||||
```bash
|
||||
docker logs open-webui 2>&1 | head -20
|
||||
```
|
||||
2. **Load the UI** at [http://localhost:3000](http://localhost:3000). You should see the login page.
|
||||
3. **If the UI looks broken**, clear your browser cache (`Ctrl+F5` / `Cmd+Shift+R`).
|
||||
4. **If you see migration errors** in the logs, check the [release notes](https://github.com/open-webui/open-webui/releases) for known issues and the [Connection Errors](/troubleshooting/connection-error) troubleshooting page.
|
||||
|
||||
### Rolling Back
|
||||
---
|
||||
|
||||
If an update causes problems, pin the previous version:
|
||||
## Rolling Back
|
||||
|
||||
If an update causes problems, you can go back to a previous version by pinning its tag.
|
||||
|
||||
<Tabs groupId="setup-method">
|
||||
<TabItem value="docker-run" label="Docker Run" default>
|
||||
|
||||
```bash
|
||||
docker rm -f open-webui
|
||||
docker pull ghcr.io/open-webui/open-webui:v0.8.3
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
|
||||
-e WEBUI_SECRET_KEY="your-secret-key" \
|
||||
--name open-webui ghcr.io/open-webui/open-webui:v0.8.3
|
||||
--name open-webui --restart always \
|
||||
ghcr.io/open-webui/open-webui:v0.8.3
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="docker-compose" label="Docker Compose">
|
||||
|
||||
Change the image tag in your `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
image: ghcr.io/open-webui/open-webui:v0.8.3
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="python" label="Python (pip)">
|
||||
|
||||
```bash
|
||||
pip install open-webui==0.8.3
|
||||
open-webui serve
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::caution Database migrations are one-way
|
||||
If the version you updated to ran a database migration, rolling back the container **does not** undo the migration. The older version may not work with the newer database schema. In that case, you need to restore from a backup taken **before** the update. For database-specific recovery, see the [Manual Database Migration](/troubleshooting/manual-database-migration) guide.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Automated Updates
|
||||
## Stay Notified About Updates
|
||||
|
||||
:::warning
|
||||
Automated updates can break your deployment if a release includes breaking changes or migration issues. Review release notes before auto-updating production systems, and always have a backup.
|
||||
:::
|
||||
|
||||
### Choosing a Tool
|
||||
|
||||
| Feature | Watchtower | WUD | Diun |
|
||||
|---------|:---:|:---:|:---:|
|
||||
| **Auto-updates containers** | ✅ | ❌ (manual via UI) | ❌ |
|
||||
| **Web interface** | ❌ | ✅ | ❌ |
|
||||
| **Notifications** | ✅ | ✅ | ✅ |
|
||||
| **Docker 29+** | ✅ (forks) | ✅ | ✅ |
|
||||
| **Resource usage** | Low | Medium | Very Low |
|
||||
| **Best for** | Homelabs | Visual monitoring | Notification-only |
|
||||
Instead of checking manually, use a tool to monitor for new releases. Options are listed from safest to most hands-on.
|
||||
|
||||
:::tip Recommendation
|
||||
- **For homelabs/personal use:** nicholas-fedor/watchtower (automated)
|
||||
- **For managed environments:** WUD (visual + manual control)
|
||||
- **For production/critical systems:** Diun (notifications only) + manual updates
|
||||
- **Production / critical systems:** Diun (notification-only) + manual updates
|
||||
- **Managed environments:** WUD (visual dashboard + manual trigger)
|
||||
- **Homelabs / personal use:** Watchtower (fully automated)
|
||||
:::
|
||||
|
||||
### Watchtower
|
||||
|
||||
The original Watchtower project hasn't received updates in over two years and fails with Docker version 29.0.0 or newer due to API version incompatibility. Two maintained forks are available: [nicholas-fedor/watchtower](https://watchtower.nickfedor.com/) and Marrrrrrrrry/watchtower, both compatible with Docker 29+.
|
||||
|
||||
**One-time update:**
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
nickfedor/watchtower --run-once open-webui
|
||||
```
|
||||
|
||||
**Continuous (check every 6 hours):**
|
||||
```bash
|
||||
docker run -d --name watchtower --restart unless-stopped \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
nickfedor/watchtower --interval 21600 open-webui
|
||||
```
|
||||
|
||||
Set `WATCHTOWER_CLEANUP=true` to auto-remove old images. See [Watchtower docs](https://watchtower.nickfedor.com/) for scheduling, notifications, and monitor-only mode.
|
||||
|
||||
### What's Up Docker (WUD)
|
||||
|
||||
Web UI for monitoring container updates and triggering them manually. See [WUD documentation](https://getwud.github.io/wud/) for setup.
|
||||
| Feature | Diun | WUD | Watchtower |
|
||||
|---------|:---:|:---:|:---:|
|
||||
| **Auto-updates containers** | ❌ | ❌ (manual via UI) | ✅ |
|
||||
| **Web interface** | ❌ | ✅ | ❌ |
|
||||
| **Notifications** | ✅ | ✅ | ✅ |
|
||||
| **Docker 29+** | ✅ | ✅ | ✅ (forks) |
|
||||
| **Resource usage** | Very Low | Medium | Low |
|
||||
|
||||
### Diun
|
||||
|
||||
Notification-only — alerts you when updates are available (email, Slack, Discord, Telegram, etc.) without touching your containers.
|
||||
Notification-only. Alerts you when updates are available (email, Slack, Discord, Telegram, etc.) without touching your containers. You decide when and how to update.
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
@@ -171,24 +230,78 @@ services:
|
||||
|
||||
See [Diun documentation](https://crazymax.dev/diun/) for full setup and notification options.
|
||||
|
||||
### What's Up Docker (WUD)
|
||||
|
||||
Web UI for monitoring container updates and triggering them manually. See [WUD documentation](https://getwud.github.io/wud/) for setup.
|
||||
|
||||
### Watchtower
|
||||
|
||||
Fully automated. Pulls new images and recreates containers without intervention.
|
||||
|
||||
:::warning
|
||||
The original `containrrr/watchtower` is **no longer maintained** and fails with Docker 29+. Use the [nicholas-fedor/watchtower](https://watchtower.nickfedor.com/) fork instead.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
Automated updates can break your deployment if a release includes breaking changes or database migrations. Review release notes before auto-updating production systems, and always have a backup.
|
||||
:::
|
||||
|
||||
**One-time update:**
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
nickfedor/watchtower --run-once open-webui
|
||||
```
|
||||
|
||||
**Continuous (check every 6 hours):**
|
||||
```bash
|
||||
docker run -d --name watchtower --restart unless-stopped \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
nickfedor/watchtower --interval 21600 open-webui
|
||||
```
|
||||
|
||||
Set `WATCHTOWER_CLEANUP=true` to auto-remove old images. See [Watchtower docs](https://watchtower.nickfedor.com/) for scheduling, notifications, and monitor-only mode.
|
||||
|
||||
---
|
||||
|
||||
## Backup & Restore
|
||||
|
||||
All data (chats, users, uploads) lives in the `open-webui` Docker volume.
|
||||
All data lives in the `open-webui` Docker volume, including:
|
||||
- **Database**: chats, users, settings, admin configuration
|
||||
- **Uploaded files**: documents, images, knowledge base content
|
||||
- **Generated content**: image generation outputs, exported data
|
||||
|
||||
### Backup
|
||||
|
||||
**Backup:**
|
||||
```bash
|
||||
docker run --rm -v open-webui:/data -v $(pwd):/backup \
|
||||
alpine tar czf /backup/openwebui-$(date +%Y%m%d).tar.gz /data
|
||||
```
|
||||
|
||||
**Restore:**
|
||||
Back up **before every update** and on a regular schedule (daily or weekly, depending on how actively you use Open WebUI).
|
||||
|
||||
### Restore
|
||||
|
||||
:::caution
|
||||
The restore command **deletes everything in the volume** before extracting the backup. Make sure you're restoring the right file.
|
||||
:::
|
||||
|
||||
```bash
|
||||
docker stop open-webui
|
||||
docker run --rm -v open-webui:/data -v $(pwd):/backup \
|
||||
alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-20250216.tar.gz -C /"
|
||||
alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-YYYYMMDD.tar.gz -C /"
|
||||
docker start open-webui
|
||||
```
|
||||
|
||||
For database-specific recovery, see the [Manual Database Migration](/troubleshooting/manual-database-migration.md) guide.
|
||||
Replace `YYYYMMDD` with the actual date of your backup file.
|
||||
|
||||
For database-specific recovery, see the [Manual Database Migration](/troubleshooting/manual-database-migration) guide.
|
||||
|
||||
---
|
||||
|
||||
## Related Guides
|
||||
|
||||
- [Scaling Open WebUI](/getting-started/advanced-topics/scaling): multi-worker and multi-instance deployments
|
||||
- [Connection Errors](/troubleshooting/connection-error): troubleshooting post-update connectivity issues
|
||||
- [Environment Variable Reference](/reference/env-configuration): all configuration options including `WEBUI_SECRET_KEY`
|
||||
- [Release Notes](https://github.com/open-webui/open-webui/releases): changelog for every version
|
||||
|
||||
+3
-3
@@ -73,10 +73,10 @@ Then open [http://localhost:8080](http://localhost:8080).
|
||||
## Explore
|
||||
|
||||
- [**Features**](/features) — Discover what Open WebUI can do
|
||||
- [**Tutorials**](/category/-tutorials) — Step-by-step guides
|
||||
- [**Tutorials**](/tutorials) — Step-by-step guides
|
||||
- [**FAQ**](/faq) — Common questions answered
|
||||
- [**Troubleshooting**](/troubleshooting) — Fix common issues
|
||||
- [**Reference**](/category/-reference) — Environment variables and API details
|
||||
- [**Reference**](/reference) — Environment variables and API details
|
||||
|
||||
---
|
||||
|
||||
@@ -90,7 +90,7 @@ Need **custom branding**, **SLA support**, or **Long-Term Support (LTS)** versio
|
||||
## Get Involved
|
||||
|
||||
- [**Contributing**](/contributing) — Help build Open WebUI
|
||||
- [**Development Setup**](/getting-started/development) — Run the project locally from source
|
||||
- [**Development Setup**](/getting-started/advanced-topics/development) — Run the project locally from source
|
||||
- [**Discord**](https://discord.gg/5rJgQTnV4s) — Join the community
|
||||
- [**GitHub**](https://github.com/open-webui/open-webui) — Report issues, submit PRs
|
||||
- [**Careers**](https://careers.openwebui.com/) — Join our team
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ All of this becomes possible when AI has **context**: your documents, your histo
|
||||
|
||||
That is what Open WebUI is. A home for AI. The place where your AI's knowledge, memory, tools, and skills accumulate over time into something that understands your work as deeply as you do. Something that doesn't just answer when asked, but anticipates what you need and acts.
|
||||
|
||||
It works with any model. It runs on your hardware. It scales from one person to thousands. And it is open source, because we believe this technology should belong to everyone.
|
||||
It works with any model. It runs on your hardware. It scales from one person to thousands. Because we believe this technology should belong to everyone.
|
||||
|
||||
**Our mission is to bring AI to every person and every organization on Earth, and everywhere beyond it.**
|
||||
|
||||
|
||||
@@ -1,7 +1,4 @@
|
||||
{
|
||||
"label": "📖 Reference",
|
||||
"position": 150,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
"position": 150
|
||||
}
|
||||
|
||||
@@ -7,7 +7,7 @@ This guide provides essential information on how to interact with the API endpoi
|
||||
|
||||
## Authentication
|
||||
|
||||
To ensure secure access to the API, authentication is required 🛡️. You can authenticate your API requests using the Bearer Token mechanism. Obtain your API key from **Settings > Account** in the Open WebUI, or alternatively, use a JWT (JSON Web Token) for authentication.
|
||||
To ensure secure access to the API, authentication is required 🛡️. You can authenticate your API requests using the Bearer Token mechanism. Obtain your API key from **Settings > Account** in the Open WebUI, or alternatively, use a JWT (JSON Web Token) for authentication. For full instructions on enabling and generating API keys - including the admin toggle and group permissions required for non-admin users - see [API Keys](/features/authentication-access/api-keys).
|
||||
|
||||
## Swagger Documentation Links
|
||||
|
||||
|
||||
+2
-2
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
sidebar_position: 40
|
||||
title: "Backend-Controlled API Flow"
|
||||
---
|
||||
|
||||
@@ -9,7 +9,7 @@ title: "Backend-Controlled API Flow"
|
||||
|
||||
:::warning
|
||||
|
||||
This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the [contributing tutorial](/tutorials/tips/contributing-tutorial).
|
||||
This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the [contributing tutorial](/tutorials/contributing-tutorial).
|
||||
|
||||
:::
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 11
|
||||
sidebar_position: 50
|
||||
title: "Database Schema"
|
||||
---
|
||||
|
||||
@@ -582,7 +582,7 @@ WEBUI_BANNERS="[{\"id\": \"1\", \"type\": \"warning\", \"title\": \"Your message
|
||||
|
||||
- Type: `list` of `dict`
|
||||
- Default: `[]` (which means to use the built-in default prompt suggestions)
|
||||
- Description: Sets global default prompt suggestions shown to users when starting a new chat. These apply when no model-specific prompt suggestions are configured. Prompt suggestions can also be configured per-model via the Model Editor (see [Prompt Suggestions](/features/ai-knowledge/models#prompt-suggestions)), or globally for all models using the [Global Model Defaults](/features/ai-knowledge/models#global-model-defaults) feature. The format is:
|
||||
- Description: Sets global default prompt suggestions shown to users when starting a new chat. These apply when no model-specific prompt suggestions are configured. Prompt suggestions can also be configured per-model via the Model Editor (see [Prompt Suggestions](/features/workspace/models#prompt-suggestions)), or globally for all models using the [Global Model Defaults](/features/workspace/models#global-model-defaults-admin) feature. The format is:
|
||||
|
||||
```json
|
||||
[{"title": ["Title part 1", "Title part 2"], "content": "prompt"}]
|
||||
@@ -715,7 +715,7 @@ If this variable is unset or invalid, Open WebUI falls back to `AIOHTTP_CLIENT_T
|
||||
|
||||
- Type: `str`
|
||||
- Default: Not set (plain-text logging)
|
||||
- Description: Controls the log output format. Set to `json` to switch all stdout logging to single-line JSON objects, suitable for log aggregators like Loki, Fluentd, CloudWatch, and Datadog. When set to `json`, the ASCII startup banner is also suppressed to keep the log stream parseable. Any other value (or unset) uses the default plain-text format. See the [JSON Logging documentation](/getting-started/advanced-topics/logging#-json-logging-log_format) for details on log fields and examples.
|
||||
- Description: Controls the log output format. Set to `json` to switch all stdout logging to single-line JSON objects, suitable for log aggregators like Loki, Fluentd, CloudWatch, and Datadog. When set to `json`, the ASCII startup banner is also suppressed to keep the log stream parseable. Any other value (or unset) uses the default plain-text format. See the [JSON Logging documentation](/getting-started/advanced-topics/logging#structured-json-logging) for details on log fields and examples.
|
||||
|
||||
#### `ENABLE_AUDIT_STDOUT`
|
||||
|
||||
@@ -1372,7 +1372,7 @@ For API Key creation (and the API keys themselves) to work:
|
||||
1. Enable API keys globally using this setting (`ENABLE_API_KEYS`)
|
||||
2. For non-admin users, grant the "API Keys" permission via Default Permissions or User Groups
|
||||
|
||||
**Note:** Administrators can generate API keys whenever `ENABLE_API_KEYS` is enabled, even without `features.api_keys`. See the [Authentication Setup for API Key](/reference/monitoring#authentication-setup-for-api-key-) guide for detailed setup instructions.
|
||||
**Note:** Administrators can generate API keys whenever `ENABLE_API_KEYS` is enabled, even without `features.api_keys`.
|
||||
|
||||
:::
|
||||
|
||||
@@ -4528,7 +4528,7 @@ Strictly return in JSON format:
|
||||
|
||||
:::tip
|
||||
|
||||
For a detailed setup guide and example configuration, please refer to the [Gemini Image Generation Guide](/features/media-generation/image-generation-and-editing/gemini).
|
||||
For a detailed setup guide and example configuration, please refer to the [Gemini Image Generation Guide](/features/chat-conversations/image-generation-and-editing/gemini).
|
||||
|
||||
:::
|
||||
|
||||
@@ -4937,23 +4937,23 @@ In any production environment running more than one instance of Open WebUI (e.g.
|
||||
#### `WEBUI_AUTH_TRUSTED_EMAIL_HEADER`
|
||||
|
||||
- Type: `str`
|
||||
- Description: Defines the trusted request header for authentication. See [SSO docs](/features/access-security/auth/sso).
|
||||
- Description: Defines the trusted request header for authentication. See [SSO docs](/features/authentication-access/auth/sso).
|
||||
|
||||
#### `WEBUI_AUTH_TRUSTED_NAME_HEADER`
|
||||
|
||||
- Type: `str`
|
||||
- Description: Defines the trusted request header for the username of anyone registering with the
|
||||
`WEBUI_AUTH_TRUSTED_EMAIL_HEADER` header. See [SSO docs](/features/access-security/auth/sso).
|
||||
`WEBUI_AUTH_TRUSTED_EMAIL_HEADER` header. See [SSO docs](/features/authentication-access/auth/sso).
|
||||
|
||||
#### `WEBUI_AUTH_TRUSTED_GROUPS_HEADER`
|
||||
|
||||
- Type: `str`
|
||||
- Description: Defines the trusted request header containing a comma-separated list of group memberships for the user when using trusted header authentication. See [SSO docs](/features/access-security/auth/sso).
|
||||
- Description: Defines the trusted request header containing a comma-separated list of group memberships for the user when using trusted header authentication. See [SSO docs](/features/authentication-access/auth/sso).
|
||||
|
||||
#### `WEBUI_AUTH_TRUSTED_ROLE_HEADER`
|
||||
|
||||
- Type: `str`
|
||||
- Description: Defines the trusted request header that determines the user's role (`admin`, `user`, or `pending`) when using trusted header authentication. When set, the user's role is updated to match the header value on every sign-in. Invalid values are ignored with a warning. See [SSO docs](/features/access-security/auth/sso).
|
||||
- Description: Defines the trusted request header that determines the user's role (`admin`, `user`, or `pending`) when using trusted header authentication. When set, the user's role is updated to match the header value on every sign-in. Invalid values are ignored with a warning. See [SSO docs](/features/authentication-access/auth/sso).
|
||||
|
||||
### Google
|
||||
|
||||
|
||||
@@ -0,0 +1,222 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: "HTTPS using Cloudflare Tunnel"
|
||||
---
|
||||
|
||||
# HTTPS using Cloudflare Tunnel
|
||||
|
||||
**Expose Open WebUI to the internet securely. No open ports, no certificates, no reverse proxy.**
|
||||
|
||||
Cloudflare Tunnel (`cloudflared`) creates an outbound-only connection from your machine to Cloudflare's edge network. Traffic flows through Cloudflare's infrastructure with automatic TLS, DDoS protection, and access controls, all without exposing a single port on your server.
|
||||
|
||||
:::tip When to use Cloudflare Tunnel
|
||||
This is the recommended approach when you want **production-grade public access** without managing TLS certificates or firewall rules. It works on any network, including behind NAT or restrictive firewalls.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Details |
|
||||
| :--- | :--- |
|
||||
| **Open WebUI** | Running locally on port `8080` (default) |
|
||||
| **Cloudflare account** | Free at [cloudflare.com](https://dash.cloudflare.com/sign-up) |
|
||||
| **Domain on Cloudflare** | Your domain's DNS must be managed by Cloudflare |
|
||||
|
||||
---
|
||||
|
||||
## Option A: Dashboard setup (no CLI)
|
||||
|
||||
The simplest path. Everything configured through the Cloudflare dashboard.
|
||||
|
||||
### 1. Create the tunnel
|
||||
|
||||
1. Go to [**Zero Trust → Networks → Tunnels**](https://one.dash.cloudflare.com/networks/tunnels)
|
||||
2. Click **Create a tunnel** → select **Cloudflared**
|
||||
3. Name it (e.g., `open-webui`)
|
||||
4. Follow the install instructions to run the connector on your machine
|
||||
|
||||
### 2. Add a public hostname
|
||||
|
||||
In the tunnel config, add a **Public Hostname**:
|
||||
|
||||
| Field | Value |
|
||||
| :--- | :--- |
|
||||
| **Subdomain** | `chat` (or whatever you prefer) |
|
||||
| **Domain** | Select your Cloudflare domain |
|
||||
| **Service type** | `HTTP` |
|
||||
| **URL** | `localhost:8080` |
|
||||
|
||||
Save. Cloudflare creates the DNS record automatically.
|
||||
|
||||
### 3. Access Open WebUI
|
||||
|
||||
Open `https://chat.your-domain.com`. HTTPS is handled entirely by Cloudflare.
|
||||
|
||||
---
|
||||
|
||||
## Option B: CLI setup
|
||||
|
||||
For automation, infrastructure-as-code, or headless servers.
|
||||
|
||||
### 1. Install cloudflared
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="mac" label="macOS" default>
|
||||
|
||||
```bash
|
||||
brew install cloudflared
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```bash
|
||||
curl -sSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
|
||||
-o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
```powershell
|
||||
winget install Cloudflare.cloudflared
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### 2. Authenticate
|
||||
|
||||
```bash
|
||||
cloudflared tunnel login
|
||||
```
|
||||
|
||||
This opens a browser to authorize `cloudflared` with your Cloudflare account.
|
||||
|
||||
### 3. Create the tunnel
|
||||
|
||||
```bash
|
||||
cloudflared tunnel create open-webui
|
||||
```
|
||||
|
||||
Note the **Tunnel ID** in the output. You'll need it for the config.
|
||||
|
||||
### 4. Configure
|
||||
|
||||
Create `~/.cloudflared/config.yml`:
|
||||
|
||||
```yaml
|
||||
tunnel: YOUR_TUNNEL_ID
|
||||
credentials-file: /home/YOUR_USER/.cloudflared/YOUR_TUNNEL_ID.json
|
||||
|
||||
ingress:
|
||||
- hostname: chat.your-domain.com
|
||||
service: http://localhost:8080
|
||||
- service: http_status:404
|
||||
```
|
||||
|
||||
### 5. Create DNS record
|
||||
|
||||
```bash
|
||||
cloudflared tunnel route dns open-webui chat.your-domain.com
|
||||
```
|
||||
|
||||
### 6. Start the tunnel
|
||||
|
||||
```bash
|
||||
cloudflared tunnel run open-webui
|
||||
```
|
||||
|
||||
Open `https://chat.your-domain.com`.
|
||||
|
||||
---
|
||||
|
||||
## Run as a system service
|
||||
|
||||
To keep the tunnel running after reboot:
|
||||
|
||||
```bash
|
||||
sudo cloudflared service install
|
||||
sudo systemctl enable cloudflared
|
||||
sudo systemctl start cloudflared
|
||||
```
|
||||
|
||||
This uses the config at `~/.cloudflared/config.yml` automatically.
|
||||
|
||||
---
|
||||
|
||||
## Configure Open WebUI
|
||||
|
||||
Set `WEBUI_URL` so OAuth callbacks and internal links resolve correctly:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 8080:8080 \
|
||||
-e WEBUI_URL=https://chat.your-domain.com \
|
||||
-v open-webui:/app/backend/data \
|
||||
--name open-webui \
|
||||
ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker Compose with cloudflared
|
||||
|
||||
Run both Open WebUI and the tunnel connector in a single stack:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
open-webui:
|
||||
image: ghcr.io/open-webui/open-webui:main
|
||||
container_name: open-webui
|
||||
volumes:
|
||||
- open-webui:/app/backend/data
|
||||
environment:
|
||||
- WEBUI_URL=https://chat.your-domain.com
|
||||
restart: unless-stopped
|
||||
|
||||
cloudflared:
|
||||
image: cloudflare/cloudflared:latest
|
||||
container_name: cloudflared
|
||||
command: tunnel --no-autoupdate run --token YOUR_TUNNEL_TOKEN
|
||||
restart: unless-stopped
|
||||
|
||||
volumes:
|
||||
open-webui:
|
||||
```
|
||||
|
||||
Get your tunnel token from the [Cloudflare dashboard](https://one.dash.cloudflare.com/networks/tunnels) → select your tunnel → **Configure** → copy the token from the install command.
|
||||
|
||||
:::tip
|
||||
No `ports` needed on the `open-webui` service. `cloudflared` connects to it via Docker's internal network. To use this, change the service URL in your tunnel config to `http://open-webui:8080`.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Add access controls (optional)
|
||||
|
||||
Cloudflare Zero Trust lets you gate access behind authentication without touching Open WebUI:
|
||||
|
||||
1. Go to [**Zero Trust → Access → Applications**](https://one.dash.cloudflare.com/access/apps)
|
||||
2. **Add an application** → Self-hosted
|
||||
3. Set the domain to `chat.your-domain.com`
|
||||
4. Create an **Access Policy** (e.g., allow only `@your-company.com` emails)
|
||||
|
||||
Users see a Cloudflare login page before reaching Open WebUI.
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
| What | Command / Value |
|
||||
| :--- | :--- |
|
||||
| Create tunnel | `cloudflared tunnel create open-webui` |
|
||||
| Start tunnel | `cloudflared tunnel run open-webui` |
|
||||
| Add DNS | `cloudflared tunnel route dns open-webui chat.your-domain.com` |
|
||||
| Install as service | `sudo cloudflared service install` |
|
||||
| Dashboard | [one.dash.cloudflare.com/networks/tunnels](https://one.dash.cloudflare.com/networks/tunnels) |
|
||||
| Set CORS origin | `CORS_ALLOW_ORIGIN=https://chat.your-domain.com` |
|
||||
@@ -3,38 +3,48 @@ sidebar_position: 6
|
||||
title: "HTTPS & Reverse Proxies"
|
||||
---
|
||||
|
||||
# Secure Your Open WebUI with HTTPS 🔒
|
||||
# HTTPS & Reverse Proxies
|
||||
|
||||
While **HTTPS is not strictly required** for basic local operation, it is **highly recommended** for all deployments and **mandatory** for enabling specific features like Voice Calls.
|
||||
**Secure your Open WebUI deployment with TLS encryption, reverse proxies, or managed tunnels.**
|
||||
|
||||
:::warning Critical Feature Dependency
|
||||
Modern browsers require a **Secure Context** (HTTPS) to access the microphone.
|
||||
**Voice Calls will NOT work** if you access Open WebUI via `http://` (unless using `localhost`).
|
||||
HTTPS encrypts all traffic between users and Open WebUI, protecting chat history, credentials, and uploaded files. It is also **required** for browser features like Voice Calls, which need a secure context to access the microphone.
|
||||
|
||||
:::warning Voice Calls require HTTPS
|
||||
Modern browsers block microphone access on non-HTTPS origins. **Voice Calls will not work** over plain `http://` unless you are on `localhost`.
|
||||
:::
|
||||
|
||||
## Why HTTPS Matters 🛡️
|
||||
---
|
||||
|
||||
Enabling HTTPS encryption provides essential benefits:
|
||||
## Choose your approach
|
||||
|
||||
1. **🔒 Privacy & Security**: Encrypts all data between the user and the server, protecting chat history and credentials.
|
||||
2. **🎤 Feature Unlocking**: Enables browser restrictions for Microphone (Voice Mode) and Camera access.
|
||||
3. **💪 Integrity**: Ensures data is not tampered with in transit.
|
||||
4. **✅ Trust**: Displays the padlock icon, reassuring users that the service is secure.
|
||||
| Method | Best for | TLS management |
|
||||
| :--- | :--- | :--- |
|
||||
| [**Cloudflare Tunnel**](./cloudflare-tunnel) | Production without open ports | Automatic (Cloudflare edge) |
|
||||
| [**ngrok**](./ngrok) | Development and testing | Automatic (ngrok edge) |
|
||||
| [**Tailscale**](./tailscale) | Private access across devices | Automatic (tailscale serve) |
|
||||
| [**Nginx**](./nginx) | Self-hosted production with full control | Manual or Let's Encrypt |
|
||||
| [**Caddy**](./caddy) | Self-hosted production, minimal config | Automatic (Let's Encrypt) |
|
||||
| [**HAProxy**](./haproxy) | High-availability / load balancing | Manual or Let's Encrypt |
|
||||
| **Cloud load balancers** | AWS ALB, GCP LB, Azure App Gateway | Managed by cloud provider |
|
||||
|
||||
## Choosing Your Solution 🛠️
|
||||
---
|
||||
|
||||
The best method depends on your infrastructure.
|
||||
## Quick recommendations
|
||||
|
||||
### 🏠 For Local/Docker Users
|
||||
If you are running Open WebUI with Docker, the standard approach is to use a **Reverse Proxy**. This sits in front of Open WebUI and handles the SSL encryption.
|
||||
- **Just want HTTPS fast?** Use [Cloudflare Tunnel](./cloudflare-tunnel) (production) or [ngrok](./ngrok) (development). No certificates to manage, no ports to open.
|
||||
- **Running a reverse proxy already?** Add [Caddy](./caddy) for automatic certs or [Nginx](./nginx) for maximum control.
|
||||
- **Need load balancing?** Use [HAProxy](./haproxy) or your cloud provider's load balancer.
|
||||
|
||||
* **[Nginx](./nginx)**: The industry standard. Highly configurable, great performance.
|
||||
* **[Caddy](./caddy)**: **Easiest option**. Automatically obtains and renews Let's Encrypt certificates with minimal config.
|
||||
* **[HAProxy](./haproxy)**: Robust choice for advanced load balancing needs.
|
||||
---
|
||||
|
||||
### ☁️ For Cloud Deployments
|
||||
* **Cloud Load Balancers**: (AWS ALB, Google Cloud Load Balancing) often handle SSL termination natively.
|
||||
* **Cloudflare Tunnel**: Excellent for exposing localhost to the web securely without opening ports.
|
||||
## Key configuration notes
|
||||
|
||||
### 🧪 For Development
|
||||
* **Ngrok**: Good for quickly testing Voice features locally. *Not for production.*
|
||||
Regardless of which approach you choose, keep these in mind:
|
||||
|
||||
| Setting | Why it matters |
|
||||
| :--- | :--- |
|
||||
| `WEBUI_URL` | Set this to your public HTTPS URL so OAuth callbacks and internal links resolve correctly |
|
||||
| `CORS_ALLOW_ORIGIN` | Must match your public URL, or WebSocket connections will fail silently |
|
||||
| Proxy buffering **off** | Required for SSE streaming. Buffering breaks markdown rendering in chat responses |
|
||||
| WebSocket support | Ensure your proxy passes `Upgrade` and `Connection` headers for real-time features |
|
||||
| Extended timeouts | LLM responses can take minutes. Set proxy read timeouts to at least 300s |
|
||||
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: "HTTPS using ngrok"
|
||||
---
|
||||
|
||||
# HTTPS using ngrok
|
||||
|
||||
**Instant public HTTPS for your local Open WebUI. Zero config, zero open ports.**
|
||||
|
||||
ngrok creates a secure tunnel from a public URL to your local machine. It's the fastest way to get HTTPS working for development, demos, or testing features that require a secure context (like Voice Calls).
|
||||
|
||||
:::tip When to use ngrok
|
||||
ngrok is ideal for **development and testing**. For production deployments, use a reverse proxy like [Nginx](/reference/https/nginx) or [Caddy](/reference/https/caddy), or a [Cloudflare Tunnel](/reference/https/cloudflare-tunnel) for zero-trust access.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Details |
|
||||
| :--- | :--- |
|
||||
| **Open WebUI** | Running locally on port `8080` (default) |
|
||||
| **ngrok account** | Free at [ngrok.com](https://ngrok.com), provides a stable authtoken |
|
||||
|
||||
---
|
||||
|
||||
## 1. Install ngrok
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="mac" label="macOS" default>
|
||||
|
||||
```bash
|
||||
brew install ngrok
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```bash
|
||||
curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok-v3-stable-linux-amd64.tgz \
|
||||
| sudo tar xz -C /usr/local/bin
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
```powershell
|
||||
choco install ngrok
|
||||
```
|
||||
|
||||
Or download directly from [ngrok.com/download](https://ngrok.com/download).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 2. Authenticate
|
||||
|
||||
```bash
|
||||
ngrok config add-authtoken YOUR_AUTH_TOKEN
|
||||
```
|
||||
|
||||
Find your authtoken at [dashboard.ngrok.com/get-started/your-authtoken](https://dashboard.ngrok.com/get-started/your-authtoken).
|
||||
|
||||
## 3. Start the tunnel
|
||||
|
||||
```bash
|
||||
ngrok http 8080
|
||||
```
|
||||
|
||||
ngrok outputs a public URL like:
|
||||
|
||||
```
|
||||
Forwarding https://a1b2-203-0-113-42.ngrok-free.app → http://localhost:8080
|
||||
```
|
||||
|
||||
Open that `https://` URL in your browser. You're done.
|
||||
|
||||
---
|
||||
|
||||
## Configure Open WebUI
|
||||
|
||||
Set `WEBUI_URL` so OAuth callbacks and internal links resolve correctly:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 8080:8080 \
|
||||
-e WEBUI_URL=https://a1b2-203-0-113-42.ngrok-free.app \
|
||||
-v open-webui:/app/backend/data \
|
||||
--name open-webui \
|
||||
ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
:::warning
|
||||
ngrok free-tier URLs change every time you restart the tunnel. Update `WEBUI_URL` accordingly, or use a [ngrok custom domain](https://ngrok.com/docs/guides/how-to-set-up-a-custom-domain/) (paid) for a stable URL.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Custom domain (optional)
|
||||
|
||||
With a paid ngrok plan, claim a fixed subdomain so your URL never changes:
|
||||
|
||||
```bash
|
||||
ngrok http 8080 --url=your-name.ngrok-free.app
|
||||
```
|
||||
|
||||
This gives you a permanent URL you can set once in `WEBUI_URL` and forget.
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
| What | Command / Value |
|
||||
| :--- | :--- |
|
||||
| Start tunnel | `ngrok http 8080` |
|
||||
| Custom domain | `ngrok http 8080 --url=your-name.ngrok-free.app` |
|
||||
| Dashboard | [dashboard.ngrok.com](https://dashboard.ngrok.com) |
|
||||
| Inspect traffic | `http://localhost:4040` (ngrok's local inspector) |
|
||||
| Set CORS origin | `CORS_ALLOW_ORIGIN=https://your-name.ngrok-free.app` |
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
| Concern | Detail |
|
||||
| :--- | :--- |
|
||||
| **Free-tier URLs rotate** | URL changes on every restart unless you use a custom domain |
|
||||
| **Interstitial warning** | Free-tier shows an ngrok splash page on first visit |
|
||||
| **Not for production** | ngrok adds latency and is a single point of failure; use a reverse proxy or Cloudflare Tunnel instead |
|
||||
| **Rate limits** | Free tier has connection rate limits; paid plans remove them |
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "HTTPS using Tailscale"
|
||||
---
|
||||
|
||||
# HTTPS using Tailscale
|
||||
|
||||
**Access Open WebUI securely from anywhere on your private network. No ports, no certificates, no public exposure.**
|
||||
|
||||
Tailscale creates an encrypted mesh VPN (a "tailnet") between your devices. Every device gets a stable hostname like `my-server.tail1234.ts.net`, and Tailscale can provision trusted HTTPS certificates for it automatically. Your Open WebUI instance stays completely private, accessible only to devices on your tailnet.
|
||||
|
||||
:::tip When to use Tailscale
|
||||
Tailscale is ideal when you want **private, authenticated access** across devices without exposing Open WebUI to the public internet. Perfect for personal setups, small teams, or accessing a home server from your phone or laptop on the go.
|
||||
:::
|
||||
|
||||
:::info Looking for the full guide?
|
||||
This page covers **HTTPS setup** specifically. For the complete Tailscale integration story, including SSO authentication, Docker Compose sidecar setup, and more, see the [**Tailscale Integration Tutorial**](/tutorials/auth-sso/tailscale).
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Details |
|
||||
| :--- | :--- |
|
||||
| **Open WebUI** | Running locally on port `8080` (default) |
|
||||
| **Tailscale account** | Free for personal use at [tailscale.com](https://tailscale.com) |
|
||||
| **Tailscale installed** | On both the server running Open WebUI and any client devices |
|
||||
|
||||
---
|
||||
|
||||
## 1. Install Tailscale
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="mac" label="macOS" default>
|
||||
|
||||
Download from the [Mac App Store](https://apps.apple.com/app/tailscale/id1475387142) or:
|
||||
|
||||
```bash
|
||||
brew install tailscale
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```bash
|
||||
curl -fsSL https://tailscale.com/install.sh | sh
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
Download from [tailscale.com/download](https://tailscale.com/download/windows).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 2. Connect the server
|
||||
|
||||
On the machine running Open WebUI:
|
||||
|
||||
```bash
|
||||
sudo tailscale up
|
||||
```
|
||||
|
||||
Your machine gets a tailnet hostname like `my-server.tail1234.ts.net`. Find it with:
|
||||
|
||||
```bash
|
||||
tailscale status
|
||||
```
|
||||
|
||||
## 3. Access Open WebUI
|
||||
|
||||
From any device on the same tailnet, open:
|
||||
|
||||
```
|
||||
http://my-server.tail1234.ts.net:8080
|
||||
```
|
||||
|
||||
This connection is already encrypted end-to-end by WireGuard. For browser features that require HTTPS (like Voice Calls), continue to the next step.
|
||||
|
||||
---
|
||||
|
||||
## Enable HTTPS with Tailscale certificates
|
||||
|
||||
Tailscale can provision trusted Let's Encrypt certificates for your tailnet hostname.
|
||||
|
||||
### 1. Enable HTTPS in the admin console
|
||||
|
||||
Go to [**Tailscale Admin → DNS**](https://login.tailscale.com/admin/dns) and enable **HTTPS Certificates**.
|
||||
|
||||
### 2. Generate a certificate
|
||||
|
||||
```bash
|
||||
sudo tailscale cert my-server.tail1234.ts.net
|
||||
```
|
||||
|
||||
This creates two files in the current directory:
|
||||
- `my-server.tail1234.ts.net.crt` (certificate)
|
||||
- `my-server.tail1234.ts.net.key` (private key)
|
||||
|
||||
### 3. Serve Open WebUI over HTTPS
|
||||
|
||||
Use `tailscale serve` to proxy HTTPS traffic directly to Open WebUI without any reverse proxy:
|
||||
|
||||
```bash
|
||||
sudo tailscale serve https / http://localhost:8080
|
||||
```
|
||||
|
||||
Now access Open WebUI at:
|
||||
|
||||
```
|
||||
https://my-server.tail1234.ts.net
|
||||
```
|
||||
|
||||
No port number needed. Tailscale handles TLS termination and proxies to your local Open WebUI.
|
||||
|
||||
---
|
||||
|
||||
## Configure Open WebUI
|
||||
|
||||
Set `WEBUI_URL` so OAuth callbacks and internal links resolve correctly:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 8080:8080 \
|
||||
-e WEBUI_URL=https://my-server.tail1234.ts.net \
|
||||
-v open-webui:/app/backend/data \
|
||||
--name open-webui \
|
||||
ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tailscale Funnel (optional public access)
|
||||
|
||||
If you want to share Open WebUI publicly (without requiring Tailscale on the client), Tailscale Funnel exposes your `tailscale serve` endpoint to the internet:
|
||||
|
||||
```bash
|
||||
sudo tailscale funnel https / http://localhost:8080
|
||||
```
|
||||
|
||||
Your Open WebUI is now publicly accessible at `https://my-server.tail1234.ts.net` with a valid TLS certificate. Funnel routes traffic through Tailscale's infrastructure, similar to Cloudflare Tunnel.
|
||||
|
||||
:::warning
|
||||
Funnel makes your Open WebUI accessible to anyone on the internet. Make sure you have authentication configured in Open WebUI before enabling it.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
| What | Command / Value |
|
||||
| :--- | :--- |
|
||||
| Connect to tailnet | `sudo tailscale up` |
|
||||
| Check hostname | `tailscale status` |
|
||||
| Serve over HTTPS | `sudo tailscale serve https / http://localhost:8080` |
|
||||
| Public access (Funnel) | `sudo tailscale funnel https / http://localhost:8080` |
|
||||
| Generate cert manually | `sudo tailscale cert my-server.tail1234.ts.net` |
|
||||
| Admin console | [login.tailscale.com/admin](https://login.tailscale.com/admin) |
|
||||
| Set CORS origin | `CORS_ALLOW_ORIGIN=https://my-server.tail1234.ts.net` |
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
sidebar_position: 150
|
||||
title: "📖 Reference"
|
||||
---
|
||||
|
||||
# Reference
|
||||
|
||||
**The technical details behind every knob, endpoint, and configuration option.**
|
||||
|
||||
Open WebUI is highly configurable. This section is the canonical source of truth for environment variables, API endpoints, network architecture, reverse proxy setups, and production monitoring. Whether you're tuning a single setting or architecting a multi-node deployment, start here.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Environment Variable Configuration
|
||||
|
||||
**Every flag, path, and secret Open WebUI reads at startup, in one place.**
|
||||
|
||||
Over 200 environment variables control authentication, model routing, storage, logging, and more. Understand `PersistentConfig` behavior, troubleshoot ignored settings, and find the exact variable you need.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🔐 **Authentication & signup** | `ENABLE_SIGNUP`, `ENABLE_LOGIN_FORM`, `WEBUI_ADMIN_EMAIL`, OIDC/LDAP/SCIM |
|
||||
| 🤖 **Model connections** | Ollama, OpenAI, direct pipeline URLs, timeouts, load balancing |
|
||||
| 💾 **Storage & databases** | SQLite, PostgreSQL, S3/GCS/Azure Blob, Redis |
|
||||
| 📊 **Logging & audit** | `GLOBAL_LOG_LEVEL`, JSON logging, audit log levels and paths |
|
||||
| 🧠 **RAG & retrieval** | Chunk size, overlap, embedding engines, reranking, vector DB selection |
|
||||
|
||||
[**Browse all environment variables →**](/reference/env-configuration)
|
||||
|
||||
---
|
||||
|
||||
## 🔌 API Endpoints
|
||||
|
||||
**OpenAI-compatible and Anthropic-compatible APIs, plus RAG, file management, and Ollama proxy routes.**
|
||||
|
||||
Open WebUI exposes a full REST API authenticated via Bearer tokens or JWTs. Use the same endpoints the web UI uses to build automations, chatbots, and custom integrations.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 💬 **Chat completions** | `POST /api/chat/completions`, OpenAI-compatible |
|
||||
| 🔮 **Anthropic messages** | `POST /api/v1/messages`, works with the Anthropic SDK and Claude Code |
|
||||
| 🦙 **Ollama proxy** | `/ollama/api/*`, passthrough to native Ollama endpoints |
|
||||
| 📄 **File & knowledge** | Upload files, build knowledge collections, query via RAG |
|
||||
| 🔧 **Filters & outlets** | Inlet, stream, and outlet hooks for every request |
|
||||
|
||||
[**Explore the API →**](/reference/api-endpoints)
|
||||
|
||||
---
|
||||
|
||||
## 🔒 HTTPS Configuration
|
||||
|
||||
**Terminate TLS in front of Open WebUI with Nginx, Caddy, or HAProxy.**
|
||||
|
||||
Step-by-step reverse proxy configurations for securing your deployment with HTTPS. Each guide includes certificate handling, WebSocket support, and production-hardened settings.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🟢 **Nginx** | Full config with SSL termination, WebSocket proxying, and headers |
|
||||
| ⚡ **Caddy** | Automatic HTTPS with minimal configuration |
|
||||
| 🔄 **HAProxy** | Enterprise-grade load balancing with TLS offloading |
|
||||
| ☁️ **Cloudflare Tunnel** | Expose Open WebUI securely without opening ports |
|
||||
| 🔒 **Tailscale** | Private encrypted access across your devices, no public exposure |
|
||||
| 🧪 **ngrok** | Instant HTTPS tunnels for development and testing |
|
||||
|
||||
[**Set up HTTPS →**](/reference/https)
|
||||
|
||||
---
|
||||
|
||||
## 🔑 API Keys
|
||||
|
||||
**Programmatic access to Open WebUI for scripts, bots, and integrations.**
|
||||
|
||||
Generate personal access tokens that let external code call the same endpoints the web UI uses. Each key inherits the permissions of the user who created it.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🔐 **Bearer token auth** | Standard `Authorization: Bearer` header, works with any HTTP client |
|
||||
| 🛡️ **Scoped to user** | Key inherits your role and group permissions |
|
||||
| 🚫 **Endpoint restrictions** | Optionally limit which API routes a key can access |
|
||||
|
||||
[**Set up API keys →**](/features/authentication-access/api-keys)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
**Observe your deployment with Uptime Kuma, OpenTelemetry, Prometheus, and Grafana.**
|
||||
|
||||
Production monitoring guides covering health checks, model connectivity verification, distributed tracing, metrics, and structured logs. Integrate with your existing observability stack or set up a new one from scratch.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| ✅ **Health checks** | Basic, model connectivity, and deep health checks with Uptime Kuma |
|
||||
| 📡 **OpenTelemetry** | Traces, metrics, and logs piped to any OTLP-compatible backend |
|
||||
| 📈 **Dashboards** | Prometheus + Grafana for real-time system and model metrics |
|
||||
|
||||
[**Set up monitoring →**](/reference/monitoring)
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Network Diagrams
|
||||
|
||||
**See how Open WebUI, Ollama, and Docker communicate across different deployment topologies.**
|
||||
|
||||
Visual C4 diagrams covering host networking, Docker Compose stacks, separate networks, and platform-specific differences. Useful for debugging connectivity issues or planning your architecture.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🖥️ **macOS / Windows** | Host Ollama, Compose stack, separate networks, host-network pitfalls |
|
||||
| 🐧 **Linux** | Same topologies with Linux-specific networking behavior |
|
||||
|
||||
[**View network diagrams →**](/reference/network-diagrams)
|
||||
@@ -1,253 +1,123 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
title: "API Keys & Monitoring"
|
||||
title: "Monitoring"
|
||||
---
|
||||
|
||||
# API Keys & Monitoring Your Open WebUI 🔑🩺
|
||||
# 📊 Monitoring
|
||||
|
||||
This guide covers two essential topics: setting up API keys for programmatic access to Open WebUI, and monitoring your instance to ensure reliability and performance.
|
||||
**Know when something breaks before your users do.**
|
||||
|
||||
**Why Monitor?**
|
||||
Open WebUI exposes health and model endpoints that make it straightforward to wire up uptime monitoring, model connectivity checks, and end-to-end response testing. Whether you're running a single instance or a multi-node deployment, these checks give you confidence that the service is up, models are reachable, and inference is actually working.
|
||||
|
||||
- **Ensure Uptime:** Proactively detect outages and service disruptions.
|
||||
- **Performance Insights:** Track response times and identify potential bottlenecks.
|
||||
- **Early Issue Detection:** Catch problems before they impact users significantly.
|
||||
- **Peace of Mind:** Gain confidence that your Open WebUI instance is running smoothly.
|
||||
---
|
||||
|
||||
## 🚦 Levels of Monitoring
|
||||
## Why Monitor?
|
||||
|
||||
We'll cover three levels of monitoring, progressing from basic to more comprehensive:
|
||||
### Catch outages instantly
|
||||
|
||||
1. **Basic Health Check:** Verifies if the Open WebUI service is running and responding.
|
||||
2. **Model Connectivity Check:** Confirms that Open WebUI can connect to and list your configured models.
|
||||
3. **Model Response Testing (Deep Health Check):** Ensures that models can actually process requests and generate responses.
|
||||
A health check that runs every 60 seconds means you know about downtime within a minute, not when a user files a complaint.
|
||||
|
||||
## Level 1: Basic Health Check Endpoint ✅
|
||||
### Verify model connectivity
|
||||
|
||||
The simplest level of monitoring is checking the `/health` endpoint. This endpoint is publicly accessible (no authentication required) and returns a `200 OK` status code when the Open WebUI service is running correctly.
|
||||
Open WebUI can be running fine while your model provider is down. Monitoring the `/api/models` endpoint catches that gap.
|
||||
|
||||
**How to Test:**
|
||||
### End-to-end confidence
|
||||
|
||||
You can use `curl` or any HTTP client to check this endpoint:
|
||||
The deepest check sends a real prompt and validates the response. If that passes, you know the entire pipeline works: API, backend, model provider, and inference.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| ✅ **Health endpoint** | Unauthenticated `/health` check, returns `200` when the service is up |
|
||||
| 🔗 **Model connectivity** | Authenticated `/api/models` check verifies provider connections |
|
||||
| 🤖 **Deep health check** | Send a real chat completion and validate the response |
|
||||
| 🐻 **Uptime Kuma recipes** | Ready-to-use configurations for each monitoring level |
|
||||
|
||||
---
|
||||
|
||||
## Level 1: Basic Health Check
|
||||
|
||||
The `/health` endpoint is publicly accessible (no authentication required) and returns `200 OK` when the service is running.
|
||||
|
||||
```bash
|
||||
# Basic health check - no authentication needed
|
||||
curl https://your-open-webui-instance/health
|
||||
curl http://your-open-webui-instance:8080/health
|
||||
```
|
||||
|
||||
**Expected Output:** A successful health check will return a `200 OK` HTTP status code. The content of the response body is usually not important for a basic health check.
|
||||
This verifies web server availability, application initialization, and basic database connectivity.
|
||||
|
||||
### Using Uptime Kuma for Basic Health Checks 🐻
|
||||
### Uptime Kuma Setup
|
||||
|
||||
[Uptime Kuma](https://github.com/louislam/uptime-kuma) is a fantastic, open-source, and easy-to-use self-hosted uptime monitoring tool. It's highly recommended for monitoring Open WebUI.
|
||||
1. **Add New Monitor** with type **HTTP(s)**
|
||||
2. **URL:** `http://your-open-webui-instance:8080/health`
|
||||
3. **Interval:** `60 seconds`
|
||||
4. **Retries:** `3`
|
||||
|
||||
**Steps to Set Up in Uptime Kuma:**
|
||||
---
|
||||
|
||||
1. **Add a New Monitor:** In your Uptime Kuma dashboard, click "Add New Monitor".
|
||||
2. **Configure Monitor Settings:**
|
||||
- **Monitor Type:** Select "HTTP(s)".
|
||||
- **Name:** Give your monitor a descriptive name, e.g., "Open WebUI Health Check".
|
||||
- **URL:** Enter the health check endpoint URL: `http://your-open-webui-instance:8080/health` (Replace `your-open-webui-instance:8080` with your actual Open WebUI address and port).
|
||||
- **Monitoring Interval:** Set the frequency of checks (e.g., `60 seconds` for every minute).
|
||||
- **Retry Count:** Set the number of retries before considering the service down (e.g., `3` retries).
|
||||
## Level 2: Model Connectivity Check
|
||||
|
||||
**What This Check Verifies:**
|
||||
|
||||
- **Web Server Availability:** Ensures the web server (e.g., Nginx, Uvicorn) is responding to requests.
|
||||
- **Application Running:** Confirms that the Open WebUI application itself is running and initialized.
|
||||
- **Basic Database Connectivity:** Typically includes a basic check to ensure the application can connect to the database.
|
||||
|
||||
## Level 2: Open WebUI Model Connectivity 🔗
|
||||
|
||||
To go beyond basic availability, you can monitor the `/api/models` endpoint. This endpoint **requires authentication** and verifies that Open WebUI can successfully communicate with your configured model providers (e.g., Ollama, OpenAI) and retrieve a list of available models.
|
||||
|
||||
**Why Monitor Model Connectivity?**
|
||||
|
||||
- **Model Provider Issues:** Detect problems with your model provider services (e.g., API outages, authentication failures).
|
||||
- **Configuration Errors:** Identify misconfigurations in your model provider settings within Open WebUI.
|
||||
- **Ensure Model Availability:** Confirm that the models you expect to be available are actually accessible to Open WebUI.
|
||||
|
||||
**API Endpoint Details:**
|
||||
|
||||
See the [Open WebUI API documentation](https://docs.openwebui.com/reference/api-endpoints/#-retrieve-all-models) for full details about the `/api/models` endpoint and its response structure.
|
||||
|
||||
**How to Test with `curl` (Authenticated):**
|
||||
|
||||
You'll need an API key to access this endpoint. See the "Authentication Setup" section below for instructions on generating an API key.
|
||||
The `/api/models` endpoint **requires authentication** and confirms that Open WebUI can reach your model providers and list available models.
|
||||
|
||||
```bash
|
||||
# Authenticated model connectivity check
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" https://your-open-webui-instance/api/models
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
http://your-open-webui-instance:8080/api/models
|
||||
```
|
||||
|
||||
*(Replace `YOUR_API_KEY` with your actual API key and `your-open-webui-instance` with your Open WebUI address.)*
|
||||
|
||||
**Expected Output:** A successful request will return a `200 OK` status code and a JSON response containing a list of models.
|
||||
|
||||
### Authentication Setup for API Key 🔑
|
||||
|
||||
Before you can monitor the `/api/models` endpoint, you need to configure API keys in Open WebUI. API key creation requires that the global API keys feature is enabled. For non-admin users, API key creation also requires the API Keys feature permission.
|
||||
|
||||
#### Step 1: Enable API Keys Globally (Admin Required)
|
||||
|
||||
1. Log in to Open WebUI as an **administrator**.
|
||||
2. Click on your **profile icon** in the bottom-left corner of the sidebar, then select **Admin Panel**.
|
||||
3. Navigate to **Settings** > **General**.
|
||||
4. Scroll down to the **Authentication** section.
|
||||
5. Find the **"Enable API Keys"** toggle and **turn it ON**.
|
||||
6. *(Optional)* Configure additional API key restrictions:
|
||||
- **API Key Endpoint Restrictions**: Enable this to limit which endpoints can be accessed via API keys.
|
||||
- **Allowed Endpoints**: Specify a comma-separated list of allowed endpoints (e.g., `/api/v1/models,/api/v1/chat/completions`).
|
||||
7. Click **Save** at the bottom of the page.
|
||||
|
||||
:::info
|
||||
|
||||
This enables the API key feature globally.
|
||||
|
||||
- Admin users can now generate API keys immediately.
|
||||
- Non-admin users still require API Keys permission (configured in Step 2).
|
||||
You'll need an API key. See [API Keys](/features/authentication-access/api-keys) for setup instructions.
|
||||
|
||||
:::tip Dedicated Monitoring Account
|
||||
Create a **non-admin user** (e.g., `monitoring-bot`), generate an API key from that account, and use it for all monitoring requests. This limits blast radius if the key is ever compromised.
|
||||
:::
|
||||
|
||||
#### Step 2: Grant API Key Permission (Admin Required)
|
||||
### Uptime Kuma Setup
|
||||
|
||||
Non-admin users need explicit API Keys permission. Administrators can grant API key permissions for non-admin users using one of the following methods:
|
||||
1. **Monitor Type:** HTTP(s) - JSON Query
|
||||
2. **URL:** `http://your-open-webui-instance:8080/api/models`
|
||||
3. **Method:** GET
|
||||
4. **Header:** `Authorization: Bearer YOUR_API_KEY`
|
||||
5. **JSON Query:** `$count(data[*])>0`
|
||||
6. **Expected Value:** `true`
|
||||
7. **Interval:** `300 seconds` (5 minutes)
|
||||
|
||||
##### Option A: Grant Permission via Default Permissions
|
||||
### Advanced JSONata Queries
|
||||
|
||||
This grants the API Keys permission to **all users with the "user" role**:
|
||||
| Goal | Query |
|
||||
| :--- | :--- |
|
||||
| At least one Ollama model | `$count(data[owned_by='ollama'])>0` |
|
||||
| Specific model exists | `$exists(data[id='gpt-4o'])` |
|
||||
| Multiple models exist | `$count(data[id in ['gpt-4o', 'gpt-4o-mini']]) = 2` |
|
||||
|
||||
1. In the **Admin Panel**, navigate to **Users** > **Groups**.
|
||||
2. At the bottom of the Groups page, click on **"Default permissions"** (this applies to all users with the "user" role).
|
||||
3. In the modal that opens, scroll to the **Features Permissions** section.
|
||||
4. Find **"API Keys"** and **toggle it ON**.
|
||||
5. Click **Save**.
|
||||
Test queries at [jsonata.org](https://try.jsonata.org/) with a sample API response.
|
||||
|
||||
:::info
|
||||
---
|
||||
|
||||
**Note for Administrators:** "Default permissions" only applies to accounts with the "user" role. Admin accounts do not need `features.api_keys` to generate API keys, but you may still use groups to grant that permission to non-admin users.
|
||||
## Level 3: Deep Health Check
|
||||
|
||||
:::
|
||||
|
||||
:::warning
|
||||
|
||||
Enabling API Keys for all users means any user can generate API keys that provide programmatic access to Open WebUI with their account's permissions. Consider using User Groups (Option B) for more restrictive access control.
|
||||
|
||||
:::
|
||||
|
||||
##### Option B: Grant Permission via User Groups
|
||||
|
||||
For more granular control, you can grant API key permissions to specific user groups only:
|
||||
|
||||
1. In the **Admin Panel**, navigate to **Users** > **Groups**.
|
||||
2. Select the group you want to grant API key permissions to (or click the **+ button** to create a new group).
|
||||
3. In the group edit modal, click on the **Permissions** tab.
|
||||
4. Scroll to **Features Permissions**.
|
||||
5. Find **"API Keys"** and **toggle it ON**.
|
||||
6. Click **Save**.
|
||||
|
||||
:::tip
|
||||
|
||||
Create a dedicated monitoring group (e.g., "Monitoring Users") and add only the accounts that need API key access for monitoring purposes. This follows the principle of least privilege.
|
||||
|
||||
:::
|
||||
|
||||
#### Step 3: Generate an API Key (User Action)
|
||||
|
||||
Once global API keys are enabled (and for non-admin users, API Keys permission is granted):
|
||||
|
||||
1. Log in to Open WebUI with a user account that has API key permissions.
|
||||
2. Click on your **profile icon** in the bottom-left corner of the sidebar.
|
||||
3. Select **Settings** > **Account**.
|
||||
4. In the **API Keys** section, click **Generate New API Key**.
|
||||
5. Give the API key a descriptive name (e.g., "Monitoring API Key").
|
||||
6. **Copy the generated API key** immediately and store it securely—you won't be able to view it again.
|
||||
|
||||
:::warning
|
||||
|
||||
Treat your API key like a password! Store it securely and never share it publicly. If you suspect an API key has been compromised, delete it immediately and generate a new one.
|
||||
|
||||
:::
|
||||
|
||||
#### Recommended: Create a Dedicated Monitoring Account
|
||||
|
||||
For production monitoring, we recommend:
|
||||
|
||||
1. Create a **non-administrator user account** specifically for monitoring (e.g., "monitoring-bot").
|
||||
2. Add this account to a group with API key permissions (or ensure default permissions allow API key creation).
|
||||
3. Generate an API key from this account.
|
||||
|
||||
This approach limits the potential impact if the monitoring API key is compromised—the attacker would only have access to the permissions granted to that specific monitoring account, not administrator privileges.
|
||||
|
||||
#### Troubleshooting
|
||||
|
||||
If you don't see the API key generation option in your account settings:
|
||||
|
||||
- **Check global setting**: Verify that an administrator has enabled API keys globally under **Admin Panel** > **Settings** > **General** > **Enable API Keys**. See [`ENABLE_API_KEYS`](/reference/env-configuration#enable_api_keys).
|
||||
- **Check your permissions (non-admin users)**: Verify that your user account or group has been granted the "API Keys" feature permission under **Features Permissions**. See [`USER_PERMISSIONS_FEATURES_API_KEYS`](/reference/env-configuration#user_permissions_features_api_keys).
|
||||
|
||||
### Using Uptime Kuma for Model Connectivity Monitoring 🐻
|
||||
|
||||
1. **Create a New Monitor in Uptime Kuma:**
|
||||
- Monitor Type: "HTTP(s) - JSON Query".
|
||||
- Name: "Open WebUI Model Connectivity Check".
|
||||
- URL: `http://your-open-webui-instance:8080/api/models` (Replace with your URL).
|
||||
- Method: "GET".
|
||||
- Expected Status Code: `200`.
|
||||
|
||||
2. **Configure JSON Query (Verify Model List):**
|
||||
- **JSON Query:** `$count(data[*])>0`
|
||||
- **Explanation:** This JSONata query checks if the `data` array in the API response (which contains the list of models) has a count greater than 0. In other words, it verifies that at least one model is returned.
|
||||
- **Expected Value:** `true` (The query should return `true` if models are listed).
|
||||
|
||||
3. **Add Authentication Headers:**
|
||||
- In the "Headers" section of the Uptime Kuma monitor configuration, click "Add Header".
|
||||
- **Header Name:** `Authorization`
|
||||
- **Header Value:** `Bearer YOUR_API_KEY` (Replace `YOUR_API_KEY` with the API key you generated).
|
||||
|
||||
4. **Set Monitoring Interval:** Recommended interval: `300 seconds` (5 minutes) or longer, as model lists don't typically change very frequently.
|
||||
|
||||
**Alternative JSON Queries (Advanced):**
|
||||
|
||||
You can use more specific JSONata queries to check for particular models or providers. Here are some examples:
|
||||
|
||||
- **Check for at least one Ollama model:** `$count(data[owned_by='ollama'])>0`
|
||||
- **Check if a specific model exists (e.g., 'gpt-4o'):** `$exists(data[id='gpt-4o'])`
|
||||
- **Check if multiple specific models exist (e.g., 'gpt-4o' and 'gpt-4o-mini'):** `$count(data[id in ['gpt-4o', 'gpt-4o-mini']]) = 2`
|
||||
|
||||
You can test and refine your JSONata queries at [jsonata.org](https://try.jsonata.org/) using a sample API response to ensure they work as expected.
|
||||
|
||||
## Level 3: Model Response Testing (Deep Health Check) 🤖
|
||||
|
||||
For the most comprehensive monitoring, you can test if models are actually capable of processing requests and generating responses. This involves sending a simple chat completion request to the `/api/chat/completions` endpoint.
|
||||
|
||||
**Why Test Model Responses?**
|
||||
|
||||
- **End-to-End Verification:** Confirms that the entire model pipeline is working, from API request to model response.
|
||||
- **Model Loading Issues:** Detects problems with specific models failing to load or respond.
|
||||
- **Backend Processing Errors:** Catches errors in the backend logic that might prevent models from generating completions.
|
||||
|
||||
**How to Test with `curl` (Authenticated POST Request):**
|
||||
|
||||
This test requires an API key and sends a POST request with a simple message to the chat completions endpoint.
|
||||
Send a real chat completion to verify the entire inference pipeline end-to-end.
|
||||
|
||||
```bash
|
||||
|
||||
# Test model response - authenticated POST request
|
||||
curl -X POST https://your-open-webui-instance/api/chat/completions \
|
||||
curl -X POST http://your-open-webui-instance:8080/api/chat/completions \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"messages": [{"role": "user", "content": "Respond with the word HEALTHY"}],
|
||||
"model": "llama3.1", # Replace with a model you expect to be available
|
||||
"temperature": 0 # Set temperature to 0 for consistent responses
|
||||
"model": "llama3.1",
|
||||
"temperature": 0
|
||||
}'
|
||||
```
|
||||
|
||||
*(Replace `YOUR_API_KEY`, `your-open-webui-instance`, and `llama3.1` with your actual values.)*
|
||||
A successful response returns `200 OK` with a chat completion containing "HEALTHY". This catches model loading failures, backend processing errors, and provider-side issues that Levels 1 and 2 would miss.
|
||||
|
||||
**Expected Output:** A successful request will return a `200 OK` status code and a JSON response containing a chat completion. You can verify that the response includes the word "HEALTHY" (or a similar expected response based on your prompt).
|
||||
:::info
|
||||
Setting up Level 3 in Uptime Kuma requires an HTTP(s) monitor with a POST body, authentication headers, and a JSON query to validate the response. See [Uptime Kuma docs](https://github.com/louislam/uptime-kuma) for POST monitor configuration.
|
||||
:::
|
||||
|
||||
**Setting up Level 3 Monitoring in Uptime Kuma would involve configuring an HTTP(s) monitor with a POST request, JSON body, authentication headers, and potentially JSON query to validate the response content. This is a more advanced setup and can be customized based on your specific needs.**
|
||||
---
|
||||
|
||||
By implementing these monitoring levels, you can proactively ensure the health, reliability, and performance of your Open WebUI instance, providing a consistently positive experience for users.
|
||||
## Next Steps
|
||||
|
||||
- **[OpenTelemetry](/reference/monitoring/otel)** - Distributed tracing, metrics, and logs with Grafana, Prometheus, Jaeger, and more
|
||||
- **[API Keys](/features/authentication-access/api-keys)** - Full guide on enabling and generating API keys for programmatic access
|
||||
|
||||
@@ -1,15 +1,22 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
sidebar_position: 100
|
||||
title: "Network Diagrams"
|
||||
---
|
||||
|
||||
Here, we provide clear and structured diagrams to help you understand how various components of the network interact within different setups. This documentation is designed to assist both macOS/Windows and Linux users. Each scenario is illustrated using Mermaid diagrams to show how the interactions are set up depending on the different system configurations and deployment strategies.
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## Mac OS/Windows Setup Options 🖥️
|
||||
Visual C4 diagrams for common deployment topologies showing how Open WebUI, Ollama, and Docker communicate. Use these to debug connectivity issues or plan your architecture.
|
||||
|
||||
### Ollama on Host, Open WebUI in Container
|
||||
<Tabs groupId="os-platform">
|
||||
<TabItem value="macos-windows" label="macOS / Windows" default>
|
||||
|
||||
In this scenario, `Ollama` runs directly on the host machine while `Open WebUI` operates within a Docker container.
|
||||
<Tabs groupId="macos-topology">
|
||||
<TabItem value="host-ollama-mac" label="Host Ollama" default>
|
||||
|
||||
#### Ollama on Host, Open WebUI in Container
|
||||
|
||||
`Ollama` runs directly on the host machine while `Open WebUI` operates within a Docker container.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -25,7 +32,10 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Ollama and Open WebUI in Compose Stack
|
||||
</TabItem>
|
||||
<TabItem value="compose-stack-mac" label="Compose Stack">
|
||||
|
||||
#### Ollama and Open WebUI in Compose Stack
|
||||
|
||||
Both `Ollama` and `Open WebUI` are configured within the same Docker Compose stack, simplifying network communications.
|
||||
|
||||
@@ -45,9 +55,12 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Ollama and Open WebUI, Separate Networks
|
||||
</TabItem>
|
||||
<TabItem value="separate-networks-mac" label="Separate Networks">
|
||||
|
||||
Here, `Ollama` and `Open WebUI` are deployed in separate Docker networks, potentially leading to connectivity issues.
|
||||
#### Ollama and Open WebUI, Separate Networks
|
||||
|
||||
`Ollama` and `Open WebUI` are deployed in separate Docker networks. This leads to connectivity issues.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -67,9 +80,12 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Open WebUI in Host Network
|
||||
</TabItem>
|
||||
<TabItem value="host-network-mac" label="Host Network">
|
||||
|
||||
In this configuration, `Open WebUI` utilizes the host network, which impacts its ability to connect in certain environments.
|
||||
#### Open WebUI in Host Network
|
||||
|
||||
`Open WebUI` utilizes the host network, which impacts its ability to connect in certain environments.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -83,11 +99,18 @@ Rel(user, openwebui, "Unable to connect, host network is the VM's network")
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
## Linux Setup Options 🐧
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Ollama on Host, Open WebUI in Container (Linux)
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
This diagram is specific to the Linux platform, with `Ollama` running on the host and `Open WebUI` deployed inside a Docker container.
|
||||
<Tabs groupId="linux-topology">
|
||||
<TabItem value="host-ollama-linux" label="Host Ollama" default>
|
||||
|
||||
#### Ollama on Host, Open WebUI in Container
|
||||
|
||||
`Ollama` runs on the host and `Open WebUI` is deployed inside a Docker container.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -103,9 +126,12 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Ollama and Open WebUI in Compose Stack (Linux)
|
||||
</TabItem>
|
||||
<TabItem value="compose-stack-linux" label="Compose Stack">
|
||||
|
||||
A set-up where both `Ollama` and `Open WebUI` reside within the same Docker Compose stack, allowing for straightforward networking on Linux.
|
||||
#### Ollama and Open WebUI in Compose Stack
|
||||
|
||||
Both `Ollama` and `Open WebUI` reside within the same Docker Compose stack, allowing for straightforward networking.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -123,9 +149,12 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Ollama and Open WebUI, Separate Networks (Linux)
|
||||
</TabItem>
|
||||
<TabItem value="separate-networks-linux" label="Separate Networks">
|
||||
|
||||
A scenario in which `Ollama` and `Open WebUI` are in different Docker networks under a Linux environment, which could hinder connectivity.
|
||||
#### Ollama and Open WebUI, Separate Networks
|
||||
|
||||
`Ollama` and `Open WebUI` are in different Docker networks, which can hinder connectivity.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -143,9 +172,12 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Open WebUI in Host Network, Ollama on Host (Linux)
|
||||
</TabItem>
|
||||
<TabItem value="host-network-linux" label="Host Network">
|
||||
|
||||
An optimal layout where both `Open WebUI` and `Ollama` use the host’s network, facilitating seamless interaction on Linux systems.
|
||||
#### Open WebUI in Host Network, Ollama on Host
|
||||
|
||||
Both `Open WebUI` and `Ollama` use the host's network, enabling seamless interaction.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -159,4 +191,8 @@ Rel(user, openwebui, "Makes requests via listening port", "http://localhost:8080
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
Each setup addresses different deployment strategies and networking configurations to help you choose the best layout for your requirements.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
+66
-62
@@ -3,69 +3,73 @@ sidebar_position: 1400
|
||||
title: "🛣️ Roadmap"
|
||||
---
|
||||
|
||||
# 🛣️ Roadmap
|
||||
|
||||
At Open WebUI, we're committed to continually enhancing our platform to provide the best experience for our users. Below, you'll find the structured roadmap for our ongoing and future developments, categorized into Interface, Information Retrieval, and Community.
|
||||
|
||||
## Interface 🖥️
|
||||
|
||||
Our roadmap for interface innovations aims to create a highly intuitive and accessible platform. These will not only improves user satisfaction but also enhance productivity by reducing the cognitive load on users.
|
||||
|
||||
- 📦 **Packaged Single Binary Executable**: Simplifying deployment and ensuring compatibility across different platforms, we aim to offer our interface as a single binary executable. This approach will facilitate effortless installation and updates, significantly enhancing usability for all users, especially those with limited technical expertise.
|
||||
|
||||
- 👤 **User Page**: A personal User Page feature where users can create posts. The functionality will also include features like followers, likes, and comments. This allows users to effectively share their model configurations, prompts, and files with a broader community, creating a richer, more connected ecosystem around the platform.
|
||||
|
||||
- 📝 **AI Powered Notes**: Inspired by tools like Notion and Obsidian, we plan to introduce a robust note-taking feature that includes AI integration. From simple note-taking to full-fledged document creation, this tool will offer a seamless experience, all locally integrated within the platform.
|
||||
|
||||
- 📈 **Advanced User Tracking and Cost Management Tools**: Users will gain access to comprehensive tools designed for tracking application performance and user activities, as well as managing costs effectively. These tools will empower users with the data they need to make informed decisions, improve user experiences, and maintain budget control, optimizing the use of resources across their AI applications.
|
||||
|
||||
- 🧠 **AI Workflow Tool**: A node-based tool to orchestrate and compose multiple aspects of AI systems. This tool will allow users to visually connect different AI modules and services, creating complex workflows with ease. It's designed to empower users to harness the full potential of AI without needing deep technical knowledge in AI programming.
|
||||
|
||||
- 🔊 **Local Text-to-Speech Integration**: This feature will allow natural language processing to convert text into lifelike spoken audio, thus making the platform more accessible, especially for visually impaired users. This integration helps in consuming information without screen interaction, facilitating multitasking and improving user engagement.
|
||||
|
||||
- 📣 **Wakeword Detection**: Incorporating hands-free operation through voice commands will not only enhance accessibility but also align with emerging trends in IoT and smart environments, making our platform future-ready.
|
||||
|
||||
- 💻 **Better Code Execution**: Enhancing coding functionalities within the platform supports a broad range of development activities, making it a one-stop solution for developers, thereby attracting a wider tech audience and fostering a robust developer community.
|
||||
|
||||
- 🤖 **Code Interpreter Function**: A flexible code interpreter embedded into the platform can support multiple programming languages, which reduces the dependency on external tools and streamlines the development process, increasing efficiency.
|
||||
|
||||
- 🔧 **Streamlined Fine-tune Support**: Open WebUI will offer a seamless fine-tuning process by allowing users to automatically build a fine-tune dataset simply by using the interface and rating the responses. We will provide Python notebooks to help preprocess your dataset, making it ready for fine-tuning directly from the notebook. This approach will be super simple and elegantly integrates fine-tuning into user workflows.
|
||||
|
||||
- ♿ **Accessibility Enhancements**: Making Open WebUI accessible to everyone matters deeply to us. We're actively advancing features that ensure people with diverse abilities can fully enjoy and benefit from our platform. Accessibility is not just a feature—it's a core value that shapes all our interface decisions. To help us achieve this, we're welcoming interested contributors who share this passion and have expertise in accessibility. If you believe you can help us create a more inclusive experience, please reach out at [careers@openwebui.com](mailto:careers@openwebui.com).
|
||||
|
||||
## Information Retrieval (RAG) 📚
|
||||
|
||||
Open WebUI currently provides an interface that enables the use of existing information retrieval (IR) models efficiency. However, we believe there is vast potential for improvement. We fully recognize the limitations of our current RAG (Retrieval-Augmented Generation) implementation in our WebUI, understanding that a one-size-fits-all approach does not effectively meet all users' needs.
|
||||
|
||||
To address this, we are committed to transforming our framework to be highly modular and extensively configurable. This new direction will enable users to tailor the information retrieval process to their specific requirements with ease, using a straightforward, interactive interface that allows for simple drag-and-drop customization. This refinement aims to significantly enhance user experience by providing a more adaptable and personalized IR setup.
|
||||
|
||||
Here's our focused plan for advancing our information retrieval capabilities:
|
||||
|
||||
- 🌐 **Customizable RAG Framework**: Envision a future where you can effortlessly tailor your IR setup via a user-friendly interface. This will include modular components that users can drag, drop, and configure without needing deep technical knowledge.
|
||||
|
||||
- 🔄 **Advanced Integration with SoTA Methods**: We aim to incorporate the latest developments in retrieval methods, enhancing accuracy and efficiency with advanced techniques and architectures.
|
||||
|
||||
- 🔍 **Dedicated R&D**: We’re scaling up our research and development to discover and integrate novel retrieval methods that push the boundaries of current methods, in collaboration with leading research entities.
|
||||
|
||||
## Community 🤝
|
||||
|
||||
We aim to create a vibrant community where everyone can contribute to and benefit from shared knowledge and developments:
|
||||
|
||||
- 🏆 **LLM Leaderboard**: A community-driven approach to evaluate and rank models ensures transparency and continuous improvement, leveraging real-world applications to benchmark performance instead of relying on standard datasets that might not reflect practical utility.
|
||||
|
||||
- 👥 **Sub-Communities**: Encouraging niche communities to curate datasets and optimize prompts can lead to better-tuned models, as these communities have specific insights and detailed feedback that typically go unnoticed in broader datasets.
|
||||
|
||||
🔗 **Community Whitepaper**: Explore our detailed strategy and join us in shaping the future of AI-driven platforms in our [whitepaper](https://openwebui.com/assets/files/whitepaper.pdf).
|
||||
|
||||
# Vision for the Future 🔭
|
||||
|
||||
Our relentless effort stems from a clear vision we hold dearly: enhancing your daily life, saving time and allowing for more focus on what truly matters.
|
||||
|
||||
Imagine a world where you think, and it happens. You desire a cup of coffee made exactly the way you love, and it's brewed for you. A world where you, simply think of a comprehensive data analysis report in a particular format, and it's done at the speed of your thought. The core idea is to turn the time-consuming, routine tasks over to our AI interface, freeing up your time and attention.
|
||||
|
||||
This isn’t a sci-fi future; together, we are working towards it right now. As our AI models gradually become more capable and intuitively understand your specific needs, your most mundane responsibilities become automated. Through this profound shift, our collective time allowance can be redistributed towards grand endeavours. Think space exploration, longevity research or simply extra moments with loved ones.
|
||||
|
||||
Creating this imagined future won't be a walk in the park, but with your help, we believe it's within our reach. Open WebUI is more than just tech - it's there to enhance your day, giving you more space for what's really important. Together, we're working on a brighter tomorrow. Thanks for joining us in this extraordinary journey.
|
||||
Open WebUI is building the AI interface that replaces everything else on your desktop. Here's where we're going.
|
||||
|
||||
---
|
||||
|
||||
Join us as we push the boundaries of technology with these ambitious and transformative features in our roadmap! 💡🚀 Your participation and feedback are crucial as we strive to make Open WebUI a pioneering tool in technology advancement.
|
||||
## 🔨 In Progress
|
||||
|
||||
### 🖥️ Desktop App
|
||||
|
||||
A dedicated desktop application with system-level integration. Global hotkeys, menu bar access, notification support, and instant launch. One download, double-click, running. No Docker, no Python, no terminal. Your AI assistant, always one keystroke away.
|
||||
|
||||
### 📈 Usage Tracking & Cost Management
|
||||
|
||||
Know exactly who's using what, how many tokens are flowing through each model, and what it's costing you. Per-user breakdowns, per-model analytics, and budget controls for teams that need to scale AI usage without surprises.
|
||||
|
||||
### ♿ Accessibility
|
||||
|
||||
Every release gets closer. Screen reader support, full keyboard navigation, ARIA compliance, high-contrast modes. AI should be for everyone, and we take that literally.
|
||||
|
||||
---
|
||||
|
||||
## 🔭 Planned
|
||||
|
||||
### 🧠 AI Workflow Builder
|
||||
|
||||
Drag, drop, and wire together models, tools, knowledge bases, and logic gates into multi-step AI pipelines. Think: "pull data from this API, run it through GPT-4, check the output against these rules, then post the result." All visual. No code required.
|
||||
|
||||
### ⏰ Scheduled Tasks & Automations
|
||||
|
||||
Set your AI to work while you sleep. Daily report generation, weekly data pulls, automated monitoring, recurring analysis. Define a workflow once and let it run on autopilot. Your AI doesn't need to wait for you to ask.
|
||||
|
||||
### 🔧 Integrated Fine-tuning
|
||||
|
||||
Your conversations and ratings become training data. Open WebUI will build fine-tune datasets from your actual usage, preprocess them, and hand you a ready-to-train package. Personalized models, built from how you already work. Your AI gets better the more you use it.
|
||||
|
||||
### 🧑💻 Enhanced Collaboration
|
||||
|
||||
Multiple users in the same conversation, watching responses stream in together, annotating, branching, and building on each other's prompts. Brainstorming with your team and your AI in the same room.
|
||||
|
||||
### 📣 Wakeword Detection
|
||||
|
||||
Say the word and start talking. No keyboard, no click, no tab switching. Walk into a room, speak, and your AI is already listening. This is what the future of human-computer interaction looks like.
|
||||
|
||||
### 🌐 Modular RAG Framework
|
||||
|
||||
Swap out every piece of the retrieval pipeline from the UI. Different chunking strategies, different embedding models, different rerankers, all configurable with drag-and-drop. One size doesn't fit all, and your RAG setup shouldn't pretend it does.
|
||||
|
||||
### 👤 User Profiles & Sharing
|
||||
|
||||
Publish your model configurations, prompts, and skills. Follow other users. Build on what they've shared. A growing ecosystem of ready-to-use AI setups that anyone can import and make their own.
|
||||
|
||||
### 🏆 Community Leaderboard
|
||||
|
||||
Real-world model rankings based on actual usage and feedback, not synthetic benchmarks. See which models perform best for code, for writing, for analysis, ranked by the people who use them every day.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## The Vision
|
||||
|
||||
AI is consolidating the tools we use every day. Search, writing, analysis, code, project management, they're all converging into a single interface. Open WebUI is built to be that interface: self-hosted, extensible, and designed to grow with the models it connects to.
|
||||
|
||||
Everything on this page is a step toward that goal.
|
||||
|
||||
---
|
||||
|
||||
Want to help us ship faster? Run the [dev branch](https://github.com/open-webui/open-webui), test upcoming features, and report what you find. Every bug caught early lets us tackle more.
|
||||
|
||||
For discussion and real-time progress, join us on [Discord](https://discord.gg/5rJgQTnV4s) or follow development on [GitHub](https://github.com/open-webui/open-webui).
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user