kavinsood/yaos: Real-Time Obsidian Sync on Your Own Cloudflare Worker

The conflicted-copy problem YAOS targets

File-sync tools treat a note as a file that gets uploaded and downloaded. When two devices edit the same note before either upload lands, the tool cannot merge the text, so it keeps both versions and hands you a conflicted copy to reconcile by hand. That workflow is fine for a folder of PDFs and miserable for a vault you edit on a phone during a commute and on a laptop at a desk.

YAOS is aimed at Obsidian users who want the opposite default: one live vault state that moves between devices, with Yjs CRDTs doing the merge instead of the filesystem. The README frames the choice as "live Markdown CRDT sync on infrastructure you deploy in your Cloudflare account." The audience is narrow on purpose. It is for people who already keep notes as local Markdown files, run Obsidian on more than one device, and are willing to own a small server rather than pay a subscription. The comparison table in the README puts iCloud and Dropbox on conflicted copies, Obsidian Sync on delayed real-time at $96/yr, and Git or LiveSync on manual conflict handling with a terminal in the loop. YAOS claims the CRDT column and $0, at the cost of self-deployment.

Two pieces: an Obsidian plugin and a Worker you own

The architecture is deliberately small. There is an Obsidian plugin, distributed through the Obsidian Marketplace, and there is a Cloudflare Worker that the user deploys into their own account from the `server/` directory. The repository layout matches that split: `src/` for the plugin, `server/` for the Worker, `docs/` for operations notes, and `qa/` plus `tests/` for the project's own harnesses.

The plugin holds the vault side. It watches local Markdown files, feeds changes into a Yjs document, and exchanges updates with the Worker over a live connection. Because the merge happens at the CRDT layer, two devices editing the same note produce a merged document rather than two files. The README also notes that the CRDT state stays aligned with the filesystem, which is why edits from git, shell scripts, or agents writing directly to disk propagate across devices instead of falling back to conflicted copies. That is the part worth taking seriously if you generate notes programmatically.

The Worker is the relay and the persistence point. It runs in the user's Cloudflare account, and the README says no database setup is required. Attachments are the exception: images, PDFs, and other binaries need an R2 bucket, and R2 is also what enables daily automatic snapshots and on-demand point-in-time backups, including browsing snapshots, diffing against current state, and restoring individual files. Without R2, the README is explicit that text sync still works and you simply lose attachment sync and snapshots. That is a clean split, and it is also the first place a new user gets surprised.

Deploying the Worker and connecting a vault

The README describes a four-step path with no terminal involved. First, the Deploy to Cloudflare button creates a Worker in your account from `https://github.com/kavinsood/yaos/tree/main/server`. Second, you open the Worker URL and click Claim to lock the server to you and generate a setup token. Third, you install the YAOS plugin from the Obsidian Marketplace. Fourth, you open the setup link or scan the QR code from the claim page, and the plugin fills in the connection details.

If you prefer to work from the repository instead of the button, the package manifest exposes the usual build and test entry points:

npm run build
npm run test:ci

The first command typechecks and produces the plugin bundle through `esbuild.config.mjs`; the second runs the regression guard chain and the live Worker integration suite. Neither is required for normal use, since the Marketplace plugin and the Deploy button cover the documented path. They matter if you plan to modify the plugin.

For attachments and snapshots, the README points to a separate R2 setup video and says the bucket takes about a minute to add. The troubleshooting section names the failure you will see if you skip it: a "R2 not configured" message means the server has no `YAOS_BUCKET` binding yet. If the Cloudflare dashboard misbehaves during the deploy, `docs/operations.md` is the place the README sends you, including a `wrangler.toml` R2-binding fallback.

Where YAOS stops: attachments, snapshots, and durability receipts

The README's own comparison table lists explicit limits around durability receipts, attachments, empty folders, and non-Markdown plugin files. Read that sentence twice before moving a real vault onto it. Text sync is the supported core. Attachments require R2. Empty folders and non-Markdown plugin files are outside what the project claims to handle, which matters if your vault depends on folder structure or on plugin data stored in JSON.

