An introduction to Mastodon

A beginner's guide to microblogging on Mastodon

Meet Mastodon, the open source Twitter alternative that's spreading like wildfire.

A beginner's guide to microblogging on Mastodon
Image by :

Twitter started out like many exciting tech projects. It invented and then offered a unique "microblogging" service, a kind of interactive RSS feed. Twitter as a company was open to fresh ideas and offered a lot of features. It gradually became such a big deal in modern web usage that it, presumably, felt the need to reel it all back in. Today, Twitter clearly can't support all the crazy things people want to do with it, and has gotten rid of a lot of the features they once offered, and are frequently criticized for being simultaneously unmoderated and too restrictive.

Because it's such a part of the modern web, people tend to treat Twitter as something "we" own. There's certainly a case to be made that the users of even a closed system ultimately do own it, at least insofar as losing all users would essentially end the service. Yet the fact remains that Twitter is a closed source communication method on the otherwise open HTTP medium.

Can open source solve this technical and social quandary?

GNU Social and Mastodon

GNU Social is a social communication software for both public and private communications. It's a microblogging platform in which any person or group of people can run their own nodes of communication, and also connect these nodes to one another for intercommunication. It solves the ownership problem in both the literal and emotional sense: the code, being open source (AGPL), is owned by everyone, and the nodes themselves are so numerous that users can shop around to find a community that best suits them, or start a personal node.

Each node, being independently run and managed, can be used as a private node, or it can be open to other users, it can block users or feeds, or it can accept feeds. Control is truly placed in the hands of the users, and yet the end result is a truly social network.

Mastodon is one implementation of GNU Social focusing on a good, clean user interface and a low barrier-to-entry for self-hosting.

And it's spreading like wildfire as the premier Twitter alternative.

The best thing about it is that you can tether Mastodon and Twitter together to ease your transition.

Joining Mastodon

Part of the advantage of Mastodon is that there isn't just one Mastodon. The project itself owns and runs, but that's just one node in a much larger network. You can join any Mastodon instance that is accepting new users. There's a list of running instances on

On the other hand, if you like to tinker on servers, you're also free to just run your own instance. Mastodon is open source, so (unsurprisingly) developers have contributed several ways to set it up. You can run it as a software package on your server, or run it as a Docker image, or even, experimentally, as a Heroku service.

Signing up with an existing instance is easy. Provide a working email address for account verification and set your desired password. Once you have verified your email address, log in as you would to any other website, using your email address as your login name and your password. Once logged in, you can also set up two-factor authentication.

Using Mastodon

The default Mastodon web interface is a little more complex than Twitter, but no more than, for instance, TweetDeck. There are, of course, other interfaces you could use with Mastodon, including mobile apps or custom Atom feeds or custom web apps using Mastodon's rich API. Since everyone starts out with the web UI, however, it's a good thing to look at to get used to Mastodon's capabilities.


Screenshot of the Mastodon web interface. CC-0.

The web UI consists of four columns. The left column is your primary control panel. Most importantly, it contains your username and avatar, and a text field for you to enter you text. In Mastodon, anything you post is called a "toot" (as in a car horn, or, possibly, the sound that prehistoric mastodons made?).

The left column also has several tabs at the top: Get Started, Local Timeline, Federated Timeline, Preferences, and Logout. That's pretty much all you need to know in order to navigate the interface. Here's what each tab does:

Get Started

The Get Started view is your current, default view. It returns all the other columns to their default views. Think of this as your Home Button.

Local Timeline

The Local Timeline contains all posts by any non-blocked and non-muted user on the same Mastodon server. This is different from Twitter because with Twitter there is no local instance. With Mastodon, you can form communities of users on just one node.

Federated Timeline

The Federated Timeline is a feed of all public posts happening on all nodes. This is the most Twitter-like view of Mastodon's activity because it breaks down the concept of nodes and displays everything happening on the worldwide network.


Users have several options for interacting with other Mastodon users, and those settings in the Preferences panel.


Mastodon preferences. CC-0.

You can set your posts to be private or to go only to your followers. You can also configure two-factor authentication, edit your profile, change your password, add "apps" so that you can interact with Mastodon through its API, configure email notifications, and more.

Feeding frenzy

That's a lot to take in, but the easiest way to start is to just click on the Federated Timeline tab and watch all the excited Mastodon users toot their random thoughts at you in the fourth column.


Federated feed. CC-0.

Interacting with other users is intuitive. You can reply to their post, you can re-post a post that you like, you can follow a user so that their posts appear in your personal feed, located in the second column.

The third column contains notifications. When other users interact with you, you'll see that in the third column.

To sum up:

  • Column 1 is your command center.
  • Column 2 is your personal feed.
  • Column 3 contains notifications.
  • Column 4 displays either your local or the federated timeline.

That's Mastodon.

Mastodon to Twitter with Python3

A social network depends equally on both the "social" part and the "network" part. Mastodon has healthy representation of both.

The technology is stable and robust, so it networks very well, and it's had major boosts in users ever since it scored some high-profile media coverage. However, chances are that not everyone you know on Twitter has migrated yet to Mastodon, so you may want to have your posts on Mastodon also appear on your Twitter feed. You don't want to have to do that manually.

You can get Mastodon and Twitter to cross-post with a tool called MastodonToTwitter. It's a Python 3 script that interacts with Twitter and Mastodon through their respective APIs. On the Twitter side, it takes a little bit of setup, since allowing Twitter API interaction on your account is opt-in.

