Stop Paying for Obsidian Sync! YAOS Is the Secret Weapon

Stop Paying for Obsidian Sync! YAOS Is the Secret Weapon

What if I told you that every time you edit a note on your phone, then open your laptop to find a "conflicted copy" waiting for you — you're living in the past?

That gut-punch moment. That rage-inducing MyNote (conflicted copy 2024-01-15).md staring back at you. You've been there. We've all been there. The so-called "solutions" are either expensive subscriptions bleeding you dry, or janky self-hosted nightmares that demand you become a DevOps^{↗ Bright Coding Blog} engineer on weekends.

But what if real-time sync — the kind where your cursor position literally follows you across devices — didn't require a PhD in distributed systems? What if it cost zero dollars, needed zero terminal commands, and ran on infrastructure you actually own?

Enter YAOS: a zero-terminal, real-time sync engine for Obsidian powered by your own Cloudflare Worker. No database setup. No .env files to wrestle with. No $96/year subscription to Obsidian's official service. Just pure, conflict-free, CRDT-powered synchronization that makes your notes feel like they're living in one magical place — because technically, they are.

This isn't theoretical. This isn't vaporware. This is production-grade engineering that leverages Yjs CRDTs to eliminate conflicted copies forever, while deploying to Cloudflare's edge in under five minutes. If you're tired of choosing between expensive managed services and complex self-hosted alternatives, keep reading. Your note-taking workflow is about to get a serious upgrade.

What Is YAOS?

