Use your own domain

Every Family Chat server comes with a free address like happy-otter.safechat.family. If you own a domain, you can use it instead — everyone’s chat address becomes something like @mum:example.com.

This guide covers the one-time setup for your domain. If your family already chats on a safechat.family address and you want to switch, read Move to your own domain first — it explains what a move involves — then come back here for the domain setup itself.

How it works

Your chat server keeps running with us — your domain never needs to host the chat itself. It only needs to answer two small web addresses (called well-known files) that tell chat apps and other Matrix servers where your real server lives. Serving these files is also how we confirm the domain is really yours.

You can use your main domain (example.com) or a subdomain (chat.example.com). Whatever you pick becomes part of everyone’s chat address, so shorter is usually nicer.

What you’ll need

1. A domain you own, registered with any provider.
2. Your server address — shown on the Domain page in the control panel (it looks like happy-otter.safechat.family). The examples below call it YOUR-SERVER-ADDRESS.
3. Somewhere to serve two HTTPS files on your domain — the options below cover every setup, including “my domain doesn’t have a website at all”.

The two files

Your domain must return these responses (replace YOUR-SERVER-ADDRESS with the address from the control panel — the Domain page shows them ready to copy):

https://example.com/.well-known/matrix/server

{"m.server": "YOUR-SERVER-ADDRESS:443"}

https://example.com/.well-known/matrix/client

{"m.homeserver": {"base_url": "https://YOUR-SERVER-ADDRESS"}}

Two details matter:

• The :443 after your server address is required.
• The client file must be sent with the HTTP header Access-Control-Allow-Origin: *, or the Element web app can’t read it (phone and desktop apps don’t mind).

Option 1: Cloudflare (recommended)

We recommend Cloudflare because its free plan can serve both files without you needing any web hosting, and it works even if your domain has no website. If your domain isn’t on Cloudflare yet, you can add it for free — or use one of the other options below with your current provider.

A small Cloudflare Worker answers both addresses:

1. In the Cloudflare dashboard, open Workers & Pages and create a new Worker (any name, e.g. matrix-wellknown).

2. Replace its code with the following, filling in your server address:

   const SERVER_ADDRESS = "YOUR-SERVER-ADDRESS"; // e.g. happy-otter.safechat.family
   
   export default {
     async fetch(request) {
       const url = new URL(request.url);
       const headers = {
         "content-type": "application/json",
         "access-control-allow-origin": "*",
       };
       if (url.pathname === "/.well-known/matrix/server") {
         return new Response(
           JSON.stringify({ "m.server": `${SERVER_ADDRESS}:443` }),
           { headers }
         );
       }
       if (url.pathname === "/.well-known/matrix/client") {
         return new Response(
           JSON.stringify({ "m.homeserver": { base_url: `https://${SERVER_ADDRESS}` } }),
           { headers }
         );
       }
       return new Response("Not found", { status: 404 });
     },
   };
   

3. Deploy the Worker, then add a route so it only handles the well-known addresses: on your domain, go to Workers Routes and add the route example.com/.well-known/matrix/* pointing at your Worker (use www or your subdomain instead if that’s where your chat addresses live).

4. Make sure DNS for the domain name itself exists and is proxied (an A, AAAA or CNAME record with the orange cloud on). If the domain has no website, a placeholder AAAA record of 100:: works fine — the Worker still answers.

Option 2: your domain already has a website

If your domain serves a website, upload the two files to it:

1. Create a folder called .well-known/matrix/ at the root of the site.

2. Add a file named server (no extension) containing the server JSON above.

3. Add a file named client (no extension) containing the client JSON above.

4. Make sure both are served as JSON with the CORS header. For nginx, the cleanest way is two small location blocks:

   location = /.well-known/matrix/server {
       default_type application/json;
       add_header Access-Control-Allow-Origin *;
       return 200 '{"m.server": "YOUR-SERVER-ADDRESS:443"}';
   }
   
   location = /.well-known/matrix/client {
       default_type application/json;
       add_header Access-Control-Allow-Origin *;
       return 200 '{"m.homeserver": {"base_url": "https://YOUR-SERVER-ADDRESS"}}';
   }
   

   For Caddy:

   handle /.well-known/matrix/server {
       header Content-Type application/json
       header Access-Control-Allow-Origin *
       respond `{"m.server": "YOUR-SERVER-ADDRESS:443"}`
   }
   
   handle /.well-known/matrix/client {
       header Content-Type application/json
       header Access-Control-Allow-Origin *
       respond `{"m.homeserver": {"base_url": "https://YOUR-SERVER-ADDRESS"}}`
   }
   

   For Apache (in the site config or .htaccess):

   <Files "server">
       Header set Content-Type application/json
       Header set Access-Control-Allow-Origin *
   </Files>
   <Files "client">
       Header set Content-Type application/json
       Header set Access-Control-Allow-Origin *
   </Files>
   

Static site hosts (GitHub Pages, Netlify, Cloudflare Pages, and similar) can serve the files the same way — check their docs for adding custom headers.

Option 3: no website, not on Cloudflare

Any free static hosting works — you only need those two files on HTTPS. Point your domain (or the subdomain you chose) at a free static host and upload the files as in Option 2. Alternatively, moving just your DNS to Cloudflare’s free plan (Option 1) is a one-time change and keeps your registrar and email untouched.

Verify your domain

Once the files are in place, open the Domain page in the control panel and press Verify now. We check both addresses and mark the domain active when they’re right. We also re-check daily and email you if the files ever disappear (for example after a website redesign), so keep them in place permanently.

Troubleshooting

Stuck? Email [email protected] — include your domain and we’ll take a look.