Relay supports self-hosting a Relay Server within your private network/VPN for document/attachment privacy.
Relay's Control Plane handles login and permissions management, but is unable to read the contents of your documents.
Start the Relay Server container:
# mounts local volume, see production deployment guide for S3-compatible storage
docker run \
-v data:/app/data \
-p 8080:8080 \
docker.system3.md/relay-server \
http://relay-server.my-network.internal:8080 # Your internal network URL
Register your server using the Relay Obsidian plugin:
- Log in
- Run the command
Relay: Register self-hosted Relay Server - Enter the relay-server URL (must match above)
Keep your server accessible from within your VPN only. If you expose your server to the public internet it is technically possible for us to access your documents.
Read the rest of this guide to understand how to set up a Relay Server in production.
Self-hosted Relay Servers rely on public key cryptography to trust tokens that are issued by the Relay Control Plane.
It is technically possible for the Relay control plane to issue an access token and then use it to connect to your Relay Server if it is hosted on the public internet.
To ensure that your documents are fully private, you need to host your Relay Server on a private network such as a tailscale tailnet or a corporate VPN.
If you don't already have a private network set up, we recommend using tailscale.
If you host your Relay Server on the public internet, we reserve the right to drop it from our network.
Before getting started, you need to make three key decisions:
Choose where to store your data:
Local Disk (not recommended for production)
S3-Compatible storage providers:
- AWS S3
- Cloudflare R2 - Easiest to set up
- Backblaze B2
- Tigris - Great for Fly.io deployments
Choose how users will access your server:
- Tailscale - ✅ Recommended: Private VPN, easy setup, secure
- Custom VPN - Use your existing corporate VPN
- Public Internet -
⚠️ Not recommended: Less secure, not private to us
Choose where to run your server:
- Docker/Docker Compose - Local or VPS deployment
- Fly.io - Cloud provider with a great developer experience
- Kubernetes - Enterprise container orchestration
-
Pick your deployment guide: See Deployment Guides section below based on your choices above
-
Follow the deployment guide instructions: Each deployment guide includes complete setup steps
-
Register your Relay Server: Open Obsidian and run the command
Relay: Register self-hosted relay server
Join our community on discord: https://discord.system3.md
Or email: daniel@relay.md
Relay Server is built to store data to S3-compatible storage. You will find examples in this repo that use:
- AWS S3
- Cloudflare R2
- Backblaze B2
- Tigris (great for fly.io)
Choose your deployment guide based on your decisions above:
| Storage | Network | Deployment Guide |
|---|---|---|
| AWS S3 | Tailscale | docker-s3-tailscale.md |
| AWS S3 | Tailscale (HTTPS) | docker-s3-tailscale-serve.md |
| AWS S3 | Custom VPN | docker-s3-custom.md |
| Cloudflare R2 | Tailscale | docker-r2-tailscale.md |
| Cloudflare R2 | Tailscale (HTTPS) | docker-r2-tailscale-serve.md |
| Cloudflare R2 | Custom VPN | docker-r2-custom.md |
See Fly.io setup instructions first, then choose:
| Storage | Network | Deployment Guide |
|---|---|---|
| AWS S3 | Tailscale | fly-s3-tailscale.md |
| AWS S3 | Tailscale (HTTPS) | fly-s3-tailscale-serve.md |
| AWS S3 | Custom VPN | fly-s3-custom.md |
| Cloudflare R2 | Tailscale | fly-r2-tailscale.md |
| Cloudflare R2 | Tailscale (HTTPS) | fly-r2-tailscale-serve.md |
| Cloudflare R2 | Custom VPN | fly-r2-custom.md |
| Storage | Deployment Guide |
|---|---|
| Tigris | kubernetes-tigris-azure |
The Relay Collaboration Server is a fork of y-sweet by the talented folks at jamsocket.com
y-sweet builds on y-crdt by Bartosz Sypytkowski, Kevin Jahns, and the y-crdt community.
The server source code is MIT licenced and available here.
