Intermediate 12 minDaily plan

Open WebUI: syncing a folder with oikb

An open laptop casts green light across a dark desk.

Importing documents by hand into an Open WebUI knowledge base works as long as the folder doesn't change. Once it's live (procedures updated, notes added, files removed), the knowledge base drifts and the model answers from outdated versions. Syncing a folder with Open WebUI via oikb, the tool featured in the Ecosystem section of the official documentation, aims to fix that drift. This guide explains how incremental sync works, what it can delete, and a cautious procedure: backup, narrow scope, test knowledge base. It has not been tested by our editorial team.

By Mohamed Meguedmi·Update 2026-11-18·Tested on Windows, macOS, and Linux
!
This guide doesn't reproduce any oikb commands
Our editorial team consulted the official page docs.openwebui.com/ecosystem/knowledge-base-sync/ on 30/10/2026, but couldn't recheck it at the time of writing (18/11/2026). Instead of reproducing from memory a syntax that may have changed, this guide points you to that page for installing oikb and for its exact options. The commands given here cover backup, scope, and checks, which don't depend on the tool.

#Why sync a folder with Open WebUI

An Open WebUI knowledge base (Knowledge) is a collection of files split into chunks and indexed as embeddings. When you attach this knowledge base to a model or reference it with # in the chat, Open WebUI retrieves the chunks closest to the question and adds them to the context. The guide “RAG local avec Ollama sans coder” explains how this works in the interface.

The problem shows up over time. A file modified on disk isn't modified in the knowledge base: Open WebUI keeps the imported version. A file deleted from the folder can still be queried. A new file doesn't exist until someone imports it. With a folder of just a few documents, you can get by with reimporting. With a folder of internal procedures or notes that changes every week, manual reimporting gets forgotten, and the assistant confidently cites an abandoned procedure.

A sync tool automates this work: it compares the folder with what has already been uploaded and sends only the difference. This is called incremental sync. The trade-off is that a tool that automatically adds and replaces can also automatically remove. That's the point that needs the most attention.

#Incremental sync: source, destination, state

The complete kit for building your own AI assistant.

Benefit from our experience and a guided path to build your local assistant and use your AI every day.

  • Lifetime online access
  • PDF + files
  • Refunded within 30 days

Whatever the tool, this kind of sync relies on three elements. Understanding them lets you read the oikb documentation with the right questions in mind.

The source
The local (or mounted) folder whose contents are the source of truth. Everything in it, within the chosen scope, is meant to end up in the knowledge base. That's why you need to define it carefully: a personal subfolder forgotten inside will be indexed and become queryable by anyone with access to the knowledge base.
The destination
A specific Open WebUI knowledge base, on a specific instance (URL). A wrong knowledge base ID can mix two corpora, or worse, apply deletions to the wrong knowledge base.
L'authentification
The tool acts through the Open WebUI API with a key tied to an account. It inherits that account's permissions: whatever the account can read, modify, or delete, the tool can too.
The state
To know what has changed, the tool must keep track of what it has already uploaded (content hashes, modification dates, mapping between local files and files on the Open WebUI side), or rebuild that record by querying the knowledge base. If this state is lost or out of sync, the tool may re-upload everything, create duplicates, or misinterpret missing files.

With this information, each run sorts files into four cases: new (to upload), modified (to replace), unchanged (to skip), gone from the source (to remove from the knowledge base, or to keep, depending on the setting). Before running oikb, look in its documentation for the answers to four questions: how it detects a change, where it stores its state, whether it removes files that have disappeared and under which option, and whether it offers a dry-run mode that shows the actions without executing them.

#The real risk: mirrored deletions

A sync that removes files from the knowledge base when they're missing from the source is useful: it's what makes the abandoned procedure disappear. But it turns any error on the source side into data loss on the knowledge base side. A few realistic scenarios:

Drive not mounted
The folder points to a network share or external drive that is missing at the time of the run. The mount point is empty: as far as the tool is concerned, all the files have disappeared.
Wrong path
A typo or a change of working directory makes the source point to an empty or different folder.
Reorganization
Renaming or moving subfolders may be seen as “delete everything, then recreate everything.” The end result may be correct, but the knowledge base is fully reindexed and any links to the old files are lost.
Shared knowledge base
If other people have manually added files to the same knowledge base, a strict mirroring tool may treat those files as foreign to the source and remove them. Check the documentation to see whether oikb only touches files it uploaded itself.

