Installation Guide

English | 中文

This guide explains how to build, install, and first configure Vault2Dify.

Related docs:

Prerequisites

Obsidian desktop app.
A reachable Dify Knowledge Base API.
A Dify Knowledge Base API key with permission to list knowledge bases and create or update documents.
At least one Dify Knowledge Base.
Node.js and npm if you build from source.

Run these commands in the plugin source directory:

npm install
npm run build

The build creates main.js in the project root.

Create this folder inside your Obsidian vault:

.obsidian/plugins/vault-to-dify/

Copy only these files into it:

main.js
manifest.json
styles.css

Then restart Obsidian if needed and enable Vault2Dify from Settings -> Community plugins -> Installed plugins.

Open Settings -> Vault2Dify and complete the setup flow:

Enter your Dify Knowledge Base API key.
Enter the Dify service URL reachable from the device running Obsidian.
Click Test connection to verify the key, URL, permissions, and Dify API response.
Add a mapping from an Obsidian folder, Markdown note, or the entire vault to one or more Dify Knowledge Bases.

If knowledge bases change later in Dify, refresh the list from the mapping area.

Enter the service root that the Obsidian device can reach. The plugin appends Dify API paths such as /v1/datasets automatically.

Scenario	Use
Local Docker on the same computer	`http://localhost:5000`
NAS/Docker or LAN server	`http://dify-host.example.test:5000`
NAS through Tailscale	`http://tailnet-device.example.test:5000`
Cloud server with public port	`http://public-ip:2280`
Reverse proxy or Dify Cloud	`https://dify.example.com`

Rules:

Do not use localhost unless Dify and Obsidian run on the same computer.
Do not use container-only hostnames such as api:5001.
If you omit http:// or https://, the plugin tries http://.
If you paste a URL ending in /v1 or /v1/datasets, the plugin normalizes it to the service root.

Example:

Configured URL: http://dify-host.example.test:5000
Knowledge-base request: http://dify-host.example.test:5000/v1/datasets

Use docs/CONNECTION_TROUBLESHOOTING.md for the full connection matrix.

Quick checks:

Confirm Dify is running and reachable from the Obsidian device.
Confirm the API key belongs to the same Dify instance and has knowledge-base permissions.
Confirm the configured URL points to Dify, not to a NAS/admin web page.
Confirm a reverse proxy forwards /v1/datasets.
If files do not sync, confirm they are .md files and match an enabled mapping with at least one selected knowledge base.

GitHub releases should attach only the user-installable plugin files:

main.js
manifest.json
styles.css

Do not include: