Mastodon on your own domain without hosting a server

Edit on GitHub

Like many in the past week, I have been having a serious look at Mastodon as an alternative to Twitter.

Mastodon is a social network that is distributed across many servers that have their own smaller communities, and federate with other servers to provide a more “global” social network.

There are many servers out there that you can choose from. Alternatively, you can also self-host your Mastodon server, or use one of many hosted instances, “Mastodon as a service”.

In recent hours, I have seen many people wanting to host their own servers, which is great fun! Self-hosting also has the added benefit of being able to have a Mastodon account on your own domain, and you own your data.

Now, I don’t really care about that (yet?). I ran my own mail server back in the day and am very happy with someone running it for me now. The same goes with Mastodon: I trust the folks at, the server I joined, to do a much better job at this than I will ever do.

However, there is one thing I would like my own server for: discoverability. Much like with e-mail, I want folks to have an easy address to find me, and one that I can keep giving out to everyone even if later I switch to a different Mastodon server. A bit like e-mail forwarding to your ISP’s e-mail service.

The good news is: you can use your own domain and share it with other folks. It will link to your actual account.

Go on, try it. Search for @[email protected], and you will find my @[email protected].

How to discover Mastodon account via custom domain

Reading “how to implement a basic ActivityPub server”, there are a couple of things that stand out:

  • Mastodon (and others) use ActivityPub as their protocol to communicate between “actors”.
  • Actors are discovered using WebFinger, a way to attach information to an email address, or other online resource.

Since discovery is what I was after, WebFinger seemed like the only thing I would need to implement.

WebFinger lives on /.well-known/webfinger on a server. For Mastodon, your server will be queried for accounts using an endpoint that looks like this:

GET /.well-known/webfinger?resource=acct:accountname@server

And indeed, if I look at my Mastodon server’s webfinger for my account, I get a response back!

GET[email protected]

  "subject": "acct:[email protected]",
  "aliases": [
  "links": [
      "rel": "",
      "type": "text/html",
      "href": ""
      "rel": "self",
      "type": "application/activity+json",
      "href": ""
      "rel": "",
      "template": "{uri}"


The next thing I tried was simply copy-pasting this JSON output to my own server under .well-known/webfinger, and things magically started working.

In other words, if you want to be discovered on Mastodon using your own domain, you can do so by copying the contents of https://<your mastodon server>/.well-known/webfinger?resource=acct:<your account>@<your mastodon server> to https://<your domain>/.well-known/webfinger.

One caveat: this approach works much like a catch-all e-mail address. @[email protected] will match, unless you add a bit more scripting to only show a result for resources you want to be discoverable.

Bonus: Discovering folks from Twitter

Discoverability, at this stage, is one of the things that matter to get a proper social graph going. Over the past days, there were a couple of tools I found very useful in finding Twitter folks on Mastodon:

  • Twitodon learns about which Twitter account matches a Mastodon account, from folks using this service.
  • Fedifinder and Debirdify scan Twitter accounts and checks if there is a Mastodon account in their profile data. * Do make sure to add your Mastodon address somewhere on your Twitter profile as well.

Good luck! And give @[email protected] a follow if you make the jump to Mastodon.

Edit: Seems there is a GitHub issue which requests custom domains as well.

Edit (15 Nov 2022): Folks have been using the approach of serving up webfinger on a different domain through proxy setups, e.g. using CloudFlare.

Edit (16 Nov 2022): Jeff Handley shared a PR demonstrating how to apply this to a Jekyll website.

Edit (8 Dec 2022): In search, it looks like the custom alias is only found when logged in to the server. Searching for the alias while not logged in may not return a result.

Leave a Comment


15 responses

  1. Avatar for Nagmay
    Nagmay November 12th, 2022

    This is a perfect way to help others locate the account associated with the custom domain I already own. Thank you for sharing.

  2. Avatar for Beatrice
    Beatrice November 16th, 2022

    Thank you so much! Super helpful.

  3. Avatar for ssfckdt
    ssfckdt November 20th, 2022

    Looks like it has to be HTTPS btw

  4. Avatar for luciano ratamero
    luciano ratamero November 25th, 2022

    hey, thanks for the post! unfortunately, I tried it on my domain and it didn’t work, even with webfinger [dot] net showing the correct data for my user@domain .

    so I tried to find you on mastodon with the username you described on the post, and I couldn’t find you as well. I tried with the usernames of a couple of different people (all of them pointing to this post as an inspiration), and none of them appeared too o_o

    I’m not sure if this is working anymore (maybe something related to mastodon v4?) any ideas on what could be going wrong? if you need help debugging, please ping me!

  5. Avatar for Patrick
    Patrick November 25th, 2022

    Thanks for writing this up - great way to get started.

    p.s. I haven’t looked into it further, but, this comment box couldn’t be typed into on Firefox :)

  6. Avatar for
    [email protected] November 26th, 2022

    I get an error (503Remote SSL certificate could not be verified) when I search for @[email protected] from my account at

  7. Avatar for Andrei
    Andrei November 26th, 2022

    Great resource, Maarten. Today I started to ‘Google’ all the “what/how to”s about this revolutionary Mastodon thing. Super helpful!

  8. Avatar for Marc Brooks
    Marc Brooks December 1st, 2022

    Thanks for the inspiration! I built out a CloudFlare Worker that uses a KV store to map identities. I’ve detailed the information and the source is at

  9. Avatar for Ryan
    Ryan December 3rd, 2022

    Hi Maarten,

    This is really helpful, but I worked through this (with my Pelican site) but it doesn’t appear to be working as expected. I’m not sure if there’s an extra step that’s not documented above.

    If you run curl you get the same output as curl\?resource\=acct:[email protected] but it doesn’t look like I can search for my domain or me on my domain 😔

    I’m also not finding any users when searching for @[email protected] on my mastodon instance (but I DO find you when searching for @[email protected]

    Not sure if I’m doing something wrong OR if this doesn’t work any longer 🤷‍♂️

  10. Avatar for TedT
    TedT December 3rd, 2022

    When I do a search for @[email protected] on Mastodon I get a 503 SSL error.  I have used with my GitHub Pages / Jekyll deployment for No SSL issues. 

  11. Avatar for Alexander Krivacs Schrøder
    Alexander Krivacs Schrøder December 5th, 2022

    @[email protected] doesn’t seem to be working on account of being misconfigured. Also, I couldn’t use the “join the discussion” box to write my comment here; had to manually make the “message” input visible and type it there instead.

  12. Avatar for Scott DeToffol
    Scott DeToffol December 5th, 2022

    Thanks for the tip, but I’m unable to get the following error:

    “Error getting JRD: invalid content-type: “

    Any ideas?

  13. Avatar for Christophe R Patraldo
    Christophe R Patraldo December 7th, 2022

    Thanks for this - It works! check it out: @[email protected] and it should take you to @[email protected]. Wow! That’s really cool. Thanks again!

    Meanwhile, if I put @[email protected] in the search bar in Mastodon, I get: 503Remote SSL certificate could not be verified

  14. Avatar for Maarten Balliauw
    Maarten Balliauw December 8th, 2022

    Side note: In search, it looks like the custom alias is only found when logged in to the server. Searching for the alias while not logged in may not return a result.

  15. Avatar for Séraphin
    Séraphin April 29th, 2023

    Thank you for sharing! BTW, the form is not working on Firefox. I had to change the tag of the #comment-div from div to input to be able to enter text.