Relay adds real-time collaboration to Obsidian with Yjs and a relay server

Three steps and a relay

Relay calls itself true multiplayer mode for Obsidian, and the product description lists three things: collaborate in real time with live cursors, edit offline and sync cleanly when you are back on, and share folders and manage access to updates.

The mechanism is described in three steps. The plugin tracks updates to designated folders, using conflict-free replicated data types to track updates to folders that you designate within your vault. It then relays those updates, sending them up to Relay servers which echo the updates out to all collaborators on the relay. And it integrates the updates, so your collaborator receives them and integrates them as they come in.

That word relay is the key to the whole design. It is not a peer-to-peer system and it is not a document server that holds the authoritative copy. The server is a message bus. Your copy of the vault is the copy you keep, and the server's job is to carry changes between people.

The consequence is the local-first property, which the FAQ states directly. Relay is local-first, which means that all of your edits are tracked locally and the server is used to relay the edits to your collaborators. You can work offline and your edits will be merged once you come back online.

That is a genuinely different behaviour from a shared file on a network drive, and it is the reason the plugin can claim to work offline and sync cleanly. The server never holds the only copy of anything, so there is no single point where an edit can be lost by the server being unreachable.

The plugin is by System 3, with a homepage at relay.md and a Discord for support. The repository is MIT licensed, the default branch is main, and the last push was on 2026-10-20. The releases are 0.8.12 from 2026-09-09, with 0.8.11 and 0.8.10 marked as beta.

The naming convention of the company is worth noting as a piece of context. Relay is made by System 3, and the legal entity behind System 3 is No Instructions, LLC, which is also the GitHub organisation the repository lives under.

What a CRDT buys you

The documentation has a section explaining CRDTs, and its quality is a good sign about the project.

CRDT stands for conflict-free replicated data type, and the explanation given is that you have data, this data is stored on multiple replicas, and CRDTs describe how to coordinate these replicas to always arrive at a consistent state.

That is the correct definition and it is stated without jargon. The idea is that instead of detecting conflicts after the fact and asking a human to resolve them, the data structure is designed so that the merges are always well defined and always produce the same result on every replica, no matter what order the updates arrive in.

The practical effect is stated in the feature list. If you're in a note at the same time, you'll see each others' cursors. You can edit the same block at the same time, which the documentation calls the magic of CRDTs. And you can edit offline and it'll all be fine when you come back on.

That last one is the hardest case and the one worth understanding. With a conventional last-writer-wins model, an offline edit that you made on a train and an edit your colleague made at their desk are both trying to write the same block, and the resolution is one or the other. With a CRDT, the merge is a property of the data structure, so both edits survive, and every replica ends up with the same result regardless of who was offline for how long.

The implementation choice is named: conflict-free replicable data types provided by the excellent yjs library, and Yjs is pinned at 13.6.33 in the dependencies. Yjs is the open source CRDT that Relay uses.

The documentation points at two videos for people who want to understand it properly. Martin Kleppmann's video is recommended with the note that for a great intro and overview you should watch the first 10 minutes, and if you want to get into the nitty-gritty, watch the whole thing. And there is a video by Kevin Jahns called Intro to the Modern State of Synchronization, with the note that Jahns is the maintainer of Yjs.

That the project points at the upstream maintainer's own explanation of the technology it depends on is a good sign. It means the documentation is not trying to make the CRDT look simpler than it is.

Creating a relay and sharing it

The user-facing flow is short, and it is documented with animated demonstrations for each step rather than with prose alone.

Creating a relay is four steps. Go to Obsidian settings using the gear icon in the lower left. Go to Relay settings on the left, at the bottom. Create new relay. Add shared folder(s) to the relay.

Adding users is three steps. Go to settings for your relay, grab the share key, and give it to your people. Joining someone else's relay is the same key in the other direction: get their share key, use it to join their relay, and add the folders you want to your vault.

So the unit of sharing is a folder, and the unit of permission is a key. That is a simple model and it matches the way people actually share notes, which is usually a folder of related notes rather than an individual file.

The documentation is also honest about the weakness of that model. Right now anyone with the share key can join the relay. So you can kick the user but they could rejoin if they want. And stricter sharing options will be added in the future.

That is a real limitation and it is stated rather than glossed over. A share key that can be revoked only by removing the user, and which that user can immediately use again, is a convenience mechanism rather than an access control mechanism. For a shared notebook between colleagues it is fine; for anything with a compliance requirement it is not, and the pricing table shows where the access control lands.

There is also a destroy flow. If you are the owner of a relay, you can destroy the copy on the server. If you are a member but not the owner, you can leave the relay, which destroys your connection to the server, and you can destroy the local data.

The separation of the two is deliberate and sensible. The owner controls the server-side copy, and a member controls their own local copy, so a member who wants out can take their data with them rather than being locked in.

Two storage models, and the one that costs money

The FAQ on file types is where the pricing makes sense, so it is worth reading before the pricing table.

Relay currently has two types of storage, document storage and attachment storage. Document storage is backed by the real-time CRDT servers, while attachments are stored as file blobs.

Document storage covers folders, Markdown files and canvases. Attachment storage covers bases, images, audio, video, PDFs and other files, which must be enabled in settings.

And the important line: you need to have available attachment storage in order to sync bases, images, audio, video, PDFs and so on.

So the free tier syncs your text and your canvases, and the paid tiers add the ability to sync everything else. The reason is architectural rather than a pricing decision about storage alone. Documents go through the CRDT servers, which is what makes the collaborative editing and the offline merging work. Attachments are opaque blobs, and syncing them means uploading and downloading files, which is bandwidth and disk.

