---
title: Obsidian
description: Sync your Obsidian vault with the SurfSense plugin
---

# Obsidian Plugin Setup Guide

SurfSense integrates with Obsidian through the SurfSense Obsidian plugin.
The old server-side vault path scanner is no longer supported.

## How it works

The plugin runs inside your Obsidian app and pushes note updates to SurfSense over HTTPS.
This works for cloud and self-hosted deployments, including desktop and mobile clients.

## What gets indexed

| Content Type | Description |
|--------------|-------------|
| Markdown files | Note content (`.md`) |
| Frontmatter | YAML metadata like title, tags, aliases, dates |
| Wiki links | Linked notes (`[[note]]`) |
| Tags | Inline and frontmatter tags |
| Vault metadata | Vault and path metadata used for deep links and sync state |

## Quick start

1. Open **Connectors** in SurfSense and choose **Obsidian**.
2. Click **Open plugin releases** and install the latest SurfSense Obsidian plugin.
3. In Obsidian, open **Settings → SurfSense**.
4. Paste your SurfSense API token from the connector setup panel.
5. Paste your SurfSense backend URL in the plugin's **Server URL** setting.
6. Choose the Search Space in the plugin, then run the first sync.
7. Confirm the connector appears as **Obsidian — <vault>** in SurfSense.

<Callout type="info">
    You do not create or configure a vault path in the web UI. The connector row is created automatically when the plugin calls `/api/v1/obsidian/connect`.
</Callout>

## Self-hosted notes

- Use your public or LAN backend URL that your Obsidian device can reach.
- No Docker bind mount for the vault is required.
- If your instance is behind TLS, ensure the URL/certificate is valid for the device running Obsidian.

## Troubleshooting

**Plugin connects but no files appear**
- Verify the plugin is pointed to the correct Search Space.
- Trigger a manual sync from the plugin settings.
- Confirm your API token is valid and not expired.

**Unauthorized / 401 errors**
- Regenerate and paste a fresh API token from SurfSense.
- Ensure the token belongs to the same account and workspace you are syncing into.

**Cannot reach server URL**
- Check that the backend URL is reachable from the Obsidian device.
- For self-hosted setups, verify firewall and reverse proxy rules.
- Avoid using localhost unless SurfSense and Obsidian run on the same machine.