Durability is the softer edge. Snapshots exist, but only with R2, and the README does not document rollback behaviour for the text-only configuration. If you run without R2, you have live sync and no point-in-time recovery story from the project itself; you are relying on whatever your filesystem or your own backups provide. That is a real trade-off, not a footnote.

Mobile is the other place to set expectations. The troubleshooting section includes "Sync stops on mobile" with the remedy of running the Reconnect to sync server command and checking network connectivity. A live connection that can drop on a phone is inherent to the design, and the project's answer is a manual reconnect rather than silent retry logic you can inspect. Files that fail to sync are attributed to exclude patterns or a maximum size limit, and the README's advice is to turn on debug logging, inspect, and then raise an issue on GitHub. Diagnostics are available through Show sync debug info, and safe diagnostics exports redact the server URL, vault ID, device name, and vault paths.

How YAOS differs from Obsidian Sync and LiveSync

Obsidian Sync is the managed option. It is paid, it is run by the Obsidian team, and the README's table marks it as rare conflicts with delayed real-time. If you want someone else to hold the operational burden and you are happy with the price, the README says plainly to pay for it and support the team. The difference is ownership: with Obsidian Sync you are a customer of a service, and with YAOS you are the operator of a Worker in your own Cloudflare account.

Git-based setups and LiveSync sit at the other end. They are self-hosted or self-deployed, free, and the README classifies their conflict handling as manual, with the terminal involved. Git gives you history and review, which YAOS does not attempt to replicate; YAOS gives you a live merged document, which Git does not. If your workflow already depends on commits, branches, and pull requests over notes, YAOS is the wrong layer to add.

The freemium hosted options in the table, Relay and Screengarden, are marked as real-time with no conflicts and no terminal, but they are someone else's infrastructure. YAOS keeps the no-terminal setup while moving the server into your account. That is the actual distinction: not the merge algorithm alone, but who holds the deployment.

Licence, releases, and what maintenance looks like

YAOS is released under 0BSD, a permissive licence that imposes no attribution requirement. For a self-deployed tool this is about as unencumbered as it gets: you can fork the Worker, modify the plugin, and run it without a copyleft obligation. The repository does not include a separate commercial or hosted-service licence, and the README directs anyone who wants a managed experience to Obsidian Sync instead. Nothing here is legal advice; read the LICENSE file if the terms matter to your situation.

The release history is short and recent. Version 2.1.1 was published on 2026-08-27, 2.1.0 on 2026-08-18, and 2.0.0 earlier the same day. The last push to the default branch was on 2026-09-08, and the repository is not archived. The version bump script is wired into npm as `version`, which runs `node version-bump.mjs` and stages `manifest.json` and `versions.json`, so plugin releases follow the standard Obsidian versioning convention.

Upgrade cost is mostly on the plugin side, since the Marketplace handles distribution. The Worker is yours, which means a server-side change is a change you apply, and the README's operations notes exist precisely because Cloudflare dashboard behaviour can be unreliable during deploys. If you fork the plugin, budget for the build chain: `npm run build` typechecks with `tsc -noEmit -skipLibCheck` before esbuild runs, and the regression suite includes guards for source artifacts, QA isolation, and schema version.

Editorial conclusion

Adopt YAOS if you already run Obsidian across two or more devices, want CRDT merge semantics instead of conflicted copies, and are comfortable owning a Worker in your Cloudflare account. Skip it if your vault leans on attachments and you have no intention of adding an R2 bucket, or if you want a vendor to hold the durability story. Before connecting a real vault, verify that the plugin token matches the claim page exactly, that your exclude patterns cover what you do not want synced, and whether R2 is configured, since the server reports "R2 not configured" when the YAOS_BUCKET binding is missing.

Frequently asked questions

Official sources

1. kavinsood/yaos on GitHub
2. License: 0BSD
3. Project website
4. README
5. Releases