Obsidian Integration Guide

This guide explains how to connect your Obsidian vault to AINexLayer for note search and AI-powered insights.

How It Works

The Obsidian connector scans your local Obsidian vault directory and indexes all Markdown files. It preserves your note structure and extracts metadata from YAML frontmatter.

• For subsequent indexing runs, the connector uses content hashing to skip unchanged files for faster sync.
• Configure periodic indexing to ensure updates appear in your search results within minutes.

What Gets Indexed

Quick start

1. Open Connectors in SurfSense and choose Obsidian.
2. Install the plugin (recommended via BRAT) using the steps below.
3. In Obsidian, open Settings → SurfSense.
4. Paste your SurfSense API token from the user settings section.
5. Paste your Server URL in the plugin setting: either your SurfSense main domain (if /api/v1 rewrites are enabled) or your direct backend URL.
6. Choose the Search Space in the plugin, then the first sync should run automatically.
7. Confirm the connector appears as Obsidian - <vault> in SurfSense.

Install via BRAT (recommended)

1. In Obsidian, open Settings → Community plugins and install BRAT.
2. Open BRAT settings and click Add beta plugin button.
3. Paste the repository: https://github.com/MODSetter/SurfSense/.
4. Select the latest plugin version, then click "Add plugin".
5. Open Settings → SurfSense to finish setup.

Migrating from the legacy connector

If you previously used the legacy Obsidian connector architecture, migrate to the plugin flow:

1. Delete the old legacy Obsidian connector from SurfSense.
2. Install and configure the SurfSense Obsidian plugin using the quick start above.
3. Run the first plugin sync and verify the new Obsidian - <vault> connector is active.

Step 1: Quick Start (Local Installation)

1. Navigate to Connectors → Add Connector → Obsidian
2. Enter your vault path: /Users/yourname/Documents/MyVault
3. Enter a vault name (e.g., Personal Notes)
4. Click Connect Obsidian

Docker Setup

For Docker deployments, you need to mount your Obsidian vault as a volume.

Step 2: Docker Setup

Step 2.1: Update docker-compose.yml

Add your vault as a volume mount to the AINexLayer backend service:

services:
  AINexLayer:
    # ... other config
    volumes:
      - /path/to/your/obsidian/vault:/app/obsidian_vaults/my-vault:ro

Troubleshooting

Vault not found / Permission denied

• Verify the path exists and is accessible
• For Docker: ensure the volume is mounted correctly in docker-compose.yml
• Check file permissions: AINexLayer needs read access to the vault directory

Self-hosted URL issues

• Use a public or LAN backend URL that your Obsidian device can reach.
• If your instance is behind TLS, ensure the URL/certificate is valid for the device running Obsidian.

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.