open-webui/docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-07-21 01:55:22 -04:00
Code Issues 37 Packages Projects Releases Wiki Activity

refac

Browse Source
This commit is contained in:
Timothy Jaeryang Baek
2026-07-10 18:36:57 -05:00
parent ca99717a77
commit 56d11f19ab
6 changed files with 65 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ecosystem/computer/agents/index.md
+14 -14
View File
@@ -9,22 +9,22 @@ An agent earns its place when you can see what it is doing, steer it before the
Use this section to make five deliberate choices:
| You want | What Computer provides |
| --- | --- |
| Visible progress | Chat tool activity, task state, files, terminal output, and git diff in the same workspace. |
| A way to steer work | Plan mode, direct chat follow-ups, cancellation, and approval controls for interactive work. |
| Continuity | Saved workspace layout and chat history, plus reconnectable terminals while the host and process remain running. |
| Reusable judgment | Skills for repeatable methods and memory for durable facts you choose to retain. |
| Parallel investigation | Sub-agents for independent questions with results brought back to the parent task. |
- **See progress:** chat tool activity, task state, files, terminal output, and git diff remain in the same workspace.
- **Steer work:** use Plan mode, direct chat follow-ups, cancellation, and approval controls for interactive work.
- **Keep continuity:** save workspace layout and chat history, then reconnect to terminals while the host and process remain running.
- **Reuse good judgment:** keep repeatable methods in skills and durable facts in memory.
- **Investigate in parallel:** use sub-agents for independent questions, then bring the result back to the parent task.
Start small. Choose a model, ask it to explain one real file, then decide whether it should be allowed to make a change. You do not need an AI connection to use the rest of Computer.
| Need | Read this |
| --- | --- |
| Decide between an API key/local endpoint and an installed agent subscription | [API models or native coding agents](./models) |
| Make a native agent available on the host | [Set up and detect a coding agent](./setup-and-detection) |
| Review changes and control approval | [Supervise agent work safely](./supervise-work) |
| Continue work across devices or recover after an interruption | [Plans, queues, resume, and context](./continuity) |
| Decide whether reusable guidance, parallel work, web research, or media input is actually needed | [Choose an agent extension](./capabilities) |
Need to choose a model or installed subscription? Read [API models or native coding agents](./models).
Need to make a native agent available on the host? Read [set up and detect a coding agent](./setup-and-detection).
Need to review changes and control approval? Read [supervise agent work safely](./supervise-work).
Need to continue work across devices or recover after an interruption? Read [plans, queues, resume, and context](./continuity).
Need reusable guidance, parallel work, web research, or media input? Read [choose an agent extension](./capabilities).
Not a fit: use a normal chat product when you only need conversation, knowledge, or model comparison. Use a disposable environment when an untrusted agent or user must not reach the real host. Running an unsupported agent CLI in a terminal remains useful, but it does not make that CLI a native Computer chat backend.
docs/ecosystem/computer/choose.md
+26 -22
View File
@@ -5,58 +5,62 @@ sidebar_position: 2
# Open WebUI, Open Terminal, Computer, or a combination?
Start with where the useful context lives and what kind of computer should do the work. These are complementary ways to work, not competing feature checklists.
These tools can work together. The useful question is not which one has the longest feature list. It is whether you want to work through a conversation, an Open WebUI terminal connection, or a workspace that is organized around your personal machine.
## Start in Open WebUI when the work begins as a conversation
Choose Open WebUI for model choice, knowledge, prompts, shared AI workflows, and conversations where the important context is already in the chat or connected knowledge sources. It works well for one person and grows naturally into shared workflows.
You can stop here when the task does not need a shell, a project folder, or a particular machine.
Stop here when the task does not need a shell, files, or another computer connection.
## Add Open Terminal when a chat needs a fresh place to execute
## Add Open Terminal when a chat needs a terminal and files
Open Terminal is an Open WebUI feature. It gives an Open WebUI chat a computing environment where the model can write files, run commands, install packages, and return the result in the conversation.
Open WebUI can connect to an Open Terminal server. The chat gets an interactive terminal, file browser, editor, uploads and downloads, running-process output, and local-port previews. The model can use the same environment as an always-on tool while you work in the chat.
Use it for a self-contained job: analyze an uploaded dataset, build a small prototype, run a script, or give an agent a clean environment for a task. It is especially useful when the work does not depend on an existing machine's long-lived state. Run it in Docker for an isolated execution environment. Use bare-metal access only when direct host access is intentional.
That environment can take several forms:
- **Docker:** a container with its own toolchain. Its files can persist when the server uses a volume.
- **Bare metal:** the terminal runs on a real machine and can start in an existing project directory.
- **Per-user containers:** the Terminals service can provision a separate configured container for each Open WebUI user.
Choose Open Terminal when you want Open WebUI's chat and file experience to drive a configured terminal environment. It can be a long-lived project environment, not only a temporary scratch space.
[Learn about Open Terminal](/features/open-terminal)
## Start in Open WebUI Computer when the real machine is the point
## Start in Open WebUI Computer when you want to operate the machine as a workspace
Choose Computer when the useful context is already alive on one machine: its existing project folders, documents, terminal, local service, browser session, installed tools, git state, or agent work.
Computer also gives you a terminal, files, previews, and agent work. Its distinct shape is the workspace itself: a chosen path on the host, with its file browser location, tabs, split layout, chats, Git status and diffs, browser tabs, terminals, and local previews kept together.
Computer is a private control surface for that machine. It lets you open the same workspace from another browser, see what is actually there, and continue or direct the work without recreating it somewhere else. AI is optional.
Choose Computer when you want to personally return to that workspace from another browser, inspect its real state, and direct work there. It is especially strong for a personal machine with a project, local service, Git history, browser state, or supported coding agent already in motion.
Use it for the moments when the right answer starts with, “Let me check my computer.”
Computer saves workspace layout and chats. Live terminals, browser sessions, and running processes still depend on the host and Computer server remaining available.
[Try Computer locally](./getting-started/local-trial)
## Use Open WebUI and Computer together when the conversation needs a real workspace
## Use Open WebUI and Computer together when a conversation needs a Computer workspace
Keep Open WebUI as the conversation interface you prefer. Connect Computer's gateway when a particular workspace must be the place where a configured model or agent works.
Keep Open WebUI as the conversation interface you prefer. Connect Computer's gateway when a particular Computer workspace should receive the work.
In that request:
- Open WebUI owns the conversation and interface.
- The selected Computer workspace model identifies the real workspace.
- Computer's configured model or agent performs the workspace work.
- The selected Computer workspace model selects a registered Computer workspace.
- Computer resolves its configured model or agent and runs the workspace task.
Open WebUI knowledge bases, model-agent tools, system prompts, users, and general configuration are not forwarded into Computer automatically. Configure an equivalent capability in Computer when the workspace task needs it.
Open WebUI knowledge bases, model-agent tools, system prompts, users, and general configuration are not automatically imported into Computer.
[Connect Open WebUI to a Computer workspace](./integrations/open-webui-gateway)
## Use all three when your work has more than one kind of context
## Use all three when each serves a clear role
This is common. Keep Open WebUI as the place to ask, compare, and organize. Use Open Terminal for a disposable or isolated execution task. Use Computer for the existing machine where your personal project, local service, or ongoing agent work must remain continuous.
The value is not forcing every job through one product. It is choosing the environment that matches the work in front of you.
You can use Open WebUI with an Open Terminal connection for chat-driven terminal work, and connect Open WebUI to Computer when you need Computer's personal workspace surface. They are separate services with their own chats, sessions, and stored state. Giving both access to the same host directory does not automatically merge their files, terminals, or conversations.
## A quick way to decide
- Need to think, compare models, or use shared AI knowledge? Start in Open WebUI.
- Need an AI to run a self-contained task in an isolated environment? Add Open Terminal in Docker.
- Need the files, process, login, project, or agent that already exists on your machine? Start in Computer.
- Need an Open WebUI conversation to direct work in one existing workspace? Connect Open WebUI to Computer.
- Need an Open WebUI chat to work through a terminal and file environment? Add Open Terminal.
- Need a browser workspace for personally operating a chosen machine and its project state? Start in Computer.
- Need an Open WebUI conversation to send work into a registered Computer workspace? Connect Open WebUI to Computer.
## If you already use an agent command-line tool
@@ -64,4 +68,4 @@ Computer can give an installed agent command a real terminal in the selected wor
## Keep the trust model in view
Open Terminal can run in an isolated Docker environment or, when you choose it, on a host. Computer deliberately reaches the real host account and its files, shell, and processes. That is what makes it useful for a trusted owner and why it should stay private. Read [the security model](./remote-access/security-model) before exposing it remotely or connecting unattended integrations.
Docker creates a useful container boundary, but mounts and access to a host Docker socket change what that environment can reach. Bare-metal Open Terminal runs with the permissions of its host account. Computer deliberately exposes the host account's files, shell, and processes to an authenticated user. Read [Open Terminal security](/features/open-terminal/advanced/security) and [the Computer security model](./remote-access/security-model) before exposing either service or connecting unattended integrations.
docs/ecosystem/computer/integrations/index.md
+20 -8
View File
@@ -7,12 +7,24 @@ sidebar_position: 1
Integrations make a real Computer workspace reachable from another product or let it act without the browser open. That is valuable only when the workspace, sender, credentials, and side effects are all deliberate. Start with a read-only check and add one connection at a time.
| What you want | Read this |
| --- | --- |
| Keep Open WebUI as the AI front door while work happens in a real workspace | [Use a Computer workspace from Open WebUI](./open-webui-gateway) |
| Run a trusted recurring task in one workspace | [Schedule trusted work](./automations) |
| Receive completion/failure results or trigger a run with a secret URL | [Notifications and webhooks](./notifications-and-webhooks) |
| Ask a private messaging account to work in a selected workspace | [Messaging bots](./messaging-bots) |
| Let an agent call a trusted tool server or API | [MCP tool servers](./mcp-tool-servers) and [OpenAPI tool servers](./openapi-tool-servers) |
### Keep Open WebUI as the AI front door
Not a fit: do not use these integrations to accept arbitrary internet requests, add a bot to a shared group, or hand a third-party service unrestricted credentials. Computer has no tenant isolation and its unattended paths run with high trust.
[Use a Computer workspace from Open WebUI](./open-webui-gateway) when the conversation starts in Open WebUI and the work must happen in a real workspace.
### Run a recurring task in one workspace
[Schedule trusted work](./automations) when the task, workspace, model, and expected result are known.
### Receive a result or trigger a known task
[Set up notifications and webhooks](./notifications-and-webhooks) for delivery and secret-trigger handling.
### Ask a private messaging account about a workspace
[Set up a messaging bot](./messaging-bots) only for an account or channel you control and deliberately allow.
### Let an agent use a declared external service
Choose [MCP tool servers](./mcp-tool-servers) or [OpenAPI tool servers](./openapi-tool-servers) when you can explain the tool's credentials, operations, and data handling.
Keep these connections private and deliberate. Computer has no tenant isolation, and its unattended paths run with high trust.
docs/ecosystem/computer/integrations/open-webui-gateway.md
+3 -3
View File
@@ -52,21 +52,21 @@ Use this when you already work in Open WebUI but need an agent to inspect, edit,
```
`{{USER_MESSAGE_ID}}`, `{{USER_MESSAGE_PARENT_ID}}`, and `{{TASK}}` require Open WebUI 0.10.0 or newer. Without them, basic chat works, but edit/regeneration branches and background-task filtering do not.
4. Save, select the `cptr/<workspace>` model in Open WebUI, and ask the read-only question above about a file in that workspace.
4. Save, select the `cptr/your-workspace` model in Open WebUI, and ask the read-only question above about a file in that workspace.
The lineage headers let Computer reuse the correct chat for subsequent turns, preserve edits/regenerations as branches, and avoid treating Open WebUI title/tag/follow-up utility requests as agent tasks.
| In a combined request | What it owns |
| --- | --- |
| **Open WebUI** | The caller conversation and interface. |
| **`cptr/<workspace>`** | The selected real Computer workspace. |
| **`cptr/your-workspace`** | The selected real Computer workspace. |
| **Open WebUI Computer** | The configured model or agent that executes the task in that workspace. |
Open WebUI knowledge bases, model-agent tools, system prompts, users, and general configuration are not forwarded into Computer unless you configure equivalent capabilities in Computer.
## Verify it worked
The workspace appears as `cptr/<workspace>` in Open WebUI’s model picker. Its answer identifies the real README command, and the associated conversation appears in the Computer sidebar. Send a follow-up, then edit or regenerate a message: the Computer sidebar should show the related branch rather than an unrelated chat. Open WebUI title/tag requests should not create a workspace-agent chat.
The workspace appears as `cptr/your-workspace` in Open WebUI’s model picker. Its answer identifies the real README command, and the associated conversation appears in the Computer sidebar. Send a follow-up, then edit or regenerate a message: the Computer sidebar should show the related branch rather than an unrelated chat. Open WebUI title/tag requests should not create a workspace-agent chat.
## If it did not
docs/ecosystem/computer/reference/gateway-api.md
+1 -1
View File
@@ -26,7 +26,7 @@ Use this reference when connecting a trusted OpenAI-compatible client and you ne
## Do it
1. Request `GET /v1/models` with `Authorization: Bearer <gateway-key>`.
2. Select a returned `cptr/<workspace>` model.
2. Select a returned `cptr/your-workspace` model.
3. Send `POST /v1/chat/completions` with `model`, `messages`, and optional `stream`.
4. Send `X-Chat-Id` or `X-OpenWebUI-Chat-Id` to reuse a Computer chat across turns. Open WebUI should additionally send its message/task lineage headers.
docs/ecosystem/computer/use-cases/open-webui-workspace.md
+1 -1
View File
@@ -21,7 +21,7 @@ You want Open WebUI as the AI front door and Open WebUI Computer as the place th
## Do it
1. Add the Computer gateway as an OpenAI API connection in Open WebUI using the documented `/v1` base URL and gateway credential.
2. Add the documented continuity headers, save the connection, and select the workspace model shown as `cptr/<workspace>`.
2. Add the documented continuity headers, save the connection, and select the workspace model shown as `cptr/your-workspace`.
3. Ask a small read-only question about a known file in that workspace.
4. Open Computer and inspect the workspace chat and activity produced by the request before trying a task that edits files or runs commands.