# Open WebUI Integration

Connect your [Open WebUI](https://docs.openwebui.com) instance to Capsule Security for governance of every chat turn that passes through it - with inline policy enforcement before the model call, audit of prompts and responses after it, and an inventory of the workspace models, tools and functions your teams have built inside the tool.

## Overview

This integration uses an Open WebUI [Filter function](https://docs.openwebui.com/features/extensibility/plugin/functions/filter) that runs in-process inside your Open WebUI server. Before each user turn reaches the model, the filter posts it to your Capsule tenant and blocks on an allow/deny verdict. After the turn settles, it posts the assistant response and the tool set that was in play as fire-and-forget telemetry.

Open WebUI is operator-deployed - you run it in your own infrastructure, so there is no SaaS install. The only thing exchanged at install time is a signed token that scopes the filter to your tenant and environment.

Because Open WebUI passes the authenticated user and chat to every filter call, activity is attributed to the real user and the real conversation rather than to a shared service identity.

The following filter methods are configured:

| Method | Type | Description |
|  --- | --- | --- |
| **inlet** | Blocking | The user message before it reaches the model - can deny on policy violation |
| **request** | Observation | The resolved tool set and any retrieved knowledge injected into the payload, on every model call in the turn |
| **outlet** | Observation | The completed assistant response |


## Prerequisites

Before you begin, ensure you have:

- A running **Open WebUI** instance (v0.5.0 or later)
- Administrator access to the Open WebUI **Admin Panel**
- A **Capsule Security** account with admin access
- Network access from your Open WebUI server to your Capsule agentsecurity endpoint (e.g. `https://agents.capsule.security`)


## Step 1: Generate a Plugin Token

1. Log in to the **Capsule Security** portal.
2. Navigate to **Integrations** and locate **Open WebUI**.
3. Click **Install** - Capsule generates a JWT scoped to your tenant and Open WebUI environment. The token contains the tenant and environment claims required by the agentsecurity endpoint; treat it as a secret.
4. Copy the generated **endpoint** and **token**. You will paste both into the filter configuration in Step 3.


## Step 2: Import the Capsule Filter

Open WebUI stores function source in its own database rather than on disk, so there is nothing to install on the host and no package to manage. Any Python dependencies the filter needs are declared in its frontmatter and installed by Open WebUI when the function loads.

1. In Open WebUI, navigate to **Admin Panel > Functions**.
2. Click **+** to add a function, then use **Import from Link** and paste the filter URL shown on the Capsule integration card. You can also paste the source directly.
3. Review the source before saving. The filter executes inside your Open WebUI server on every chat turn, so treat it the way you would treat any other function you install.
4. Save the function. It appears in the function list as **Capsule Guard**.


Saving activates the function immediately. Open WebUI does not need to be restarted.

## Step 3: Configure the Valves

The filter reads its configuration from **Valves**, Open WebUI's admin-scoped settings for a function. Keeping the token in a valve rather than in the source means you can rotate it without re-importing the filter.

1. In **Admin Panel > Functions**, click the settings icon on the **Capsule Guard** row.
2. Set `capsule_endpoint` to the endpoint from Step 1, for example `https://agents.capsule.security/v1/openwebui/hooks/events`.
3. Set `capsule_token` to the JWT from Step 1.
4. Save.


### Configuration Options

| Option | Type | Default | Description |
|  --- | --- | --- | --- |
| `capsule_endpoint` | `string` | *(required)* | Capsule Open WebUI hooks endpoint, e.g. `https://agents.capsule.security/v1/openwebui/hooks/events` |
| `capsule_token` | `string` | *(required)* | JWT generated in Step 1, scoped to your tenant and environment |
| `block_on_risk` | `boolean` | `true` | Apply server `deny` verdicts inline. Set to `false` to run in observe-only mode |
| `fail_open` | `boolean` | `true` | When Capsule is unreachable or returns an error, allow the turn to proceed. Set to `false` to fail closed |
| `timeout_ms` | `number` | `5000` | Per-request timeout in milliseconds |
| `priority` | `number` | `0` | Open WebUI filter ordering. Lower values run first; leave at `0` so Capsule evaluates the turn before other filters rewrite it |


### Token Storage

Valve values live in the Open WebUI database and are visible to any Open WebUI administrator. Treat the token accordingly:

- Restrict Open WebUI administrator access to the same set of people you would trust with a tenant-scoped API credential
- Rotate the token through the Capsule portal if an administrator leaves or if the value is exposed
- Never paste the token into the function source, into a shared config file, or into version control


## Step 4: Enable the Filter Globally

A filter only applies to the models an administrator has enabled it on. To govern every model in the instance:

1. In **Admin Panel > Functions**, locate **Capsule Guard**.
2. Confirm the function is **active**.
3. Click the globe icon to toggle **Global**.


With Global enabled the filter runs on all models and cannot be disabled per model. Without it, coverage is limited to the models you enable it on individually, and any model added later is ungoverned until someone remembers to enable it.

## Step 5: Verify the Installation

1. Open a new chat in Open WebUI and send a message to generate activity.
2. Log in to the **Capsule Security** portal.
3. Navigate to **Inventory > Agents** and confirm an Open WebUI agent appears.
4. Click on the agent and review the audit logs to verify the user message and the assistant response are captured.


### Troubleshooting

If events are not appearing:

1. **Verify the endpoint is reachable** from the Open WebUI host:

```bash
curl -sS -o /dev/null -w "%{http_code}\n" https://agents.capsule.security/v1/openwebui/hooks/events
```
2. **Verify the valves are set** - the filter stays inert and logs `capsule_guard: disabled` when `capsule_endpoint` or `capsule_token` is missing.
3. **Confirm the filter is enabled** - an inactive function, or an active one that is neither global nor enabled on the model you are testing, never runs.
4. **Check for timeouts** - if your network has high latency to the Capsule endpoint, increase `timeout_ms` or confirm `fail_open` is set appropriately.
5. **Check the Open WebUI server logs** - the filter logs a warning on every failed post, including the HTTP status Capsule returned.
6. **Contact Capsule Security support** if issues persist.


## Security Considerations

The Capsule filter runs in-process inside your Open WebUI server and observes every chat turn. Before deploying:

1. **Review the filter source before importing it.** Open WebUI functions are arbitrary Python that runs on your server with access to the full request. This applies to the Capsule filter and to every other function you install.
2. **Protect the JWT** - anyone with the token can post events on behalf of your tenant. Rotate it through the portal if it is exposed.
3. **Choose `fail_open` deliberately** - `true` (the default) prioritizes availability and lets turns through when Capsule is unreachable; `false` prioritizes policy enforcement and rejects turns when Capsule cannot be reached.
4. **Pin a filter version** in production and review changes before re-importing.
5. **Use TLS-only endpoints**. The filter sends a Bearer token on every request - never configure an `http://` endpoint outside local development.


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your organization ID, integration status, plugin version, and any error messages


## References

- [Open WebUI Documentation](https://docs.openwebui.com)
- [Open WebUI Plugin System](https://docs.openwebui.com/features/extensibility/plugin/)
- [Open WebUI Filter Functions](https://docs.openwebui.com/features/extensibility/plugin/functions/filter)