# Open WebUI with vLLM: backend models and workspace wrappers

Connect Open WebUI to an existing vLLM endpoint and distinguish backend model identity, Workspace wrappers, and user access.

Author: Retrivium team
Updated: 2026-11-03
Canonical URL: https://retrivium.ai/journal/open-webui-vllm-model-workspace/
Language: en

When connecting Open WebUI to vLLM, distinguish the backend model identity from a Workspace wrapper shown to users. A wrapper can package instructions and resources, but it does not rename the running weights or grant backend capabilities by itself.

## The concrete application boundary

Open Workspace → Models and create a model entry only after testing the base model through the provider connection. The Base Model selection points to the generator, while the Workspace ID and display name identify the reusable configuration. In its editor, bind the required system instruction and keep optional knowledge and tools empty for the first trial. The documentation also distinguishes hidden base models from ordinary selector visibility and resource access. An administrator can choose a hidden base model without proving that every account may select it directly. Therefore inspect both the wrapper’s intended audience and the account performing the test, not simply the presence of a familiar name. Running a wrapper checks access to both wrapper and base. Hiding an accessible base from the selector is different from restricting it away from the intended users ([Open WebUI Models](https://docs.openwebui.com/features/workspace/models/)) ([Open WebUI Workspace](https://docs.openwebui.com/features/workspace/)).

## A practical route

Start with an existing compatible endpoint and verify its served model identity independently. Add the compatible connection in Open WebUI and check its inventory behavior. Select the base model directly before creating a Workspace entry. Then define a wrapper with a clear name and a narrow instruction, keeping its base model and visibility explicit ([Open WebUI compatible provider guide](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible)).

## A worked example

Create a code-review helper that asks for a function and returns a list of uncertainties before suggesting changes. First test the base model with an ordinary question. Then test the wrapper with a fictional helper function. Compare the instruction behavior while keeping the backend unchanged, and repeat using the intended non-administrator account.

| Check | Record |
| --- | --- |
| Backend identity | The model identifier served by the existing vLLM endpoint. |
| Wrapper identity | The Workspace entry used for the code-review instructions. |
| Access result | Whether the intended user can select the wrapper and complete its sample conversation. |

## Reading the failure correctly

Compatible connection verification commonly requests the model inventory. An endpoint may support conversation requests while not satisfying the same inventory path. A saved connection is therefore different evidence from successful verification or a successful chat. Separately inspect allowlists and wrapper access when only some users see an entry.

## What completes the check

The final note should connect a visible wrapper to its actual base model and account scope. Keep a direct base-model check available: it lets later instruction changes be investigated without first changing the inference backend.

Related background: [vLLM served-model-name: Fix a Missing API Model](/journal/vllm-served-model-name/), [llama.cpp server: a local API from a GGUF model](/journal/llama-cpp-server-launch/).