OpenWebUI

OpenWebUI is a self-hosted AI chat interface with multi-user support. When connected to CoreCube, each user's queries are automatically scoped to their assigned knowledge compartments — no extra configuration per user is needed after initial setup.

Prerequisites

• CoreCube running and accessible from your OpenWebUI instance
• OpenWebUI 0.3.0 or later
• An admin account on CoreCube

Step 1 — Create a service API key

In the CoreCube admin console, go to Settings → API Keys and create a new key:

Field	Value
Key Name	OpenWebUI Production (or any label)
Key Type	Service — proxy app
Integration	OpenWebUI
Owner User	Select an admin user as key owner
Auto-provision users	Enable if you want CoreCube to create accounts automatically for new OpenWebUI users
Default scope	Select the scope new users should receive (required when auto-provision is on)

Save the key — copy the raw value now, it is shown only once.

Step 2 — Enable user identity forwarding in OpenWebUI

Set the following environment variable on your OpenWebUI instance:

ENABLE_FORWARD_USER_INFO_HEADERS=true

With this enabled, OpenWebUI injects the logged-in user's email address into every request it sends to CoreCube:

X-OpenWebUI-User-Email: alice@company.com

This header is set by OpenWebUI's server, not the user's browser. Users cannot forge or override it.

:::info Docker Compose

services:
  open-webui:
    environment:
      ENABLE_FORWARD_USER_INFO_HEADERS: 'true'

:::

Step 3 — Add CoreCube as a connection in OpenWebUI

In OpenWebUI, go to Admin Panel → Settings → Connections and add a new external connection:

Field	Value
URL	http://corecube:7400/v1 (or your CoreCube address)
Auth	Bearer
Bearer token	The service key from Step 1
Provider Type	OpenAI
API Type	Chat Completions

Save. OpenWebUI will call GET /v1/models to discover available models — these come from CoreCube's configured LLM providers.

Step 4 — Make CoreCube models visible to non-admin users

By default, OpenWebUI hides models discovered from admin-configured connections from non-admin users. Even though the connection is working, regular users cannot select CoreCube in the model picker until the admin explicitly sets the model to public.

1. In OpenWebUI, go to Admin Panel → Settings → Models
2. Find each CoreCube model in the list
3. Open the model's settings and set Visibility to Public

warning

Without this step, non-admin users will see "No models available" or will not find CoreCube in the model picker — the connection itself is fine, but OpenWebUI filters it out of their view.

Step 5 — Ensure users exist in CoreCube

CoreCube resolves the user from the forwarded email. Each OpenWebUI user must have a matching account in CoreCube with the same email address.

Option A — Manual: Create users in CoreCube admin (Settings → Users) with the same email addresses as your OpenWebUI users.

Option B — Auto-provision: Enable the auto-provision toggle on the service key (Step 1). New users are created automatically the first time they send a chat message — not at OpenWebUI login, and not when the admin creates their OpenWebUI account.

:::info When does auto-provisioning actually fire? Auto-provisioning happens only when the OpenWebUI user sends their first chat message. Creating the account in OpenWebUI, logging in, or browsing the model list does not trigger it. The CoreCube user appears in Settings → Users only after the first POST /v1/chat/completions request is received with their forwarded email. :::

:::warning Auto-provisioned users Auto-provisioned users receive a no_access role and the default scope only. They cannot log into the CoreCube admin console. Adjust their scope and role after provisioning if needed. :::

Step 6 — Assign knowledge scopes

In CoreCube admin, go to Access Control → Scopes and assign each user to the appropriate scope. Users without a scope assignment will receive empty search results.

How it works end-to-end

Alice logs into OpenWebUI
  → sends a chat message
  → OpenWebUI calls POST /v1/chat/completions
    with: Authorization: Bearer cc_SERVICE_KEY
          X-OpenWebUI-User-Email: alice@company.com
  → CoreCube resolves alice, applies her scopes
  → searches only compartments alice can access
  → returns cited response

Troubleshooting

"User not found" errors The email in OpenWebUI does not match any CoreCube user. Check that emails are identical (case-insensitive). Enable auto-provision if you want CoreCube to create users automatically.

All users see the same results ENABLE_FORWARD_USER_INFO_HEADERS is not set or is false. Verify the env var is set and OpenWebUI has been restarted.

Models not appearing in OpenWebUI CoreCube's /v1/models endpoint returns models from configured LLM providers. Ensure at least one LLM provider is configured in Settings → LLM Providers.

Non-admin users cannot select CoreCube / "connection lost" after login Admin sees CoreCube fine, but a newly created non-admin user cannot pick CoreCube in the model picker. This is an OpenWebUI permission default, not a CoreCube issue — see Step 4 to set the model to public visibility.

New OpenWebUI user not appearing in CoreCube despite auto-provision Auto-provisioning fires only on the first chat message, not on OpenWebUI account creation or login. Confirm the user can actually select CoreCube in the model picker (see previous entry) and has sent at least one message. Then check Settings → Users in CoreCube admin.