YAOS: Yjs CRDT sync for Obsidian on a Cloudflare Worker you deploy yourself
A zero-terminal, real-time sync engine powered by your own Cloudflare Worker.
At a glance
- What is it?
- YAOS pairs an Obsidian plugin with a Cloudflare Worker to sync a vault as live Markdown CRDT state. The setup skips the terminal entirely, but attachment sync, snapshots and an R2 binding sit outside the default path.
- Who is it for?
- Adopt YAOS if you already run things on Cloudflare, want CRDT merges rather than conflicted copies, and can live without attachment sync until you add an R2 binding named YAOS_BUCKET. Skip it if you need a managed service with a support contract, if your vault is mostly PDFs and images you cannot move to R2, or if you expect empty folders to survive a round trip.
- Can I use it commercially?
- Yes. 0BSD is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The conflicted-copy problem YAOS is aimed at
File-level sync tools treat a note as a blob. When two devices write the same file before either has seen the other's version, the tool has no way to merge the contents, so it keeps both and appends a suffix. The README puts iCloud and Dropbox in that column, and it is the failure mode most Obsidian users recognise: a folder slowly filling with duplicates you have to reconcile by hand. YAOS takes the other route. It keeps one live vault state built from Yjs CRDTs and moves that state between devices, so concurrent edits to the same note merge at the character level instead of producing two files. The README describes this as keeping one live vault state moving across devices rather than letting them take polite turns uploading files. That is the whole pitch, and it is a narrower one than general file sync: the target user is a single person or a small group editing Markdown notes across a desktop and a phone, who wants the merge behaviour without standing up a database or paying a yearly subscription.
Worker, plugin and the claim step that binds them
The architecture has two halves. The server side is a Cloudflare Worker deployed into your own account, and the client side is an Obsidian plugin installed from the Marketplace. The Worker is not a hosted service you sign into. It is an instance you own, which is why the README can claim no database setup is required: the Worker is the coordination point, and Cloudflare provides the runtime. The interesting mechanism is the claim step. After deployment you open the Worker URL and click Claim, which locks that Worker to you and generates a setup token. The plugin then receives connection details either through a setup link or a QR code shown on the claim page. That design removes the usual copy-paste of URLs and keys, and it also means the Worker is effectively single-tenant after claiming. The README does not describe what happens to an unclaimed Worker that someone else finds first, so treat the claim step as the security boundary and do it immediately after deploying. Attachments are handled separately through an R2 bucket, which the README says enables image and PDF sync as well as daily automatic snapshots and on-demand point-in-time backups, with the ability to browse snapshots, diff against current state, and restore individual files.
Getting it running without a terminal
The README lists four steps. Click the Deploy to Cloudflare button, which creates a Worker in your account. Open the Worker URL and click Claim to generate the setup token. Install YAOS from the Obsidian Marketplace. Then open the setup link or scan the QR code from the claim page, and the plugin fills in the connection details itself. There is no .env file and no database provisioning in that path. R2 is the optional second stage and the README frames it as a roughly one-minute addition, with a separate setup video. The one configuration key named in the material is YAOS_BUCKET, the binding the server expects for R2. If it is missing, the plugin reports R2 not configured. The troubleshooting section also points at docs/operations.md for a wrangler.toml R2-binding fallback when the Cloudflare dashboard or build queue misbehaves, which is a useful admission that the dashboard path is not always smooth. Two other named surfaces are worth knowing before you file a bug: a Show sync debug info command for local inspection, and a safe diagnostics export that redacts server URL, vault ID, device name and vault paths. Use the redacting export if you are pasting anything into a public issue.
Where the design gives up ground
The README is unusually direct about the boundaries, and they are worth taking at face value. Durability receipts are listed as an explicit limit, meaning there is no per-write confirmation that a change reached durable storage. Attachments are not in the default path: without R2, text sync works and nothing else does. Empty folders are called out as a limit, so a vault organised around placeholder directories will not round-trip faithfully. Non-Markdown plugin files are also excluded, which matters if you rely on snippets, themes or plugin data that live outside plain notes. There is also a size ceiling: the troubleshooting notes say files over max size are skipped, and that exclude patterns can silently keep files out of sync. Both are quiet failures rather than errors, which is the worst kind. The mobile note is a smaller annoyance: the README tells you to run Reconnect to sync server when syncing stops, which implies reconnects are a normal event rather than an exception. None of this makes YAOS broken. It makes it a text-first tool with a documented edge, and you should decide whether your vault lives inside that edge before you move it.
Obsidian Sync and LiveSync as the real comparisons
The README's own table puts Obsidian Sync at 96 dollars a year with delayed rather than real-time propagation, and Git or LiveSync in the self-hosted column with manual conflict handling and no no-terminal path. The difference with Obsidian Sync is operational, not technical: you get a managed service and someone to contact when it breaks, and you give up running the endpoint yourself. The difference with LiveSync is the opposite trade. LiveSync keeps your existing server and your existing terminal habits, while YAOS asks you to deploy a Worker and then never open a shell again. If you already have a VPS and a working LiveSync setup, YAOS is a lateral move at best. If you have no server and no interest in acquiring one, the Cloudflare deploy button is the shortest path in this comparison set. The README also mentions Relay and Screengarden as freemium real-time options with no CRDT merge, which is the distinction that matters most: those give you speed, YAOS gives you merge semantics.
Agents, scripts and files written behind the plugin's back
One section of the README is worth separating from the marketing around it. Because an Obsidian vault is a directory of Markdown files, anything that writes to disk is writing into the vault: git, shell scripts, an editor, or an agent. YAOS claims the CRDT state stays aligned with the filesystem, so changes from those sources propagate across devices instead of falling back to conflicted copies. That is a real architectural claim and it follows from the CRDT choice, but it is also the claim most likely to be tested by unusual write patterns, such as an agent rewriting a file wholesale while you are typing in it. The README does not describe how external writes are detected or how often the filesystem is reconciled against CRDT state. If your workflow depends on programmatic edits, that is the first thing to probe on a throwaway vault rather than the thing to assume.
Licence, upgrade cost and what you actually maintain
YAOS is 0BSD, which is about as permissive as a licence gets: it permits use, modification and redistribution with no attribution requirement. That removes the licensing question almost entirely, and it also means there is no commercial entity with an obligation to keep the project alive. The maintenance you take on is operational. Your Worker runs in your Cloudflare account, so Cloudflare's free tier and its limits are your limits, and the README's claim of zero cost depends on staying inside them. Upgrades arrive as plugin updates through Obsidian and as Worker redeployments, and the release history in the repository shows a 2.0.0 followed by 2.1.0 and 2.1.1 within weeks, which suggests active iteration rather than a frozen codebase. Fast iteration on a sync engine is not automatically good news for someone with a large vault. Read the release notes before upgrading, and keep the R2 snapshot feature in mind: the README presents snapshots as the recovery mechanism, which is a reason to configure R2 even if you never sync an image. This is a description of the licence terms, not legal advice.
Editorial conclusion
Adopt YAOS if you already run things on Cloudflare, want CRDT merges rather than conflicted copies, and can live without attachment sync until you add an R2 binding named YAOS_BUCKET. Skip it if you need a managed service with a support contract, if your vault is mostly PDFs and images you cannot move to R2, or if you expect empty folders to survive a round trip. Before trusting it with a real vault, verify three things on your own account: that the claim page locked the Worker to you, that the plugin token matches the server token exactly, and that the R2 binding is visible in the Worker configuration rather than only in wrangler.toml.
Community notes