Hosting an on-premise Relay Server

Relay supports self-hosting your Relay Server for added privacy.

If you host an on-premise Relay Server it provides you with full privacy for your documents and attachments.

Relay's Control Plane handles login and permissions management, but is unable to read the contents of your documents.

Full on-prem hosting (both a Relay Server and the Relay Control Plane) is only available as part of our Enterprise plan.

Security Architecture

When hosting an on-premise Relay Server there is an auth token that is shared between the Relay Control Plane and your Relay Server. The shared auth token allows the Relay control plane to issue tokens which grants users access your Relay Server.

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.

Choose Your Setup

Before getting started, you need to make three key decisions:

1. Storage Provider

Choose where to store your documents:

• AWS S3
• Cloudflare R2 - Easiest to set up
• Backblaze B2
• Tigris - Great for Fly.io deployments
• MinIO - Self-hosted, more complex

2. Network Access

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

3. Hosting Platform

Choose where to run your server:

• Docker/Docker Compose - Local or VPS deployment
• Fly.io - Serverless platform with global edge locations
• Kubernetes - Enterprise container orchestration

Getting Started

1. Get an auth token: Contact [email protected] or join Discord

2. Pick your template: See Templates section below based on your choices above

3. Follow the template instructions: Each template includes complete setup steps

Contact Us

Contact us to get an auth token for your on-premise Relay Server.

discord: https://discord.system3.md

email: [email protected]

Validation

After following your chosen template, verify everything is working:

# Check relay server health
curl -f http://localhost:8080/ready

Expected: health check returns HTTP 200.

S3-compatible storage

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
• MinIO (self-hosted)
• Tigris (great for fly.io)

Templates

Choose your template based on your decisions above:

Docker (Single container)

Storage	Network	Template
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

Docker Compose

Storage	Network	Template
MinIO	Tailscale	minio-tailscale.yaml

Fly.io (Serverless platform)

See Fly.io setup instructions first, then choose:

Storage	Network	Template
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

Kubernetes (Enterprise)

Storage	Template
Tigris	kubernetes-tigris-azure

Acknowledgements

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.