Step 1 — Create a Cloudflare R2 bucket

1. Log in to dash.cloudflare.com.
2. Go to R2 Object Storage and create a new bucket. Name it anything (e.g. my-obsidian-vault).
3. Under R2 → Manage R2 API Tokens, create a token with Object Read & Write permission scoped to your bucket.
4. Copy the Access Key ID, Secret Access Key, and your Account ID.

Step 2 — Install the plugin

1. In Obsidian, open Settings → Community Plugins → Browse.
2. Search for Secure Smart Sync and install it.
3. Enable the plugin after installation.

Step 3 — Configure credentials

1. Open Settings → Secure Smart Sync.
2. Enter your Account ID, Bucket Name, Access Key ID, and Secret Access Key.
3. Set an encryption password. This is used to encrypt all files before upload — keep it safe.
4. Click Test Connection to verify everything is working.

Step 4 — First sync

Click the sync icon in the ribbon or run Secure Smart Sync: Manual Sync from the command palette. Your vault will be encrypted and uploaded to R2.

1. Installation

1. Go to the Releases page on GitHub and download the latest main.js, manifest.json, and styles.css.
2. Open your vault's hidden config folder — .obsidian at the root of your vault.
3. Navigate to .obsidian/plugins/. Create this folder if it doesn't exist.
4. Create a new folder inside plugins/ named exactly Secure-Smart-Sync.
5. Move the three downloaded files into that folder.
6. In Obsidian: Settings → Community Plugins, refresh the list, and toggle Secure-Smart-Sync on.

2. Cloudflare R2 Setup

SSS uses Cloudflare R2 as its storage backend. You own and control the bucket — no third party has access to your files.

1. Log in to dash.cloudflare.com. Navigate to R2 Object Storage in the sidebar.
2. If prompted, add a payment method to activate R2.
3. Click Create bucket. Choose a name such as my-obsidian-vault-sync. Leave location as Automatic. Click Create bucket.

3. Generating API Credentials

1. On the R2 Overview page, click Manage R2 API Tokens (top-right).
2. Click Create API Token. Give it a recognisable name (e.g. "Obsidian Sync Key").
3. Set Permissions to Object Read & Write.
4. Under Specify bucket(s), select Apply to specific buckets only and choose your bucket.
5. Click Create API Token.

4. Entering Credentials in Obsidian

Open Settings → Secure-Smart-Sync and fill in:

Optional: Set a Remote Prefix if you want your vault stored in a subfolder within the bucket. Toggle Sync .obsidian Config Directory to also sync themes, snippets, and plugin settings.

Click Test Connection at the bottom of the section to verify the plugin can reach your bucket.

5. Encryption (Strongly Recommended)

Without a password your files are uploaded in plaintext. To maintain true zero-knowledge privacy, set an encryption password before your first sync.

1. Enter a strong Password in the Encryption section.
2. Choose an Encryption Method: openssl-base64 encrypts file content only; rclone-base64 encrypts content and file names.

6. The First Sync

Do not hit the ribbon sync button for your very first run. Use the Command Palette instead:

1. Open the Command Palette (Ctrl/Cmd + P) and run Secure-Smart-Sync: Dry run (show what would change). This scans without moving files. Check the Developer Console (Ctrl/Cmd + Shift + I) to verify the plan looks correct — it should list all your local files as "to push".
2. Once satisfied, run Secure-Smart-Sync: Sync now from the Command Palette.
3. After the primary device finishes, trigger Sync now on each secondary device to pull the encrypted files down.

7. Device Pairing (Mobile / Other Devices)

Avoid manually re-entering long API keys on mobile. Use the built-in encrypted pairing relay instead.

8. Sync Settings

9. Automation — Smart Sync vs Manual

Smart Sync timing controls:

If you turn Smart Sync Off, manual triggers are available: Sync on App Open, Auto-Sync Interval, Sync on Save Debounce, and Sync on Idle. Note that manual mode does not include real-time cross-device awareness.

10. Status Indicators

Auto-syncs run silently — no pop-up toasts unless you trigger manually. Color cues communicate state instead:

On mobile, a small custom icon sits next to the sidebar toggle on the main dashboard. On desktop, the ribbon icon and the bottom-right status bar both reflect live sync state.

11. Advanced & Danger Zone

1. Privacy First