YAOS (short for "Yet Another Obsidian Sync" — though it's quickly becoming the Obsidian sync) is an open-source, real-time synchronization engine built specifically for Obsidian vaults. Created by Kavin Sood, YAOS represents a radical reimagining of how personal knowledge management should work: local-first, edge-deployed, and mathematically guaranteed to never produce conflicts.

The project sits at the intersection of several explosive trends in developer tooling: the resurgence of local-first software, the democratization of edge computing through platforms like Cloudflare, and the maturation of CRDT (Conflict-free Replicated Data Type) libraries like Yjs. What makes YAOS genuinely special isn't any single technology choice — it's the relentless elimination of operational complexity while preserving sophisticated distributed systems guarantees.

Traditional sync solutions ask you to choose between two miserable options: pay recurring fees for opaque managed services, or descend into self-hosted hell configuring databases, reverse proxies, and SSL certificates. YAOS introduces a third path: infrastructure-as-code deployment to Cloudflare Workers that requires literally zero terminal interaction. Click a button, claim your server, scan a QR code. Done.

The project's timing is impeccable. As developers and knowledge workers increasingly reject SaaS rent-seeking, tools that offer genuine ownership without operational burden are capturing attention. YAOS has trended across Hacker News, developer Twitter, and Obsidian community forums precisely because it solves a universal pain point with unexpected elegance.

The philosophy is explicit in the documentation: "If you want the official, fully managed experience, pay for Obsidian Sync and support the team. If you want a fast, self-deployed, local-first alternative on your own Cloudflare account, this is YAOS." This isn't anti-commercial — it's pro-choice. And for technical users who value control, that choice is increasingly obvious.

Key Features That Make YAOS Insane

CRDT Merge Semantics — Kill Conflicts Forever

YAOS doesn't "handle" conflicts. It obliterates the concept entirely. By using Yjs CRDTs, every edit becomes an operation that mathematically converges. Edit the same paragraph on three devices simultaneously? The CRDT merges all changes into a coherent result. No conflicted copies. No "which version do you want to keep?" dialogs. No data loss. This is the same foundational technology that powers Figma's multiplayer editing and Notion's real-time collaboration, now applied to your personal notes.

Zero-Terminal Deployment

The "Deploy to Cloudflare" button isn't marketing fluff — it's a genuine zero-ops pipeline. Cloudflare's Workers platform compiles and deploys the serverless backend without you touching wrangler CLI, editing wrangler.toml, or understanding what a Durable Object is. The claim-and-pair workflow uses browser-based authentication and obsidian://yaos deep links. Your grandmother could deploy this (assuming your grandmother uses Obsidian, which, respect).

Monolithic Vault CRDT with ACID Guarantees

Here's where YAOS gets architecturally sophisticated. Rather than treating each file as an independent CRDT document, YAOS maintains one vault-level Y.Doc containing all per-file CRDTs. This means cross-file operations are transactionally atomic. Rename a folder containing 200 notes? That's one atomic operation. The vault structure cannot "tear" into inconsistent states. This design choice trades horizontal scalability for correctness guarantees that matter deeply for personal knowledge bases.

Filesystem-CRDT Bridge with Dirty-Set Draining

Obsidian's file events are noisy. Rapid autosaves, plugin-triggered rewrites, and metadata updates could spam the CRDT with meaningless operations. YAOS implements sophisticated event deduplication: a dirty-set tracks pending changes, content-acknowledged suppression prevents echo loops, and controlled draining batches updates efficiently. Your disk stays a normal filesystem; the CRDT stays aligned without performance degradation.

Checkpoint + Journal Persistence Engine

Early versions of YAOS rewrote full state on every persistence event — catastrophic for large vaults. The engineering team (primarily Kavin) redesigned storage around state-vector-anchored delta journaling. Only changes since the last checkpoint are persisted, dramatically reducing write amplification. Durable Objects survive hibernation and restarts without data loss, maintaining sync room state across server lifecycles.

Content-Addressed Attachment Sync via R2

Images, PDFs, and other attachments bypass the text CRDT entirely, syncing through Cloudflare R2 with content-addressed storage. This prevents binary blobs from polluting the operational CRDT state while enabling efficient deduplication. Attachments are proxied natively through the Worker with bounded fan-out respecting Cloudflare's connection limits.

Real-World Use Cases Where YAOS Dominates

The Multi-Device Researcher

You're writing a paper. Laptop at your desk, tablet in the library, phone for capture on-the-go. With Dropbox or iCloud, you develop paranoid habits: "Did I let it finish syncing?" "Should I close Obsidian first?" YAOS eliminates this cognitive overhead entirely. Edit anywhere, anytime. The CRDT state converges automatically. Your cursor position even propagates across devices if you enable remote cursors. The mental model collapses to: "there is one vault."

The AI-Augmented Knowledge Worker

You're building agentic workflows — Claude, GPT-4, or local LLMs that read and write your vault files directly. Traditional sync breaks here: an AI edits todo.md while you're editing it on your phone, and suddenly you have todo (conflicted copy).md, todo (1).md, and existential despair. YAOS's filesystem bridge means external changes propagate cleanly through the CRDT. Scripts, git operations, and AI agents become first-class citizens of your sync topology.

The Privacy-Paranoid Professional

Client notes. Medical records. Journal entries. You cannot accept a third-party service having plaintext access. YAOS runs on your Cloudflare account with your Durable Objects storing your encrypted-at-rest state. The trust boundary is clear: Cloudflare's infrastructure, your code, your data. No opaque sync service parsing your notes for "improvements" or training data.

The Frugal Power User

Obsidian Sync costs $96/year. Dropbox Plus is $120/year. iCloud+ with sufficient storage adds up. YAOS is free at scale — Cloudflare Workers have generous free tiers, R2 storage is competitively priced, and the open-source license (0-BSD) imposes zero restrictions. For students, indie developers, or anyone optimizing subscription bloat, this is transformative.

Step-by-Step Installation & Setup Guide

Prerequisites

• An Obsidian installation (desktop or mobile)
• A Cloudflare account (free tier sufficient)
• A GitHub account (for BRAT plugin installation and update workflows)
• The BRAT plugin installed in Obsidian (for beta plugin management)

Step 1: Deploy Your Cloudflare Worker

Click the Deploy to Cloudflare button on the YAOS repository:

https://deploy.workers.cloudflare.com/?url=https://github.com/kavinsood/yaos/tree/main/server

This opens Cloudflare's deploy interface. Authenticate with your Cloudflare account, select or create a project, and deploy. The Worker compiles and provisions automatically — no terminal, no configuration files.

Step 2: Claim Your Server

Navigate to the deployed Worker URL (e.g., https://yaos-yourname.your-subdomain.workers.dev). Click Claim to lock the server to your identity. This generates your setup token — a cryptographically secure credential that pairs your Obsidian plugin with this specific Worker instance.

Step 3: Install the YAOS Plugin

YAOS is currently in Obsidian's marketplace review queue. For immediate access, use BRAT:

1. Open Settings → Community Plugins → BRAT
2. Click Add Beta plugin
3. Paste: kavinsood/yaos
4. Enable the plugin in Community Plugins

# BRAT installation path
Settings → Community Plugins → BRAT → Add Beta plugin → kavinsood/yaos

Step 4: Connect Your Vault

From the claim page, either:

• Click the setup link (deep-links to obsidian://yaos?token=...&server=...)
• Scan the QR code with your mobile device

YAOS auto-populates Server URL and Sync token in plugin settings. No manual copy-pasting of cryptic URLs.

Step 5: Configure R2 for Attachments (Optional but Recommended)

For image/PDF sync and snapshot backups:

1. In Cloudflare dashboard, create an R2 bucket
2. Bind it to your Worker as YAOS_BUCKET
3. In YAOS settings, enable Sync attachments

The R2 setup video demonstrates this visually.

Step 6: Initialize the Update Pipeline

One-time setup for seamless updates:

1. Settings → YAOS → Advanced → Initialize updater
2. GitHub opens with pre-filled workflow file
3. Commit the workflow

Future updates become: notification → click → Run workflow with update. Rollbacks use revert.

REAL Code Examples from the Repository

The following examples demonstrate YAOS's architecture and configuration patterns extracted directly from the project's documentation and engineering notes.

Example 1: Monolithic Vault CRDT Structure

YAOS's core architectural decision — one vault-level Y.Doc containing all file CRDTs:

// Conceptual structure of YAOS's vault-level Y.Doc
// Each markdown↗ Smart Converter file maps to a stable ID with Y.Text for content

const ydoc = new Y.Doc();

// Vault structure: a shared map of file IDs to their CRDTs
const files = ydoc.getMap('files');

// Each file gets: stable UUID, Y.Text for content, metadata
const fileId = generateStableId('path/to/note.md');
const ytext = new Y.Text();
ytext.insert(0, '# My Note\n\nInitial content...');

files.set(fileId, {
  path: 'path/to/note.md',      // Current filesystem path
  content: ytext,                // Y.Text CRDT for live collaboration
  created: Date.now(),
  modified: Date.now()
});

// Cross-file operations are ATOMIC because they're one Y.Doc transaction
ydoc.transact(() => {
  // Rename folder: update all affected paths in single transaction
  for (const [id, file] of files) {
    if (file.path.startsWith('old-folder/')) {
      file.path = file.path.replace('old-folder/', 'new-folder/');
    }
  }
});
// Folder rename cannot tear — all paths update together or not at all

Why this matters: Traditional per-file CRDT designs would allow partial renames during concurrent edits — some files with old paths, some with new. The monolithic Y.Doc gives ACID semantics to vault operations that users intuitively expect to be atomic.

Example 2: Filesystem Bridge Event Processing

How YAOS converts noisy Obsidian file events into safe CRDT updates:

// Simplified filesystem bridge: dirty-set draining with echo suppression

class FilesystemBridge {
  private dirtySet: Set<string> = new Set();     // Files pending sync to CRDT
  private acknowledged: Set<string> = new Set(); // CRDT-originated changes (suppress echo)
  private drainTimer: number | null = null;

  onFileChange(path: string, content: string, source: 'disk' | 'crdt') {
    if (source === 'crdt') {
      // Change came from CRDT sync — mark as acknowledged to prevent echo
      this.acknowledged.add(path);
      return;
    }

    // Change from disk (Obsidian save, external edit, AI agent)
    if (this.acknowledged.has(path)) {
      // Recently acknowledged from CRDT — likely our own change echoing back
      this.acknowledged.delete(path);
      return; // Suppress: don't feed disk echo back into CRDT
    }

    // Genuine external change — queue for CRDT integration
    this.dirtySet.add(path);
    this.scheduleDrain();
  }

  private scheduleDrain() {
    if (this.drainTimer) return; // Coalesce rapid events
    
    this.drainTimer = window.setTimeout(() => {
      this.drainTimer = null;
      
      // Batch process all pending changes
      for (const path of this.dirtySet) {
        const content = readFileFromDisk(path);
        const ytext = this.getYTextForFile(path);
        
        // Compute minimal delta, apply to CRDT
        const current = ytext.toString();
        const diff = computeMinimalDiff(current, content);
        ytext.applyDelta(diff);
      }
      
      this.dirtySet.clear();
    }, 50); // 50ms coalescing window
  }
}

Critical insight: Without echo suppression, every CRDT update would trigger a file write, which would trigger a file watcher, which would trigger another CRDT update — infinite loop. The acknowledged set breaks this cycle by tracking provenance.

Example 3: Cloudflare Worker Durable Object Sync Room

The server-side sync room that maintains shared state across client disconnections:

// Durable Object: one per vault, survives hibernation and restarts

export class YaosSyncRoom {
  private state: DurableObjectState;
  private storage: DurableObjectStorage;
  private ydoc: Y.Doc;
  private connections: WebSocket[] = [];

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
    this.storage = state.storage;
    
    // Restore from checkpoint + journal on activation
    this.ydoc = new Y.Doc();
    this.loadPersistedState();
  }

  async fetch(request: Request) {
    const url = new URL(request.url);
    
    if (url.pathname === '/websocket') {
      // Upgrade to WebSocket for live sync
      const [client, server] = Object.values(new WebSocketPair());
      await this.handleConnection(server);
      return new Response(null, { status: 101, webSocket: client });
    }
    
    // ... HTTP endpoints for claim, snapshots, etc.
  }

  private async handleConnection(ws: WebSocket) {
    this.connections.push(ws);
    
    // Send current state vector for efficient sync
    const stateVector = Y.encodeStateAsUpdate(this.ydoc);
    ws.send(stateVector);
    
    ws.addEventListener('message', async (msg) => {
      // Apply client update to shared CRDT
      const update = new Uint8Array(msg.data);
      Y.applyUpdate(this.ydoc, update);
      
      // Broadcast to other connected clients (excluding sender)
      this.broadcast(update, ws);
      
      // Persist incrementally: journal the delta, periodic checkpoints
      await this.persistDelta(update);
    });
  }

  private async persistDelta(update: Uint8Array) {
    // Append to journal — NOT full state rewrite
    const journalKey = `journal/${Date.now()}`;
    await this.storage.put(journalKey, update);
    
    // Periodic checkpoint: merge journal, write compact state
    const journalSize = await this.journalSize();
    if (journalSize > CHECKPOINT_THRESHOLD) {
      await this.compactCheckpoint();
    }
  }

  // Survives hibernation: Durable Object state is preserved
  async alarm() {
    // Scheduled tasks: snapshot creation, cleanup, etc.
  }
}

Engineering depth: The checkpoint+journal system replaced early full-state rewrites. For a 50MB text vault, rewriting complete state every few seconds would be unsustainable. Delta journaling makes persistence O(changes) rather than O(vault size).

Advanced Usage & Best Practices

Optimize for Your Vault Size

YAOS's monolithic Y.Doc has practical limits — approximately 50MB of raw text is comfortable. If you're approaching this, consider: archiving old notes to separate vaults, using larger attachments (images/PDFs go to R2, not the CRDT), or excluding heavy paths via Exclude paths setting (templates/, .trash/, archive/).

Master the Command Palette

Power users should memorize these commands:

• Force reconcile: When disk and CRDT feel misaligned (rare, but possible after crashes)
• Clear local server-receipt state: Essential after server resets or migrations — Phase A receipt state cannot auto-detect every same-vault server reset
• Nuclear reset: The escape hatch. Wipes all CRDT state, re-seeds from disk. Use when all else fails.

Configure External Edit Handling

The Edits from other apps setting controls how YAOS handles git pulls, script modifications, or AI agent writes. For agentic workflows, set this to aggressive reconciliation — external disk changes should propagate immediately, not wait for the next sync cycle.

Snapshot Strategy

With R2 configured, YAOS creates daily automatic snapshots and supports on-demand point-in-time backups. Before major vault restructuring (folder reorganization, bulk imports), manually trigger Take snapshot now. The diff-and-selective-restore UI lets you recover individual files without full rollback.

Monitor with Debug Logging

Enable Debug logging when troubleshooting. The Show sync debug info command reveals connection state, file counts, queue status, and receipt timestamps. Safe diagnostics redact sensitive fields; filename-inclusive exports require explicit confirmation.

Comparison with Alternatives

The Verdict: YAOS uniquely combines real-time CRDT semantics, genuine zero-ops deployment, complete infrastructure ownership, and zero cost. Trade-offs exist — the 50MB text ceiling, no .obsidian plugin sync, empty folder limitations — but for personal knowledge management, these are pragmatic constraints, not dealbreakers.

FAQ

Is YAOS actually free forever?

Yes. The 0-BSD license imposes zero restrictions. Cloudflare Workers and R2 have generous free tiers; typical personal vault usage stays within them. You pay only if you exceed Cloudflare's free thresholds (unlikely for normal use).

Can I trust CRDTs with my important notes?

Yjs CRDTs are battle-tested in production at Figma, Notion, and numerous collaborative editors. The mathematical convergence guarantees are proven. However, YAOS is relatively young — the engineering notes explicitly document "warts and limits." For critical data, enable R2 snapshots.

What happens if my Cloudflare Worker goes down?

Your vault exists locally as normal Markdown files. Offline edits queue in IndexedDB and merge on reconnection. The Durable Object state persists across Worker restarts. Maximum offline window depends on IndexedDB storage limits — typically generous for text.

Does YAOS work on mobile?

Yes. The Obsidian plugin supports iOS and Android. QR-code setup is specifically designed for mobile pairing. If sync stalls, use the Reconnect to sync server command — mobile network transitions can drop WebSocket connections.

Can multiple people share a vault?

YAOS is optimized for personal or small-team use. The claim mechanism locks a Worker to one owner who controls access via token distribution. There's no built-in per-user permissions — share the token, share the vault. For larger teams, consider whether Obsidian's official collaboration features better fit.

Why no .obsidian folder sync?

Plugin settings and themes can conflict in destructive ways. YAOS intentionally excludes these to prevent configuration corruption. Sync plugins separately through git or manual management.

How do I migrate from Obsidian Sync?

Disable Obsidian Sync, ensure all devices have current vault state, deploy YAOS, connect one device, verify sync, then connect remaining devices. The "Nuclear reset" command can force alignment if migration causes state confusion.

Conclusion

YAOS isn't just another sync tool — it's a declaration of independence for knowledge workers. In an era where every productivity app demands recurring rent for access to your own data, YAOS hands you the keys: real-time collaboration semantics, infrastructure you control, and a price tag that can't be beaten.

The engineering is genuinely impressive. Monolithic CRDT transactions. Checkpoint+journal persistence. Zero-config auth with deep-link pairing. A filesystem bridge that makes AI agents first-class citizens. This isn't weekend hackathon code — it's thoughtful distributed systems design documented with unusual transparency in the engineering/ directory.

Is it perfect? No. The 50MB text ceiling, empty folder limitations, and young project maturity mean you should evaluate against your specific needs. But for the vast majority of Obsidian users — researchers, writers, developers, thinkers — YAOS eliminates the central pain of multi-device note-taking without introducing new ones.

Your move. Stop accepting conflicted copies. Stop paying subscription rents for basic sync. Stop choosing between complexity and control.

Deploy your own YAOS server today: github.com/kavinsood/yaos. Click the button, claim your Worker, scan the code. Five minutes to never thinking about sync again.

The future of personal knowledge management is local-first, edge-deployed, and conflict-free. YAOS is already there. The only question is whether you'll join it.