Fast Note Sync: Self-Hosted, Real-Time Obsidian Sync Across Devices

Why Self-Host Your Note Sync?

Most Obsidian users have run into this problem: you write notes on your work computer, open your laptop at home, and they are missing. You capture an idea on your phone, return to your desktop, and it is missing too.

Obsidian Sync costs $5 a month, roughly RMB 35. That is not especially expensive, but large vaults, lots of attachments, or a company network that restricts external connections can make it unsuitable.

Alternatives such as Remotely Save with S3 or WebDAV can work, but setup can be cumbersome, sync can lag, and conflicts are common.

That is where Fast Note Sync comes in.

It is an open-source package comprising a client plugin and a self-hosted server. Deploy the backend on your own server and install the plugin on every device to get:

• ✅ Real-time sync in milliseconds through WebSocket pushes rather than polling
• ✅ Mac, Windows, iOS, and Android support
• ✅ Attachment sync for images, videos, and PDFs
• ✅ Note history and a recycle bin
• ✅ One-click note-sharing links
• ✅ Automatic Git backups
• ✅ MCP support so AI tools can read and write your notes
• ✅ Multiple storage backends: S3, OSS, R2, WebDAV, and local storage

It is free, and your data stays under your control.

GitHub: https://github.com/haierkeys/obsidian-fast-note-sync

At the time of writing, the plugin had 2.4k stars, the server had 1.6k stars, and the community plugin had more than 170,000 downloads, with active maintenance.

This guide walks through the setup from scratch.

Understand the Architecture First

Before starting, take a look at how the components fit together:

The server runs on your own machine—a VPS, NAS, or even a Raspberry Pi. The client is an Obsidian plugin. They communicate in real time through WebSocket connections. A note change on any device is pushed to all other connected devices within milliseconds.

Step 1: Deploy Fast Note Sync Service

The server is the core of the system, so set it up first. There are three official deployment options, listed here in order of preference.

Option 1: One-Command Installer for Linux and macOS

This is the simplest option: one command handles installation, configuration, and startup on boot.

Connect to your server over SSH and run:

bash <(curl -fsSL https://raw.githubusercontent.com/haierkeys/fast-note-sync-service/master/scripts/quest_install.sh)

For users in mainland China, the Tencent CNB mirror can be faster:

bash <(curl -fsSL https://cnb.cool/haierkeys/fast-note-sync-service/-/git/raw/master/scripts/quest_install.sh) --cnb

The installer:

1. Detects your operating system and CPU architecture.
2. Downloads the matching prebuilt binary.
3. Installs it in /opt/fast-note and creates the fns command in /usr/local/bin/fns.
4. Registers a systemd service on Linux or a launchd service on macOS to start on boot.

After installation, manage the service with fns:

fns              # Open the interactive menu, recommended for beginners
fns start        # Start the service
fns stop         # Stop the service
fns status       # Check service status
fns update       # Update to the latest version

Option 2: Docker

If your server already runs Docker, this is a convenient option.

Using Docker Run:

# Pull the image
docker pull haierkeys/fast-note-sync-service:latest

# Start the container
docker run -tid --name fast-note-sync-service \
    -p 9000:9000 \
    -v /data/fast-note-sync/storage/:/fast-note-sync/storage/ \
    -v /data/fast-note-sync/config/:/fast-note-sync/config/ \
    haierkeys/fast-note-sync-service:latest

-p 9000:9000 maps the container’s port 9000 to the host. If that host port is occupied, use a mapping such as -p 9527:9000.

The -v mounts persist data and configuration. Mount both directories outside the container so deleting the container does not delete your data.

Using Docker Compose, recommended for teams or long-term use:

Create docker-compose.yaml:

version: '3'
services:
  fast-note-sync-service:
    image: haierkeys/fast-note-sync-service:latest
    container_name: fast-note-sync-service
    restart: always
    ports:
      - '9000:9000'
    volumes:
      - ./storage:/fast-note-sync/storage
      - ./config:/fast-note-sync/config

Start it:

docker compose up -d

Option 3: Install the Binary Manually

Download the archive for your operating system from the Releases page, extract it, and run:

tar -xzf fast-note-sync-service_linux_amd64.tar.gz
./fast-note-sync-service run -c config/config.yaml

This option does not provide process supervision out of the box. It works for trying the service; for long-term use, use systemd or screen to keep it running.

After Deployment: Open the Port and Management Panel

Whichever deployment method you choose, open this address once the service starts:

http://YOUR_SERVER_IP:9000

If you use a cloud server from Alibaba Cloud, Tencent Cloud, AWS, or another provider, allow port 9000 in its security group or firewall.

On your first visit, register an account with your email address and password. The first registered user should be configured as the administrator, as described below.

Step 2: Configure the Server

After registering and signing in, open the web management panel. The interface shown in the screenshots is in Chinese.

2.1 Create a Vault

In the sidebar, select Note vaults, click New, enter a name such as MyNotes, and save.

One user can create multiple vaults—for example, separate work and personal notes.

2.2 Get the Authorization Configuration

This is the key step for connecting clients.

On the vault page, find the vault you created and select Authorize Obsidian.

• Desktop, Mac or Windows: the button launches Obsidian and fills in the authorization details automatically.
• Mobile, iOS or Android: one-click launching is not currently supported. Select Copy API configuration, copy the JSON, and paste it into the mobile plugin later.

2.3 Adjust Key Settings, Optional but Recommended

The default configuration works out of the box, but you may want to adjust a few settings in config/config.yaml in the server directory:

# === Security ===
security:
  auth-token-key: fast-note-sync-Auth-Token # Replace with your own random string
  token-expiry: '365d' # Token lifetime; 365 days is usually sufficient

# === User management ===
user:
  register-is-enable: true # Set to false after setup if you are the only user
  admin-uid: 0 # Set your user UID, available in the management panel's user list

# === Logging ===
log:
  level: warn # Use debug for troubleshooting; warn or info for normal operation

# === Storage ===
storage:
  local-fs:
    is-enable: false # Local filesystem storage is sufficient for a basic setup
    save-path: 'storage/uploads'

Restart the service after changing configuration: fns restart or docker restart fast-note-sync-service.

2.4 Configure Nginx and HTTPS, Optional

If you have a domain name, a reverse proxy and SSL certificate let you access the service securely at an address such as https://notes.yourdomain.com.

Example Nginx configuration:

server {
    listen 443 ssl;
    server_name notes.yourdomain.com;

    ssl_certificate     /etc/ssl/certs/yourdomain.pem;
    ssl_certificate_key /etc/ssl/private/yourdomain.key;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";       # Required for WebSocket
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;                    # Long-lived WebSocket connections
    }
}

Set a sufficiently long proxy_read_timeout; otherwise, Nginx may terminate WebSocket connections and interrupt syncing.

Step 3: Install the Client Plugin

With the server ready, install the plugin on each device.

3.1 Desktop: Mac, Windows, or Linux

Open Obsidian → Settings → Community Plugins → turn off safe mode → Browse → search for Fast Note Sync → install and enable it.

If you used one-click authorization in the management panel, the plugin is already configured.

For manual setup, paste the API configuration JSON into the configuration field in the plugin settings.

3.2 Mobile: iOS or Android

Follow the same flow: Settings → Community Plugins → search for and install Fast Note Sync.

Then copy the API configuration from the management panel and paste it into the mobile plugin.

On iOS, if pasting fails, try pasting into Apple Notes first, then copying it again. This is a known issue with Obsidian on iOS.

The connected-service status indicates that setup is complete.

3.3 Verify Syncing

After installation, a Fast Note Sync icon appears at the bottom of Obsidian’s left sidebar. Click it to view sync status and logs.

Run a simple test:

1. Create a test note on your desktop and write a few lines.
2. Open Obsidian on your phone, wait a few seconds, and check that the note appears.
3. Edit the same note on your phone.
4. Return to your desktop and check for the update.

If everything works, your private sync system is running. 🎉

Step 4: Configure Advanced Features

Once basic syncing works, these features can improve the experience.

4.1 Sync Exclusions and Allowlists

For files you do not want to sync, such as .obsidian/workspace.json or large attachments, configure the plugin settings:

• Exclusion rules: glob patterns such as **/.obsidian/workspace* exclude workspace files.
• Allowlist mode: sync only selected directories or files.

4.2 Note History and the Recycle Bin

On the management panel’s vault page, select a note to view its history:

• Each edit saves a snapshot with a 10-second debounce.
• Compare differences and restore any previous version.
• Deleted notes enter the recycle bin, which retains them for seven days by default and supports restoration.

4.3 Share Notes

Click the share button beside a note in the management panel to:

• Generate a link for online previews without Obsidian.
• Set an access password.
• Generate a short link.
• View access statistics.

This is useful for sharing notes with friends or colleagues who do not use Obsidian.

4.4 Automatic Git Backups

Enable Git in config.yaml to automatically commit and push note changes to a remote repository:

git:
  name: 'FNS Service'
  email: 'fns@email.com'

A private GitHub repository provides another layer of off-site backup.

Initialize a Git repository in the note-storage directory on the server, configure its remote, and restart the service. See the GitHub repository for details.

4.5 S3, OSS, or R2 Storage Backups

If you have many large attachments, switch attachment storage to an object-storage backend:

storage:
  aws-s3:
    is-enable: true
    # ... Set the S3 access key, bucket, and region

Supported backends include Alibaba Cloud OSS, AWS S3, Cloudflare R2, MinIO, and WebDAV. The storage section in config.yaml documents the settings.

Step 5: MCP Integration for AI Access to Notes

This is one of Fast Note Sync’s most useful features.

MCP, the Model Context Protocol, connects AI tools to external systems. FNS can act as an MCP server, allowing Claude Code, Cursor, Cherry Studio, and other AI clients to read and write your Obsidian notes.

Configuration for Claude Code or Cursor

Add this to your MCP client configuration:

{
	"mcpServers": {
		"fns": {
			"url": "http://YOUR_SERVER_IP:9000/api/mcp",
			"type": "http",
			"headers": {
				"Content-Type": "application/json",
				"Authorization": "Bearer YOUR_API_TOKEN",
				"X-Default-Vault-Name": "MyNotes",
				"X-Client": "Claude Code",
				"X-Client-Version": "1.0",
				"X-Client-Name": "Mac"
			}
		}
	}
}

Find your API token in the JSON returned by Copy API configuration in the management panel.

You can then ask your AI client to:

• “Turn today’s meeting minutes into an Obsidian note.”
• “Search my knowledge base for every note about microservice architecture.”
• “Write a summary based on my recent reading notes.”

FNS synchronizes the resulting content across all your devices in real time.

Troubleshooting

Mobile syncing is intermittent

iOS and Android restrict background processes. Check the following:

• On iOS, turn off Low Power Mode and allow background refresh for Obsidian.
• On Android, disable battery optimization and allow Obsidian to start automatically.
• If you have not opened the mobile app for a while, give it a few seconds to sync.

What happens when notes conflict?

FNS prioritizes the latest modification time and saves older versions in the history. If important content is overwritten, recover it from the management panel’s version history.

Memory or disk usage is too high

• SQLite is the default database and is sufficient for personal use with low memory consumption.
• For many attachments, use object storage rather than keeping large files on the server’s local disk.
• Limit retained versions with app.history-keep-versions.

Can I use it without a server?

No. FNS uses a client/server architecture and requires a server. The cost can be low: a one-core, 1 GB cloud server, home NAS, Raspberry Pi, or spare laptop running Linux can host it.

Strengths and Tradeoffs

Final Thoughts

Obsidian’s central idea is that you own and control your data. If that is why you chose a local-first note-taking tool, your sync setup should follow the same principle: your data passes through your own server, rather than someone else’s cloud.

Fast Note Sync offers a strong balance of features and straightforward deployment. Its server combines Go, WebSocket, and React, the client is responsive, and the project continues to evolve quickly.

Spend half an hour setting up the server and five minutes configuring the clients, and your notes can move automatically across devices. That convenience makes the setup time worthwhile.