Personal notes are deeply private. They may contain journals, research, unfinished writing, or information users never intend to share. Secure Smart Sync treats privacy as non-negotiable. Files are encrypted before leaving your device. No third-party server can inspect your notes. Convenience should never come at the cost of privacy.

2. User Experience Matters

A technically functional product is not automatically a usable product. Significant development time has gone into small UX decisions that collectively make the plugin significantly easier to use — the mobile sync indicator, the encrypted relay for device pairing, and this documentation site all exist because friction reduction matters.

3. Long-Term Reliability

The definition of "done" is not whether a feature technically works once. It is whether the system remains reliable across messy real-world Obsidian workflows over long periods. Users go offline. They create conflicts. They reopen devices after long inactivity. The plugin is built with these scenarios in mind — conflict handling, duplicate protection, deletion safeguards, and sync state awareness are all part of the foundation, not afterthoughts.

1. Virtual File System Layer

The plugin operates on Obsidian's VFS abstraction. The sync engine only interacts with abstract providers — a Local Provider (reads/writes vault files) and a Remote Provider (interacts with R2 via a custom AWS S3 SDK implementation with a FetchHttpHandler wrapping Obsidian's requestUrl(), bypassing CORS limitations).

2. Three-Way Sync Engine

Every sync decision compares three states: local, remote, and previous sync. ETags and metadata provide additional validation to prevent accidental overwrites, missed changes, deletion mistakes, and conflict-related data loss.

3. Cryptographic Pipeline

Encryption is handled through a dedicated pipeline. Heavy cryptographic operations are offloaded to Web Workers so Obsidian doesn't freeze on large files.

4. Device Coordination Layer (Smart Sync)

R2 is intentionally treated as dumb object storage. A lightweight sentinel file stored on R2 allows devices to detect when another device has performed meaningful sync activity. The plugin uses a dynamic polling mechanism — active, idle, standby, and post-sync intervals — most of which are exposed to users for fine-grained control.

5. Encrypted Relay System

Credential onboarding across devices is handled by an encrypted relay using Cloudflare Workers KV. Credentials are transmitted encrypted, stored temporarily, and self-destruct after approximately 10 minutes. The relay source code is publicly available at Secure-Smart-Sync-relay.

Zero Egress Fees

Traditional object storage (AWS S3, Google Cloud Storage) charges for downloading data — and in a multi-device sync workflow, every upload by one device must be downloaded by all others. Cloudflare R2 charges $0 for data egress. Users only pay for storage and operations, making costs entirely predictable.

Generous Free Tier

For the vast majority of personal Obsidian users, Secure Smart Sync is completely free to operate:

• 10 GB free object storage per month
• 1 million Class A (write/list) operations per month
• 10 million Class B (read) operations per month
• Unlimited free egress bandwidth

S3 API Compatibility

R2 implements the widely adopted S3 API, allowing use of the official @aws-sdk/client-s3 library — battle-tested SDKs with reliable multipart uploads, streaming, and error handling — rather than writing custom API wrappers.

Simplified Setup

Creating a bucket and generating a scoped API token on Cloudflare's dashboard takes under 60 seconds. AWS IAM, in comparison, requires navigating users, policies, and roles — a significant barrier for non-technical users.

Technical Trade-offs

The Problem with Toasts

Early versions relied on popup toast notifications. These were intrusive and disrupted the writing experience. Disabling them on desktop was fine because the status bar provided visibility — but on mobile, removing toasts left users completely blind to background sync activity.

The Solution

A small sync status indicator is placed directly on the mobile dashboard, positioned next to the sidebar icon. It is intentionally minimal so it feels native to Obsidian rather than like an external UI element. It only appears on the main dashboard and disappears in settings or when the sidebar is open.

Indicator States

On desktop, the same color cues are applied to the ribbon icon. Desktop users also benefit from the persistent status bar for sync visibility.

Operation Types

Per Sync Cycle (one file, two devices)

Typical Monthly Estimates

Secure Smart Sync (SSS) is an open-source project created by an independent solo developer, Sen, as a free and privacy-focused alternative to Obsidian Sync.

The plugin was built to give users full ownership over their notes by allowing them to sync their Obsidian vaults through their own Cloudflare R2 storage while keeping files encrypted locally before upload. The public release of SSS v1.0.0 was reached after 26 major iterations of the codebase.

All branding assets — including the project name, logos, icons, and visual identity — were created by Sen and remain exclusive to this project. While the source code is licensed under the MIT License, the branding assets are not covered under that license.