Keeping Open WebUI Knowledge Bases Up to Date: Sync Directory, Upload or oikb

Connect knowledge sources to Open WebUI? WZ-IT runs Open WebUI as an AI platform with knowledge workspaces and, on request, sets up the automatic connection to your sources, for example Confluence, GitHub or file stores. More on features and options under Open WebUI as an AI platform. Book a meeting

A knowledge base in Open WebUI is only as good as its freshness. Documents uploaded once are an outdated copy the moment the source changes: the handbook in the wiki gets revised, the product documentation in the repository gets a new commit, new contracts land in the document store. The model then answers with yesterday's knowledge, and nobody notices.

Since Open WebUI 0.9.6 there is oikb for this, the official companion tool for synchronisation. It keeps a knowledge base level with a living source, on a schedule, on every push or on demand. This article puts it in context: which ways there are to get knowledge into Open WebUI, when each pays off, which connectors oikb brings, what operations look like and where the limits are. All statements are as of October 2026 and based on the Open WebUI documentation.

Note: This article is not legal advice. Statements on data protection and permissions are technical assessments.

Table of Contents

1. oikb at a Glance
2. Ways Into a Knowledge Base Compared
3. Decision Guide
4. How the Incremental Sync Works
5. The Connectors at a Glance
6. Use Cases
7. Operations: Daemon, Webhooks and Security
8. Limits and Pitfalls
9. Data Protection and Permissions for Connectors
10. Our Approach at WZ-IT
11. Further Guides

oikb at a Glance

oikb is a standalone program, not part of the Open WebUI server. It consists of a command line and an optional daemon and talks to Open WebUI over its regular REST API (oikb documentation).

The core difference from a one-off upload: oikb connects a knowledge base to a source once and keeps it current afterwards. An unchanged source triggers nothing, because nothing is re-uploaded, re-extracted or re-embedded.

Ways Into a Knowledge Base Compared

There are several ways to get content into an Open WebUI knowledge base. They differ in effort, freshness and scale.

Since version 0.9.6 the sync in the interface is no longer destructive either: the client hashes the files, the server compares and touches only new, modified and deleted files. Before that, everything was deleted and re-uploaded (knowledge base documentation).

Decision Guide

The choice depends on four questions:

1. How large is the library? For small libraries, upload or the sync directory is enough. With thousands of files or several gigabytes, Open WebUI itself recommends oikb because it works natively with parallel uploads and retries.
2. How current must the knowledge be? If the source rarely changes, a manual run is enough. If the model should always know today's state, you need the daemon with a schedule or webhook.
3. Where does the source live? Local folders, repositories, wikis, ticketing systems or cloud storage are covered by the oikb connectors. For proprietary specialist systems without a connector, a custom script against the API remains.
4. Who operates it? oikb is an additional service with credentials, a schedule and monitoring. That pays off if someone is responsible for it. Otherwise managed operations are the better choice.

As a rule of thumb: upload single documents, synchronise a folder in the browser, use oikb for larger or living sources, and the daemon for permanent operation.

How the Incremental Sync Works

oikb scans the source and computes a SHA-256 checksum for every file. It sends a manifest with path, file name, checksum and size, but without file contents, to Open WebUI's /sync/diff endpoint. The server replies with what was added, modified and deleted, plus which directories to create or remove. This call changes nothing.

oikb then deletes the stale files and empty directories, creates missing directories and uploads only new and modified files, each with its hash so the server does not hash again. HTTP 5xx errors are retried up to three times with growing wait times. Uploads run sequentially by default, with --concurrency N N files run in parallel (oikb documentation).

A short output shows what a run does:

$ oikb sync github:acme/handbook --kb-id 8f3a2b1c-...
  1,204 files found
  Diff: +3, ~1, -2, 1198 unchanged
Sync complete: 3 added, 1 modified, 2 deleted, 1198 unchanged

With --dry-run oikb shows beforehand what would change without uploading anything. That is the safe way in before a productive knowledge base is connected.

The Connectors at a Glance

A source is either a local path or a string of the form scheme:target. oikb resolves the scheme to a connector, fetches the files and compares them. Credentials never appear in the source string or the configuration file, they come from environment variables. A selection from the documentation:

Some connectors need a vendor extra, such as pip install oikb[s3] for Amazon S3. GitHub is read through the Trees API, no local clone is needed. Chat history is split by day so the sync stays truly incremental: past days do not change and are never uploaded again.

The scope can be narrowed with include and exclude patterns, a size cap and a .oikbignore file in the root folder. A source can also be split across several knowledge bases, for example the documentation and the source code of one repository.

Use Cases

The documentation names typical scenarios that carry over to companies:

• Product documentation that is always current. The documentation repository is synchronised on every merge in CI or by webhook. Support and customers query a library that is at most one commit old.
• Handbook from the wiki. A Confluence space or Notion workspace is mirrored every morning by cron. An assistant for internal questions answers from the current handbook, wiki changes are in by the next day.
• Support knowledge from tickets. Resolved cases from Zendesk or Jira land in a knowledge base so a triage model sees how similar problems were solved.
• Code-aware assistant. A repository is split by filter across two knowledge bases: prose under docs/** and source code under src/**.
• Document stores. Contracts, policies or reports in S3, SharePoint or a file store are compared regularly so new documents become findable without manual work.

Which scenario fits depends on the sources. Anyone who clarifies in advance which content the model may see avoids the most common mistake: connecting entire stores that hold confidential or outdated documents.

Operations: Daemon, Webhooks and Security

The daemon runs several sources from one configuration file .oikb.yaml. Each entry holds a source, a knowledge base ID and optionally an interval, webhook and notification (daemon documentation).

• Schedule. Intervals such as 30m, 1h or 1d, or cron expressions such as 0 6 * * 1-5 (weekdays at 6 am).
• Webhooks. For GitHub (HMAC signature), GitLab (token), Slack (signature) and Confluence (by space key). If a sync is already running, a triggered webhook is skipped.
• HTTP API. GET /health, GET /health/ready and GET /metrics are public, POST /sync/{name-or-kb-id} requires the API key OIKB_API_KEY.
• Observability. Prometheus metrics such as oikb_sync_total and oikb_sync_duration_seconds, JSON logs with LOG_FORMAT=json, history in SQLite and notification by HTTP POST on failures.
• Containers. Image ghcr.io/open-webui/oikb, in Compose or Kubernetes with a ConfigMap for the configuration and a Secret for the keys. The daemon is meant for one replica because the schedule and per-knowledge-base locks live in one process.
• Model-driven. The daemon offers three tools at /openapi.json: start a sync, query status, retrieve history. A model can trigger a refresh in conversation, provided an API key is set.

For security the documentation recommends keeping secrets out of the configuration file, preferring file-based secrets in production and exposing the daemon only on trusted networks when no webhook secrets are set.

Limits and Pitfalls

• Version. Without Open WebUI 0.9.6 or newer there is nothing for oikb to call.
• API keys. They are off by default. An admin must enable them, and users without the permission see no key management. Even with a valid key you get 403 if endpoint restrictions do not allow /api/v1/knowledge and /api/v1/files, or if the user lacks write access to the knowledge base.
• Indexing runs server-side. oikb uploads fast, embedding happens afterwards asynchronously. Files appear in the file list only after it completes.
• File limits. If an admin has set a maximum upload size or allowed file extensions, matching files fail on every run with HTTP 413 or 400 until they are excluded by filter.
• One daemon, one replica. More sources belong as further entries in one daemon, not in several copies.
• oikb reset. The command deletes all files of the knowledge base, not just those uploaded by oikb. It asks for confirmation for good reason.
• Retention. On cleanup the server deletes the record and stored bytes of a stale file, unless ENABLE_KNOWLEDGE_FILE_RETENTION=true is set, the file is linked to another knowledge base or the key's user is neither the file's owner nor an admin.

Data Protection and Permissions for Connectors

Every connector is a data flow. With local folders and repositories in your own network it stays internal. With Confluence Cloud, Slack, Gmail or Zendesk, content flows from those services into your Open WebUI instance, is embedded and feeds into the model's answers. To clarify beforehand:

1. Content. Which personal or confidential data is in the source, and does it have to go into the knowledge base?
2. Access. oikb works with the rights of the API key's user and does not bypass access control in Open WebUI. Assume that everything the connection's account can read in the source ends up in the knowledge base. Define the knowledge base sharing independently of the permissions in the source.
3. Credentials. Each connector reads its keys from environment variables. Use accounts with minimal read rights on the desired source.
4. Model path. Where the content flows after embedding is decided by the model connection. Running the model in Germany keeps the data flow in your own framework.

This is a technical assessment. The legal evaluation, for example on data processing or professional secrecy, belongs in your data protection review.

Our Approach at WZ-IT

WZ-IT runs Open WebUI as an AI platform and as managed hosting by compute size, in both cases with the original branding visible. For these instances we set up the connection to your knowledge sources with oikb on request. The requirement, Open WebUI 0.9.6 or newer, is met because we run Open WebUI in its current version.

Before setting up we clarify with you:

1. Sources and content. Which systems should be connected and which content may go into the knowledge base?
2. Permissions. Who may use which knowledge base, and with which accounts does the synchronisation access the sources?
3. Schedule. Daily run, webhook on changes or manual trigger?
4. Operations. Monitoring of runs, notification on failures, updating oikb and Open WebUI.

The scope is defined in the proposal. If you want to run Open WebUI in your own network, the route is the AI Cube.

Further Guides

• Open WebUI as an AI platform, features, operating options and packages.
• RAG knowledge base for public authorities, what to consider for public clients.
• RAG and the AI Act, when a knowledge base becomes a high-risk system.
• Open WebUI licence and branding, what the branding clause means for companies.
• Open WebUI vs. AnythingLLM, the comparison of both interfaces.
• Install Open WebUI on Linux, installer script with Docker and Caddy.
• Onyx self-hosted, enterprise search as an alternative.
• Shadow AI in companies, what an approved internal alternative looks like.
• AI solutions from WZ-IT, the hub with all offers for local AI and LLM operations.

Connect Open WebUI to your knowledge sources? We set up the automatic connection of your sources for Open WebUI instances run by WZ-IT and operate it. Sources, permissions and schedule are clarified beforehand. Book a meeting

Sources

• Open WebUI, Knowledge Base Sync (oikb)
• Open WebUI, oikb daemon, webhooks and deployment
• Open WebUI, knowledge bases and sync API
• oikb, GitHub repository
• Open WebUI, release v0.9.6