That distinction also tells you what Relay is good at and what it is not. It is a collaborative editing tool for structured text, and it is not a general file sync. If your vault is mostly notes and a few images, the free tier covers the collaborative part entirely.

The pricing table is unusually clear about what is included, and it is worth reading the whole thing because the tiers are shaped by who is sharing.

The free tier is up to three users, two devices per user, unlimited Markdown and canvas files, no cloud storage at zero megabytes, cloud deployment with markdown only, a self-hosted relay server, bring-your-own storage which is unmetered and self-host only, and community support.

Hobby is five dollars per month in total and buys up to six users, three devices per user, ten gigabytes of cloud storage, the self-hosted server, and community support.

Starter is six dollars per user per month and scales that to fifty users, six devices per user, twenty gigabytes plus five per user, role-based access control, single sign-on, a private Discord or Slack channel and email support.

Two things are notable. The Hobby tier is priced per month in total rather than per user, so it is aimed at a small fixed group. And self-hosting is available on every tier, including the free one, which the documentation underlines: you can self-host your Relay Server on any tier, because we don't charge for privacy. There are also discounts for educational use.

Self-hosting, and the part that is not open source

The self-hosting section and the open source section have to be read together, because the boundary between them is the thing to understand before deploying.

The plugin is MIT licensed, which is this repository. The Relay Server is a fork of y-sweet and is MIT licensed, and it lives in a separate repository. Our login, permissions and billing server code is proprietary.

So two of the three pieces are open, and the third is the control plane: the thing that knows who you are and what you are allowed to do.

What that means in practice is spelled out. If you self-host your Relay Server on a private network then your users will still perform login and permissions checks through our control plane, but they will connect directly to your server. Your content will be completely private and inaccessible by us.

That is a specific and useful guarantee. The content does not touch the vendor at all. What does touch the vendor is the authentication and the authorisation decision, which means the plugin still needs to reach the control plane to join a relay even when the relay server is on your own network.

Whether that arrangement satisfies you depends on what you are defending against. If the concern is that a third party reads your notes, the guarantee is absolute. If the concern is that a third party knows who you collaborate with and when, that metadata still goes to the control plane, and self-hosting does not change it.

For instructions on hosting the Relay Server on fly.io there is a Relay Server Template repository, and the Discord is the place to get help configuring a self-hosted server.

Behind all of it is a very small team. Relay is made by System 3, the legal entity is No Instructions, LLC, and the whole operation is two people. Dan is a software engineer who has worked at places like Planet and Benchling. Matt is a product manager and psychotherapist in training. The split between an engineer and somebody whose background is in product and therapy is worth noticing, because it explains a design decision that would otherwise look odd, which is the share key rather than a permission system.

The repository, and what the dependencies say

The repository layout is distinctive and tells you a few things about how the project is built.

There is src/ for the source, __tests__/ for the tests, and a manifest.json and styles.css for the Obsidian plugin format. There is a relay-plugin-api.d.ts, which is the type definition for the API surface the plugin exposes to other Obsidian plugins, which is a deliberate move rather than a private implementation.

Then there is the build machinery. There is esbuild.config.mjs, a run.mjs script, and separate build.d/ and lint.d/ directories, which look like the output directories for the two tasks. The package scripts use them: the dev script runs esbuild in watch mode, the build script runs node run.mjs build, the lint script runs node run.mjs lint and the deploy script runs node run.mjs deploy.

The run.mjs pattern is worth noting. Wrapping several tasks behind one script means there is a single entry point that knows about the project, and the individual commands are the same whether a developer runs them or the deployment does. The release and beta scripts show the pattern clearly, and they both run the type check first before the build:

The release script runs tsc with noEmit and skipLibCheck and then esbuild in production mode, and the beta script does the same with the debug mode. A separate staging script runs esbuild in staging mode with watch.

The version script runs a version-bump script and then stages manifest.json and versions.json in git, which is a nice touch: the Obsidian manifest and the plugin's own version list are kept in step by a script rather than by hand, and the git add is part of the script so the commit is already prepared.

The dependencies tell you the stack. Yjs at 13.6.33 with y-protocols and lib0, which is the standard Yjs stack, plus diff-match-patch and node-diff3 for diffing, which is what you need to turn a Yjs update into a patch you can show a user. The jose library handles the JSON Web Token work that authentication implies, and @noble/hashes is a cryptography primitive library.

Pocketbase at 0.20.3 stands out, because it is a backend that gives you a database, authentication and file storage from one binary. That is almost certainly what the proprietary control plane is built on, and it explains how a two-person operation can ship login, permissions and billing.

The UI is Svelte 5, with svelte-preprocess, the svelte eslint parser and lucide-svelte for the icons, and the CodeMirror packages for the editor, which is the editor Obsidian itself uses. There is also a diff type package, monkey-around for test doubles, and yaml for configuration.

The Obsidian API package is at 1.13.1, and the TypeScript types for Obsidian are included in the dev dependencies, so the plugin is typed against the real API rather than against hand-written stubs.

Editorial conclusion

Adopt Relay if you share an Obsidian vault with other people and want simultaneous editing rather than file sync, since the CRDT layer is what makes concurrent edits and offline work merge correctly. Skip it if you only need one-way sync of notes between devices, since that is a simpler problem, and if your requirement is strict access control, since the current sharing model is a share key that anyone holding can reuse. Verify first which storage model you need, because attachments require the paid tier while document sync is free, and that you are comfortable with the login and permission checks running through the vendor's control plane even on a self-hosted server.

Frequently asked questions

Official sources

1. License: MIT
2. No-Instructions/Relay on GitHub
3. Project website
4. README
5. Releases