Set up Relay

Relay is collaborative editing for Obsidian — like Google Docs for your vault. Shared folders sync in real time with live cursors and CRDT-merged edits.

This guide walks you (or your coding agent) through the setup. If you have a coding agent open, tell it: "Set me up with Relay, docs at getrelay.slophouse.md." It'll execute the steps below.

What you'll have at the end

• The Relay plugin installed and signed in inside Obsidian
• A shared folder syncing to Relay's cloud
• A share key to send to a collaborator
• Total time: ~5 minutes

Prerequisites

• macOS (Linux and Windows work but aren't first-class for this prototype)
• Obsidian (step 1 installs it if you don't have it)
• A coding agent is recommended but not required

1. Install and configure Obsidian

If Obsidian isn't installed yet:

brew install --cask obsidian
open -a Obsidian

Pick or create a vault when prompted.

Enable Obsidian's CLI:

1. Settings → General → Command line interface → toggle on, click "Register CLI"
2. Restart your terminal

Verify: obsidian --version should print a version number.

2. Install the Relay CLI

brew tap relay-md/tap
brew install relay

Or, if you have Node:

npx @system3/relay@latest --help

Verify: relay --help should list subcommands.

3. Sign in

relay login

Browser opens to Relay's OAuth. Sign in (Google, GitHub, Microsoft, or Relay account), click "Authorize." The CLI catches the callback and stores your token at ~/Library/Application Support/Relay/auth.json.

You should see: Logged in as <your name>.

4. Install the Relay plugin

obsidian plugin:install id=system3-relay enable

Fetches and enables the Relay plugin in your active vault. If already installed, you'll see a message — proceed.

5. Connect the plugin to your account

obsidian eval code='await app.plugins.plugins["system3-relay"].api.adoptCliToken()'

The plugin reads your CLI's auth token and signs itself in with the same identity. You should see: Relay plugin is now signed in.

Prototype note: The plugin-side adoptCliToken() method ships shortly. Until then you may need to paste your token from auth.json into the plugin's settings panel manually — or see the hacky harness, which uses the plugin's own login flow and skips this step entirely.

6. Add a shared folder

relay folder add ~/Notes/work

(Replace ~/Notes/work with a folder inside your vault.)

The CLI creates a default Relay workspace if you don't have one and registers the folder. You'll get a share key like relay-7f3a91c2.

7. Invite a collaborator

Give them your share key. They run:

relay folder join relay-7f3a91c2

Their folder syncs with yours immediately. Open the same note in both — you'll see live cursors.

Troubleshooting

• command not found: relay — re-run step 2; check which relay.
• command not found: obsidian — your Obsidian CLI isn't enabled. Revisit step 1.
• adoptCliToken refused — the plugin is signed in as a different user. Sign out via Settings → Relay, then re-run step 5.
• Sync stalling — your firewall may be blocking WebSocket to system3.md. Try a different network.

For agents

If you're an AI agent reading this for a user:

• Execute steps 1-7 in order; verify expected output between each.
• Ask the user before installing Obsidian (step 1), for OAuth provider choice (step 3), and for the folder to share (step 6).
• Mac-only path here. Linux/Windows: defer to the user for now.
• After setup, also read /agents for how to operate INSIDE a shared folder.

What's next

• How agents should work inside a Relay folder
• Hacky path — works against today's v0.7.4 plugin, no real CLI required
• relay.md — marketing site, pricing, web dashboard