First, you need to join to get a consumer key and access token, each of which permits you to use external scripts to control Twitter.

Once you create an account at, navigate to My Apps and click the Create New App button.


Create new app. CC-0.

Creating a new app isn't nearly as scary as it sounds. In this context, the "app" really is just a mechanism to acquire login tokens. Name your app anything you want to, provide a fake description and a fake website. Leave the callback field empty.


You can use these settings, verbatim. CC-0.

Once your app has been created, you're taken to an overview of the app. While this does provide your consumer key, you need several more pieces to enable API access. Click the manage keys and access tokens link next to the Consumer key (API Key) line.


App overview. CC-0.

On the Application Settings screen, click the Create my access token button. This generates your access tokens, and displays all the information you need in one place.


Keep it secret, keep it safe. CC-0.

Keep these keys safe, because they allow access to your account without information like username and password. Do not share them with others, do not take screenshots of them and post them online.


To run MastodonToTwitter, you must install its dependencies: pip3, python-twitter, and To obtain these these on Fedora or similar Linux distribution:

$ sudo dnf install python3-pip
$ sudo python3 -m pip install twitter-python

Then download MastodonToTwitter from GitHub.

$ git clone MastodonToTwitter.clone

Change directory to MastodonToTwitter.clone and run the script with Python3:

$ python3 ./

The script has a first-run setup mode that automatically launches if it doesn't find configuration files, so just follow the prompts.

For Twitter, there will be four prompts: one for each key that you obtained from creating your Twitter app. Just paste in the key codes, exactly as Twitter provided them.

For Mastodon, you'll only need your registered email address and password.

Once you've passed all the setup steps, MastodonToTwitter runs non-interactively, silently listening to Twitter and Mastodon for any activity. Post something to Mastodon, and you'll see it be detected by MastodonToTwitter, and then in about 30 seconds the same post pops up as a Twitter post. The same works in reverse.

How you run MastodonToTwitter is up to you. You're free to run in manually whenever you want to cross-post, or you can set it up as a cron job so that it runs every hour or two. If you're a very active Twitter user, you can even run it as a daemon on a server (a low-powered Raspberry Pi server is pretty easy to set up) so that it syncs your accounts instantly.

Join the federation

The future of the independent and free web is in the federation: independent nodes managed by real people with real and trusted communities, all feeding into a larger amalgamation. The GNU project, MediaGoblin, Mastodon, GNUnet, and many others, are working toward making this a reality.

Instead of complaining about being abused by your Internet corporate sponsors, why not join the Federation? Captain Kirk did, and things turned out pretty well for him. Give Mastodon a try!



One more soldier in the Federation

Go guys, it's really quick and simple to launch your own instance.

Vote up!
Vote down!

Here's a really great article about GNU Social, Mastodon, and Federation.

Vote up!
Vote down!

It's probably worth mentioning that you can ping another user of Mastodon by mentioning them in a toot with this syntax:

Where @seth is the username, and the is the instance (or node, or server) they have their account.

Alternately, this syntax:

Vote up!
Vote down!
Leon Palmer

Does anyone know what happens if you signup via a particular instance and that goes down temporarily or the maintainer of that instance decides to take it down permanently?

Vote up!
Vote down!
Puff Hammer

I was actually just wondering the same thing. I love the idea, but that is a very real question. Guess we'll find out

Vote up!
Vote down!

The same thing that happens to a Twitter user if Twitter goes down temporarily or permanently, but at least with The Federation (GNU Social, Mastodon etc) the rest of the network doesn't go down with it, just like the email network doesn't go down temporarily or permanently if GMail goes down.

Hosting your own instance is one way to avoid depending on someone else's server, but it's going to be the case for a while yet (if not forever) that some people just can't host our own instance (for lack of server-side skills or $ for hosting fees). Working on making each user's identity portable across instances is a priority, including their social graph (followers, followed) and post history. Ideally identity would be portable not only regardless of instance, but regardless of which federated app that instance was running.

Vote up!
Vote down!

As Strypy says, yes, if an instance you are using evaporates, then so does your user account. This is a reality of modern web services and probably why many people opt to use the multimillion-dollar providers; presumably, they'll never evaporate (not true, but it's the perception, and in practise, there does seem to be a trend that if a corner of the Internet fails, some greater entity will buy it out).

On the independent web, you have different ways to mitigate this risk.

1) First, you can export your data. Mastodon allows for this through its web UI and through its API. So if you were very concerned about losing past toots, or your list of friends, and so on, you could export the data on a semi-regular basis, and even script it through the API.

2) Alternately, you can run your own instance, or team up with some reliable group of people who you trust and run a co-op instance.

3) Many instances that have been brought up so far also have Patreon accounts, so if you want to help ensure an instance sticks around, throw money at it. Get to know the admin. Take an active role in your web use! Consumer culture tends to eat itself, so take this as an opportunity to be a part of the system you use.

Lots of options!

Vote up!
Vote down!

I would like to setup a server. Are there step-by-step instructions on performing maintenance tasks, such as upgrading to the latest version?

Vote up!
Vote down!

It's all still pretty new, so the docs are still developing.

You can get a start here:

But otherwise, chat with some other instance maintainers and the developers themselves to find out what the best practises are.

Good luck!

Vote up!
Vote down!

Comment now