Two rules follow from this. First, a synced knowledge base should be reserved for syncing: no manual additions to it. Second, until you have observed how the tool behaves on a test knowledge base, don't enable deletion on the one you use every day.

#Prerequisites

A working Open WebUI
An up-to-date instance connected to Ollama (by default on http://localhost:11434), with an embedding model configured. The guide “Open WebUI avec Ollama: guide complet” covers installation.
A dedicated account
Ideally a user account created for syncing that owns the knowledge base, rather than the admin account. The key's scope is then limited to what this account needs.
Allowed API keys
Depending on the version, the administrator must enable API keys in the admin settings before a user can generate one from Settings > Account. The exact labels vary: refer to your version.
A recent backup
A verified archive of the Open WebUI Docker volume. It's the only real way back if the knowledge base is emptied by mistake.
oikb-specific prerequisites
The language, version, and installation method are listed on the official page. Don't assume them.

#Syncing a folder with Open WebUI: the 5-step procedure

  1. 01
    1. Back up the instance
    Stop the container, archive the volume, restart, and compute a checksum. The full procedure, including restoration, is in the guide “Restoring Open WebUI and Ollama after a failure”. A backup that has never been restored is just an assumption: test it at least once on a control instance.
  2. 02
    2. Define the scope
    Don't point oikb at your entire Documents folder. Set up a publishing folder that contains only the files meant for the knowledge base, in formats Open WebUI can extract (plain text, Markdown, text-based PDF, etc.). Take an inventory of it: that's your reference for later checking what actually made it into the knowledge base.
  3. 03
    3. Create a test knowledge base and a key
    In Workspace > Knowledge, create a knowledge base named, for example, “sync-test”. Its ID appears in the URL of the knowledge base's page. Generate the API key for the sync account, store it in a file only you can read, and check that it works with a simple call.
  4. 04
    4. First run on the test knowledge base
    Install oikb and run it as described on the official page, with the test knowledge base as the destination, without deletion, and in dry-run mode if the tool offers one. Read the list of announced actions before starting the real run. Then compare the number of files in the knowledge base with your inventory.
  5. 05
    5. Test the edge cases, then switch over
    On the test knowledge base: modify a file, add one, delete one, and run it again. Check that only the modified file is replaced and that the deleted file is handled the way the documentation says. Then temporarily empty the source (rename the folder) and see what the tool plans to do: this is the unmounted-disk test. Only after that should you point oikb at the real knowledge base.

Step 2 can use rsync to build the publishing folder from a working folder, keeping only certain extensions. The example below copies Markdown and PDF files, preserves the directory structure, and ignores everything else. It does not use --delete: a file removed from the working folder stays in the publishing folder until you remove it, which leaves a human decision before any deletion on the knowledge base side.

Terminal — step 2: publishing folder and inventory
# Dossier de travail (à adapter) et dossier réservé à la synchronisation
SOURCE=~/Documents/procedures/
PUBLI=~/oikb-publication/
mkdir -p "$PUBLI"

# Simulation d'abord (-n), puis relancer sans -n
rsync -avn --prune-empty-dirs \
  --include='*/' --include='*.md' --include='*.pdf' --exclude='*' \
  "$SOURCE" "$PUBLI"

# Inventaire daté avec empreintes, à garder avec la sauvegarde
cd "$PUBLI" && find . -type f -print0 | sort -z | xargs -0 sha256sum \
  > ~/sauvegardes-ia/inventaire-oikb-$(date +%F).txt
wc -l ~/sauvegardes-ia/inventaire-oikb-$(date +%F).txt

For step 3, you can test the key without changing anything. The Open WebUI API accepts a key in the Authorization: Bearer header; the call below lists the models visible to the account. A JSON response confirms that the URL and key are correct; a 401 or 403 error indicates an invalid key or that API keys are not allowed by the administrator.

Terminal — step 3: key kept out of history and read-only test
# Clé dans un fichier privé, pas dans l'historique du shell
install -m 600 /dev/null ~/.config/oikb-cle
${EDITOR:-nano} ~/.config/oikb-cle

U=http://localhost:3000
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $(cat ~/.config/oikb-cle)" \
  "$U/api/models"

Port 3000 matches the most common Docker command (-p 3000:8080); adjust it to your setup. How oikb reads the key (environment variable, option, configuration file) is described in its documentation: prefer a variable or a file over command-line options, which remain visible in the process list and shell history.

→
One knowledge base per source
Map each publishing folder to a single knowledge base, and give both the same name (“quality-procedures” for the folder and the knowledge base). If you're ever unsure where a run is headed, the name alone is enough to catch the mistake before it spreads.

#Automating the sync without exposing yourself

Once you've observed the behavior on the test knowledge base, it's tempting to schedule a run every hour. Before doing that, add a few safeguards that don't depend on the tool.

Check the source before each run
A script that refuses to start the sync if the publishing folder is empty or if its file count drops sharply compared to the last inventory. This is the simplest protection against an unmounted drive.
Keep a log
Redirect the output of each run to a dated file. If the assistant gives a surprising answer, the log shows when a file entered or left the knowledge base.
Space out runs
For documents that change a few times a week, a daily run is enough and reduces the indexing load on the machine computing the embeddings.
Back up before, not just after
A regular backup of the volume, independent of the sync. If a run empties the knowledge base, restoring also brings back the embeddings without reindexing everything.
Terminal — pre-run safeguard
#!/usr/bin/env bash
set -euo pipefail
PUBLI=~/oikb-publication
MIN=10   # seuil à adapter : en dessous, on refuse

N=$(find "$PUBLI" -type f | wc -l)
if [ "$N" -lt "$MIN" ]; then
  echo "$(date -Is) source suspecte : $N fichiers, passage annulé" >&2
  exit 1
fi

# Lancer ici la commande oikb indiquée par la documentation officielle,
# en redirigeant sa sortie vers un journal daté.

This script intentionally does not include the oikb command: copy it from the official page and paste it where indicated. The MIN threshold is arbitrary; a finer-grained check compares the file count against the last inventory and refuses any drop greater than a certain proportion.

#Troubleshooting

401 or 403 from the API
The key is expired, revoked, or was copied with a space. Also check that the administrator allows API keys and that the account has access to the target knowledge base.
Files uploaded but not found in the chat
Uploading and indexing are two separate steps. A scanned PDF without a text layer may be accepted without producing any usable chunks. Open the file in the knowledge base to see the extracted text; run scans through OCR before publishing them.
Duplicates in the knowledge base
A common sign of lost state, or of a first run launched on a knowledge base that already contained the same files imported by hand. Start over from an empty knowledge base reserved for syncing.
Lengthy reindexing
Changing the embedding model in the Open WebUI settings requires reindexing your documents. Avoid changing this setting and the sync at the same time: you would no longer know which one caused a discrepancy.
Answers still outdated
Check in the knowledge base that the old version was actually replaced rather than added alongside it. Open a new conversation: chunks already cited in an existing conversation remain in its history.

#What was verified, and what wasn't

oikb was not tested for this guide: no installation, no run, and no measurement of duration or volume. The official documentation page was consulted on 30/10/2026 while preparing the topic, but couldn't be rechecked on 18/11/2026. The backup commands are taken from the site's restore guide. The key test uses the Bearer header and the /api/models route of the Open WebUI API; confirm this on your version. The questions to check against the documentation (change detection, state, deletions, dry run) are general criteria, not a description of how oikb works.

i
Keyword and search data
The topic was selected on 30/10/2026 based on the query « open webui synchroniser dossier ». The keyword research tool (DataForSEO, Google Ads, France) returned no search volume value, so interest in the query is neither confirmed nor quantified.

#Go further

Local RAG with Ollama without coding
How Open WebUI knowledge bases work in the interface, and when to prefer AnythingLLM: https://quelllm.fr/guide/rag-local-ollama-sans-coder
Restore Open WebUI and Ollama after a failure
Volume backup, restoration, and control instance, the prerequisites for step 1: https://quelllm.fr/guide/restaurer-open-webui-ollama-sauvegarde
Open WebUI with Ollama: complete guide
Installing the interface and basic settings: https://quelllm.fr/guide/open-webui-ollama-tutoriel
Primary source
Open WebUI, Ecosystem documentation, Knowledge Base Sync: https://docs.openwebui.com/ecosystem/knowledge-base-sync/ (accessed 30/10/2026, not rechecked on 18/11/2026).
Did this guide help you?

Feedback, an error, or a clarification? Let us know—it improves the guide for everyone.