Moving from Mastodon to a new instance or to Micro.blog

Mastodon has a feature to move accounts from one instance to another instance. I spent some time recently exploring how this works so that we could support it in Micro.blog. I used this to consolidate my ActivityPub presence from multiple Mastodon accounts to just @manton@manton.org, powered by my blog and Micro.blog.

From what I can tell, this feature is not well-documented. It does not exist in the ActivityPub spec. The “Move” activity examples in the companion ActivityStreams spec also do not cover moving accounts. So I’ll document some of the technical bits here in the hope that it’ll be helpful to other folks.

To move accounts, 2 things are required:

• From the new instance, set up an “alias” that links your new and old accounts.


• From the old instance, initiate a migration to the new instance.

The Mastodon documentation says that aliases should be set up on both sides of the migration, but this does not seem to be required. In my testing, an alias is only needed on the new instance.

Because I wanted to move to Micro.blog, I added an alias in Micro.blog that references one of my old accounts: @manton@mastodon.social. You can find this in Micro.blog under Account → View Mastodon Details → Aliases.

Aliases are added to the ActivityPub profile information in the field alsoKnownAs. Here’s a snippet of my info:

{
  "preferredUsername": "manton",
  "name": "Manton Reece",
  "alsoKnownAs": [
    "https://mastodon.social/users/manton"
  ],
  …
}

For debugging, I often use curl on the command line to poke around at people’s accounts. To see my full ActivityPub JSON, use something like this with the “actor” URL returned from WebFinger:

curl -L -H "Accept: application/activity+json" https://manton.org/activitypub/manton

The next step is to sign into the old Mastodon instance and tell it to move to Micro.blog. Mastodon will take a few actions when this starts:

• It will verify that there’s an alias on Micro.blog, confirming that both accounts are yours.


• It will lock your Mastodon account, updating the profile to tell people about the new Mastodon instance. (In my case, actually powered by Micro.blog.)


• It will send a “Move” activity to all the instances for all your followers, telling them to update their references to point to your new username.

The “Move” activity is sent to each follower’s inbox just like other activities such as “Create”. It includes a field target for the new instance that the user is moving to:

{
  "actor": "https://mastodon.social/users/manton",
  "target": "https://manton.org/activitypub/manton",
  …
}

Mastodon won’t add alsoKnownAs to your ActivityPub profile on the old instance, but instead it will add a similar field named movedTo with the new actor URL:

{
  "preferredUsername": "manton",
  "name": "Manton Reece",
  "movedTo": "https://manton.org/activitypub/manton",
  …
}

Updating your followers can take quite a while. Likely hours and possibly over a day, if you have hundreds or thousands of followers. It makes sense that this is a very low priority background task. You can watch the progress as Mastodon essentially decrements your follower count on the old instance.

Here’s what Mastodon now looks like for my account, to tell people that I’ve moved:

This is a fairly new feature in Mastodon, and I expect we’ll need to keep refining our support for it as there is more real-world usage. If you’re using Micro.blog, also remember that Micro.blog is not Mastodon. You can follow and reply to anyone on Mastodon, but you can’t use Mastodon-only clients like the upcoming Ivory from Tapbots.

What about moving in the opposite direction, away from Micro.blog to Mastodon? We’ll be adding that later. ActivityPub is only currently enabled for new Micro.blog users, or if you’ve manually enabled it, so I want to wait until we’ve enabled it for all users. Otherwise there will be no way to move Micro.blog-only followers.

✴️ Also on Micro.blog