MacKuba.eu

Running Bluesky PDS undockered

2026-02-04T19:14:20Z

A bit over a year ago, in the first week of January 2025, I migrated my main Bluesky account to my own PDS on a Netcup VPS. It’s been quite easy to set up using the official installer, and it’s been running pretty much without any problems or maintenance the whole year.

Despite that, I haven’t been 100% happy with this setup for one reason: Docker. So I decided to try to take it out of the box, and I made it run first on the same VPS installed separately, and then moved it to another machine this month with a clean install. This blog post is a guide to how I did this, if you’re interested. There are a few existing posts about this already:

But I figured it doesn’t hurt to make another one that does things slightly differently again. “There are many like this, but this one is mine”. (I mostly followed the benharri.org version.)

Note: I’m describing what I did to migrate an existing PDS from in-Docker to outside-Docker, so I already had existing data and pds.env config; if you wanted to install one from scratch this way, you’d probably need to also set up the config manually.

You might be asking: why? And that’s a good question. I mostly wouldn’t recommend this setup over the standard Docker one by default, unless you know what you’re doing. The standard installation is literally running one command and answering some questions, and then it auto-updates and manages everything.

My reason is that I’m generally pretty familiar with installing things on Linux servers manually, but I’m completely unfamiliar with Docker. I always wanted to do some modifications on the PDS, but I didn’t know how, because the Docker setup basically takes over the whole server for itself. I don’t know where it pulls code from, I don’t know where it puts it, and I don’t know when it can overwrite any changes I make. I don’t feel in control. (And to be clear, this is likely a me problem.)

So here’s what I did (this setup is for Ubuntu 24.04 Noble):

Install Nginx

The standard PDS distribution uses Caddy, but I use Nginx everywhere and I have configs built for it, so I’ve set up Nginx:

# install Nginx
sudo apt-get install --no-install-recommends nginx-light

# enable HTTP on the firewall
sudo ufw allow http/tcp
sudo ufw allow https/tcp

# if you haven't enabled ufw before:
sudo ufw limit log ssh/tcp
sudo ufw enable

Also here’s a standard thing I do on VPSes to let me install webapps in /var/www from my account:

# set up environment for webapps

sudo groupadd deploy
sudo adduser psionides deploy
sudo chown root:deploy /var/www
sudo chmod 775 /var/www

I also need Certbot for LetsEncrypt:

# install Certbot

sudo apt-get install --no-install-recommends certbot python3-certbot-nginx
sudo certbot plugins --nginx --prepare

certbot plugins --nginx --prepare does some initial setup of some config files in /etc/letsencrypt that are unrelated to specific certificates.

One thing to note is that the standard setup with Caddy uses a .well-known route to verify any handles under *.yourdomain.com, and it automatically creates HTTPS certificates for those subdomains; this wouldn’t be as simple here, but I don’t need to be able to mass create new handles under my domain. If I ever need one or two, I’ll just set them up manually.

Email

We’ll also need email – you can use an external SMTP, but I like to use local sendmail that’s configured to forward emails to my main account:

# install Postfix
sudo apt-get install --no-install-recommends postfix

  # choose: "Internet site"
  # enter domain: "lab.martianbase.net"

# set up the email forwarding
sudo nano /etc/postfix/virtual

  # add a line like this:
  # kuba@lab.martianbase.net my.real.email@domain.com

sudo nano /etc/postfix/main.cf

  # add:
  # virtual_alias_domains = lab.martianbase.net
  # virtual_alias_maps = hash:/etc/postfix/virtual

sudo postmap /etc/postfix/virtual
sudo service postfix reload

# enable SMTP on firewall
sudo ufw allow smtp/tcp

If you set things up this way, you need to set the PDS_EMAIL_SMTP_URL in pds.env to smtp:///?sendmail=true.

Note: you will probably need to set up a few things the right way in the DNS and might also need more tweaks in the /etc/postfix/main.cf for the email sending and forwarding to work. I honestly don’t understand the Postfix config well enough, I just have a setup that works and I don’t touch it, but it’s old and I don’t know how correct it is, so I won’t share it here. From my experience, it’s generally not super hard to configure self-hosted email in such way that it works for sending emails to you and only to you (like I have with my PDS and my Mastodon instance). If it goes to spam, you know where to look, and if you move it to the inbox, generally the email service should remember and whitelist the sender. (Sending emails to others is a whole different story of course.)

NodeJS

Next, NodeJS. I used asdf to install it (the version 0.15 is because in 0.16 they did a complete rewrite in Go from the original Bash version, and some things don’t work as before).

# install asdf
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.15.0
nano .bashrc

  # add:
  # source "$HOME/.asdf/asdf.sh"

# ---
# log out & back in here - this is also needed for the deploy group to take effect
# ---

# install node
asdf plugin add nodejs

NODE_VER=`asdf latest nodejs 22`
asdf install nodejs $NODE_VER
asdf global nodejs $NODE_VER

corepack enable
asdf reshim nodejs

The Docker version runs on 20.x, but that’s almost EOL, so I’ve upgraded to the latest 22.x. 24.x doesn’t work at the moment, I get some ugly errors during installation.

Install the PDS

Now the actual PDS code. I’ve decided to keep the code in /var/www, fetch it from git and use git pull for updates, and keep the data separately in /var/lib.

cd /var/www
git clone https://github.com/bluesky-social/pds
cd pds/service

pnpm install --production --frozen-lockfile

Migrate the data

Now it’s time to copy over the data from the previous setup.

On the first server I did it like this (remember to also turn off and disable the old PDS service in Docker):

sudo rsync -rlpt /pds /var/lib/
sudo chown -R psionides:psionides /var/lib/pds

For the second one, I made a temporary SSH key on the old server:

ssh-keygen -t ed25519 -f ~/.ssh/migration -N "" -C "pds migration"

Added it to authorized keys on the new one:

nano ~/.ssh/authorized_keys

Prepared an empty directory:

sudo mkdir /var/lib/pds
sudo chown psionides:psionides /var/lib/pds

And rsynced the data from the old one to the new one:

# install if missing on the target server:
sudo apt-get install rsync

rsync -rltv -e "ssh -i ~/.ssh/migration" /var/lib/pds/ newserver:/var/lib/pds/

I tried to sync it from a local machine first, but I realized it would take much longer, and between two servers on the same network it took less than a minute for many GBs.

Start the service

With the data copied, it’s time to finish the installation. First, an HTTPS certificate – for now, I made one using manual DNS registration before switching the DNS records:

sudo certbot certonly --manual --preferred-challenges dns --key-type ecdsa \
    -m $myemail --agree-tos --no-eff-email -d lab.martianbase.net

The way it works is that it gives me a kind of verification token, and I need to put it in a TXT DNS record at _acme-challenge.lab.martianbase.net before pressing continue.

Then, I added a systemd service at /etc/systemd/system/pds.service:

[Unit]
Description=Bluesky PDS
After=network.target

[Service]
Type=simple
User=psionides
WorkingDirectory=/var/www/pds/service
ExecStart=/home/psionides/.asdf/shims/node --enable-source-maps index.js
Restart=on-failure
EnvironmentFile=/var/lib/pds/pds.env
Environment="NODE_ENV=production"
TimeoutSec=15
Restart=on-failure
RestartSec=1
StandardOutput=append:/var/lib/pds/pds.log

[Install]
WantedBy=default.target

I also told the PDS what port to run on in pds.env:

PDS_PORT=3000

And then enabled it like this:

sudo systemctl daemon-reload
sudo systemctl enable --now pds

Test?

$ curl http://localhost:3000

         __                         __
        /\ \__                     /\ \__
    __  \ \ ,_\  _____   _ __   ___\ \ ,_\   ___
  /'__'\ \ \ \/ /\ '__'\/\''__\/ __'\ \ \/  / __'\
 /\ \L\.\_\ \ \_\ \ \L\ \ \ \//\ \L\ \ \ \_/\ \L\ \
 \ \__/.\_\\ \__\\ \ ,__/\ \_\\ \____/\ \__\ \____/
  \/__/\/_/ \/__/ \ \ \/  \/_/ \/___/  \/__/\/___/
                   \ \_\
                    \/_/

It’s working! Now, the Nginx config.

Nginx config for the PDS

In /etc/nginx/sites-available/pds.site:

# this is needed to proxy the relevant HTTP headers for websocket
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

upstream pds {
  server 127.0.0.1:3000 fail_timeout=0;
}

server {
  server_name lab.martianbase.net;
  listen 80;
  listen [::]:80;  # ipv6

  # redirect any http requests to https
  location / {
    return 301 https://$host$request_uri;
  }

  # except for certbot challenges
  location /.well-known/acme-challenge/ {
    root /var/www/html;
  }
}

server {
  server_name lab.martianbase.net;
  listen 443 ssl http2;
  listen [::]:443 ssl http2;

  ssl_certificate /etc/letsencrypt/live/lab.martianbase.net/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/lab.martianbase.net/privkey.pem;

  access_log /var/log/nginx/pds-access.log combined buffer=16k flush=10s;
  error_log /var/log/nginx/pds-error.log;

  client_max_body_size 100M;

  location / {
    include sites-available/proxy.inc;
    proxy_pass http://pds;
  }
}

In /etc/nginx/sites-available/proxy.inc:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Origin "";
proxy_set_header Proxy "";

proxy_buffering off;
proxy_redirect off;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

tcp_nodelay on;

Then:

sudo ln -s /etc/nginx/sites-available/pds.site /etc/nginx/sites-enabled/
sudo nginx -t
sudo service nginx reload

DNS

At this point it was time to update the DNS and wait…

Once it started working for me, I also had to wait a bit more for the existing relays to notice the IP change and I needed to poke them a few times to reconnect to me again, like this:

curl https://bsky.network/xrpc/com.atproto.sync.requestCrawl \
  --json '{"hostname": "lab.martianbase.net"}'

Restarting the server with sudo service pds restart also sends a requestCrawl at least to bsky.network. What you want is to see in the pds.log that after pds has started it says request to com.atproto.sync.subscribeRepos. There was a brief moment when I could post something, but after reloading bsky.app I wouldn’t see my post, because the AppView hasn’t indexed it yet… thankfully, after the relay finally reconnected, it backfilled the missing events.

I also updated the Certbot certificate again the normal way so I wouldn’t forget about it later:

sudo certbot certonly --webroot --webroot-path /var/www/html \
    --key-type ecdsa -d lab.martianbase.net

(There’s also a more automated Nginx verification method, where it adds the required certificate lines to your Nginx configs automatically, but I don’t like it because it makes a terrible mess of the configs…)

Gatekeeper

There was one more thing I did while I was already messing with the PDS, which was to add Bailey Townsend’s Gatekeeper service, which restores support for email-based 2FA. For some reason, the email 2FA was implemented in the “entryway” PDS bsky.social and not in the main code, and as of today it still hasn’t been added to the self-hosted PDS distribution… so Bailey decided that “we can just do things” and went and added it himself. You just need to install it separately (it’s written in Rust).

First, we install the 🦀:

# install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --profile minimal
# (press enter)

source ~/.cargo/env

I used rustup, because Gatekeeper requires a fairly new version of Rust and the one I had in Ubuntu LTS repo didn’t cut it.

We also need some additional dependencies for building:

# some general compilers and stuff
sudo apt-get install --no-install-recommends build-essential

# openssl and pkg-config
sudo apt-get install --no-install-recommends libssl-dev pkg-config

Now, time to clone and build the service:

git clone https://tangled.org/baileytownsend.dev/pds-gatekeeper /var/www/gatekeeper
cd /var/www/gatekeeper/
cargo build --release
sudo cp target/release/pds_gatekeeper /usr/local/bin/

(It takes a bit of time to compile, go make yourself a coffee ☕️)

The current version is missing support for sendmail email transport, so I had to make some tweaks to make it work (see PR).

There are a couple of ENV entries we need to add to the pds.env:

PDS_BASE_URL=http://localhost:3000
GATEKEEPER_PORT=8000

And again, we need to write a systemd service at /etc/systemd/system/gatekeeper.service:

[Unit]
Description=Bluesky Gatekeeper
After=network.target

[Service]
Type=simple
User=psionides
ExecStart=/usr/local/bin/pds_gatekeeper
Restart=on-failure
Environment="PDS_ENV_LOCATION=/var/lib/pds/pds.env"
TimeoutSec=15
Restart=on-failure
RestartSec=1
StandardOutput=append:/var/lib/pds/gatekeeper.log

[Install]
WantedBy=default.target

And launch it:

sudo systemctl daemon-reload
sudo systemctl enable --now gatekeeper

Finally, a few updates to the Nginx config:

upstream gatekeeper {
  server 127.0.0.1:8000 fail_timeout=0;
}

server {
  ...

  location /xrpc/com.atproto.server.createSession {
    include sites-available/proxy.inc;
    proxy_pass http://gatekeeper;
  }

  location /xrpc/com.atproto.server.getSession {
    include sites-available/proxy.inc;
    proxy_pass http://gatekeeper;
  }

  location /xrpc/com.atproto.server.updateEmail {
    include sites-available/proxy.inc;
    proxy_pass http://gatekeeper;
  }

  location /@atproto/oauth-provider/~api/sign-in {
    include sites-available/proxy.inc;
    proxy_pass http://gatekeeper;
  }
}

And reload it again:

sudo nginx -t && sudo service nginx reload

At this point the PDS should be fully operational, including email 2FA when you try to log in 🎉

For creating accounts and other admin stuff, you can use the pdsadmin scripts from the source code dir, but you need to pass a PDS_ENV_FILE env var with the path to pds.env:

cd /var/www/pds
PDS_ENV_FILE=/var/lib/pds/pds.env bash pdsadmin/account.sh list

Backups

There’s one last thing – it would also be nice to have backups of your nearly 3 years worth of Bluesky posts…

I do it like this:

# create a backup user
sudo adduser archivist

# add a separate SSH key from local Mac
sudo mkdir /home/archivist/.ssh
echo "ssh-ed25519 ... archivist@martianbase.net" | sudo tee /home/archivist/.ssh/authorized_keys
sudo chown -R archivist:archivist /home/archivist/.ssh

sudo nano /usr/local/sbin/backup_pds:

#!/bin/bash

set -e

service pds stop
rsync -rlpt --exclude="pds.log*" /var/lib/pds/ /var/backups/pds
chmod -R g+rX /var/backups/pds
chown -R root:archivist /var/backups/pds
service pds start

sudo chmod a+x /usr/local/sbin/backup_pds

sudo nano /etc/cron.d/backup_pds:

10 10 * * *   root   /usr/local/sbin/backup_pds

And then I have a cron job on the local Mac which runs this backup script:

#!/bin/bash

SSH_COMMAND="ssh -i ~/.ssh/archivist"

rsync -rltq -e "$SSH_COMMAND" "archivist@lab.martianbase.net:/var/backups/pds/" pds

This way, at one point during the day the PDS data is copied to another folder on the server, shutting down the PDS for a moment to make sure the .sqlite files don’t end up corrupted, and then at some point later, my Mac separately rsyncs the copy of the data from that second folder, while the files aren’t being actively written to. This obviously doubles the data size requirements, so it wouldn’t be feasible for a larger PDS, but it’s totally fine on mine.

And that’s it. A bit more than curl | bash, but I now control every piece of it and I can change them as I please. The old-school way, as God intended 😎

ATProto blog posts collection

2025-11-18T18:59:04Z

I come across a lot of blog posts about the AT Protocol and Bluesky technicals – both on Bluesky official blogs and those of the team members, and by independent developers from the community. So many people are blogging now (especially now that Leaflet got popular in these circles) that I started using an RSS reader again just to keep up with everything.

These posts are usually shared widely for a day or two, and then kind of forgotten – but a lot of them contain some valuable knowledge that is still relevant much later. Even if someone remembers that something like this has been written, it’s not always easy to dig it out from the archive.

I thought it would be nice to have one place collecting those old and newer blog posts to make them easier to find. So I went through those RSS feeds, my like archives and other places, and collected everything I could find here in an organized list. I also included the documents from the “Proposals” GitHub repo, and various posts from the “Discussions” section in the ATProto repo.

This is a subjective selection – from many blogs I skipped some less relevant posts or only included a couple out of many – so if you’re interested, click through to the home page from any post and look for the other posts there.

Search posts by title:

Bluesky official sources

atproto.com

ATProto for distributed systems engineers (Sep 2024)
Atproto Ethos (Apr 2025)

bsky.social/about/blog

Composable Moderation (Apr 2023)
How to verify your Bluesky account (Apr 2023)
Federation Architecture Overview (May 2023)
Bluesky: An Open Social Web (Feb 2024)
Bluesky’s Stackable Approach to Moderation (Mar 2024)
Tips and Tricks for Bluesky Search (May 2024)
Bluesky Welcomes Mike Masnick to Board of Directors (Aug 2024)
Bluesky Announces Series A to Grow Network of 13M+ Users (Oct 2024)
2024 In Review (Dec 2024)
Bluesky’s Patent Non-Aggression Pledge (Oct 2025)

docs.bsky.app

Click to expand

github.com/bluesky-social/atproto/discussions

Click to expand

2023

brainstorm ideas for Cool Developer Tools (Feb 2023)
Intention to remove repository history (Jul 2023)
Planned Changes to DID Documents (August 2023) (Aug 2023)
DID PLC Rate Limits and Validation (Sep 2023)
Upcoming Disruptive Protocol and Infra Changes (Oct 2023)
Migrating bsky.social to Multiple PDS Instances (Nov 2023)
That which we call a “BGS”, By any other name would smell as sweet (Nov 2023)
Tightening Datetime, Record Key, and TID validation (Dec 2023)

2024

Protocol Tech Debt (Feb 2024)
Summary of Recent Changes (Feb 2024)
March 2024 Protocol Updates (Mar 2024)
What does a PDS implementation entail? (Mar 2024)
What goes in to a Bluesky or atproto SDK? (Apr 2024)
OAuth Roadmap (Jul 2024)
Service auth token iteration – method binding & nonces (Aug 2024)
Brainstorming: atproto Dev Tooling and Experience (Aug 2024)
What does an AppView implementation entail? (Nov 2024)
Relay Operational Updates (Nov 2024)
Call for Developer Projects (Nov 2024)
RFC: Lexicon Resolution (Nov 2024)
Account Lifecycle Best Practices (Dec 2024)
Account Migration Details (Dec 2024)

2025

Proposal: OAuth Scopes (Mar 2025)
Relaxing DID PLC Verification Method Constraints (Jul 2025)
OAuth Client Security in the Atmosphere (Jul 2025)
Adding internal repositories to Bluesky’s workflows (Jul 2025)
Progress on Auth Scopes Implementation (August 2025) (Aug 2025)
Draft Lexicon Style Guide (Lexinomicon) (Oct 2025)
PLC Operational Updates (Oct 2025)
Lexicon Language Corner Cases (Nov 2025)
Early Permission Sets (Dec 2025)

github.com/bluesky-social/proposals

0001: User Lists, Reply-Gating, and Thread Moderation (Jun 2023)
0002: Labeling and Moderation Controls (Jun 2023)
0003: Hashtags (Jun 2023)
0004: OAuth 2.0 for the AT Protocol (Feb 2024)
0005: Ozone Moderation History (Oct 2024)
0006: AT Protocol Sync v1.1 (Feb 2025)
0007: Moderation Report Routing (Feb 2025)
0008: User Intents for Data Reuse (Mar 2025)
0009: Moderation Report Granularity (May 2025)
0010: Client assertion backend for browser-based applications (Jun 2025)
0011: Auth Scopes for ATProto (Jun 2025)
0012: Infrastructure Abuse Notices (Nov 2025)

Bluesky team

jaygraber.medium.com (Jay Graber, CEO)

Web3 is Self-Certifying (Dec 2021)

pfrazee.com (Paul Frazee, CTO)

Why RichText facets in Bluesky (Jan 2024)
Why not RDF in the AT Protocol? (Jan 2024)
Why isn’t Bluesky a peer-to-peer network? (Jan 2024)
Guidance on Authoring Lexicons (Mar 2025)
Atmospheric Computing (Dec 2025)

pfrazee.leaflet.pub (Paul Frazee, CTO)

We probably need to rename the AppView (Sep 2025)
Update on Protocol Moderation (Sep 2025)
Private data: developing a rubric for success (Sep 2025)
Three schemes for shared-private storage (Sep 2025)
Social platforms are not neutral (Oct 2025)
The politics of purely client-side apps (Nov 2025)

bnewbold.net (Bryan Newbold)

Progress on atproto Values and Value Proposition (Aug 2024)

whtwnd.com/bnewbold.net (Bryan Newbold)

Notes on Running a Full-Network atproto Relay (Jul 2024)
Migrating PDS Account with ‘goat’ (Oct 2024)
Reply on Bluesky and Decentralization (Nov 2024)
Registering Identity Recovery Keys via PDS, using goat (Feb 2025)
A Full-Network Relay for $34 a Month (May 2025)
AT Moderation Architecture (Oct 2025)

bnewbold.leaflet.pub (Bryan Newbold)

AT Namespaces for Community Spaces (Oct 2025)
Record Versioning (Nov 2025)
Big Indexing (Dec 2025)

dholms.leaflet.pub (Daniel Holms)

PLC Threat-modeling & Auditability (Dec 2025)

jimray-bsky.leaflet.pub (Jim Ray)

The Importance of Backfillability (Dec 2025)

mozzius.dev (Samuel)

React Native, and “the native feel” (Oct 2024)
ATProto by example part 1: Records and Views (Mar 2025)

emilyliu.me (Emily Liu, ex-Bluesky)

Using Bluesky posts as blog comments (Nov 2024)

jazco.dev (Jaz, ex-Bluesky)

Solving Thundering Herds with Request Coalescing in Go (Sep 2023)
Scaling Go to 192 Cores with Heavy I/O (Jan 2024)
Your Data Fits in Memory (GraphD Part 1) (Apr 2024)
An entire Social Network in 1.6GB (GraphD Part 2) (Apr 2024)
How HLS Works (Jul 2024)
Jetstream: Shrinking the AT Proto Firehose by >99% (Sep 2024)
When Imperfect Systems are Good, Actually: Bluesky’s Lossy Timelines (Feb 2025)
Turning Billions of Strings into Integers Every Second Without Collisions (Sep 2025)

ATProto community

whtwnd.com/futur.blue (Futur)

atproto relay any% speedrun (Mar 2025)
in and out, quick appview adventure (Jun 2025)

overreacted.io (Dan Abramov, ex-Bluesky)

Open Social (Sep 2025)
Where It’s at:// (Oct 2025)

underreacted.leaflet.pub (Dan Abramov, ex-Bluesky)

we can just do things (Oct 2025)

bsky.bad-example.com (Phil)

consuming the jetstream firehose correctly (Feb 2025)
Can atproto scale down? (Feb 2025)

mackuba.eu 🙃

A complete guide to Bluesky (Feb 2024)
Introduction to AT Protocol (Aug 2025)

shreyanjain.net (Shreyan)

Nostr and ATProto (Jul 2024)

jcsalterego.leaflet.pub (Jerry Chen)

We live in a space station (Oct 2025)

da.vidbuchanan.co.uk (David Buchanan, @retr0.id)

Hijacking Bluesky Identities with a Malleable Deputy (Sep 2023)
Adversarial ATProto PDS Migration (Jul 2025)

marvins-guide.leaflet.pub (Bailey Townsend)

Host a PDS via a Cloudflare Tunnel (Jul 2025)
A blob in the bucket (Aug 2025)
What the hell is the atmosphere anyway (Sep 2025)
What the hell is a rotation key? (Nov 2025)

dame.is (Dame)

How I made an automated dynamic avatar for my Bluesky profile (Feb 2025)
Creating a decentralized bathroom (powered by the AT Protocol) (Mar 2025)
A guestbook and welcome message for my atproto PDS (May 2025)

steveklabnik.com (Steve Klabnik)

How Does BlueSky Work? (Feb 2024)

knotbin.leaflet.pub (Roscoe Rubin-Rottenberg)

Wherever you get your Podcasts (Aug 2025)

blog.smokesignal.events

Creating a did-method-web Identity for ATProtocol (Aug 2025)

graysky.app

Adding comments to this blog (Feb 2024)

Other recommended blogs

Connected Places newsletter (Laurens Hof)
Connected Places Leaflet (Laurens Hof)
How Streamplace Works (Eli Mallon)
Tangled engineering (@tangled.org)
Nick’s Blog (Nick Gerakines)
Bailey’s Weekly Retrospective (Bailey Townsend)
dame’s leaflets (Dame)
icy takes (Anirudh Oppiliappan)
Juliet’s rambles (Juliet)
mildly at-musing (Samuel)
The Smoke Signal blog (@smokesignal.events)
Matthieu’s Leaflet (Matthieu Sieben)
augment (Anuj Ahooja)
Tree For You (Tree)
A New Social (Bridgy Fed)
Kuba’s Lab Notes 😉

How I ran one Ruby app on three SQL databases for six months

2025-10-15T19:11:16Z

Since June 2023, I’ve been running a service written in Ruby (Sinatra) that provides several Bluesky custom feeds (initially built with a feed for the iOS/Mac developers community in mind, later expanded to many other feeds). If you don’t know much about Bluesky feeds, you make them by basically running a server which somehow collects and picks existing posts from Bluesky using some kind of algorithm (chronological or by popularity, based on keyword matching, personal likes, whatever you want), and then exposes a specific API endpoint. The Bluesky AppView (API server) then calls your service passing some request parameters, and your service responds with a list of URIs of posts (which the API server then turns into full post JSON and returns to the client app). This lets you share such feed with anyone on the platform, so they can add it to their app and use it like any built-in feed. (If you’re interested, check out my example feed service project.)

In order to provide such service, in practice you need to connect to the Bluesky “firehose” streaming API which sends you all posts made by anyone on the network, and then save either those which are needed for your algorithm, or save all of them and filter later. I chose the latter, since that lets me retry the matching at any time after I modify the keyword lists and see what would be added after that change (and also some of the feeds I now run require having all posts). I also use the same database/service to generate e.g. the total daily/weekly stats here.

All posts made on Bluesky is much less than all posts on Twitter, of course, but it’s still a lot of posts. At the moment (October 2025), there are around 3.5M posts made on average every day; at the last “all time high” in November 2024, it was around 7.5M per day. A post is up to 300 characters of (Unicode) text, but since I also store the other metadata that’s in the record JSON, like timestamp, reply/quote references, embeds like images and link cards, language tags etc., it adds up to a bit less than 1 KB of storage per post on average.

In addition to that, the firehose stream (if you use the original CBOR stream from a relay, not Jetstream, which is a JSON-serving proxy) includes a lot of overhead data that you don’t need in a service like that, plus all the other types of events like handle changes, likes, follows, blocks, reposts, and so on. The total input traffic is around 15 Mbit/s average right now in October 2025 (or around 5 TB per month), and it used to be around twice that for a moment last year. (Jetstream sends around an order of magnitude less, especially if you ask it to send filtered data, e.g. only the posts.)

On disk, the millions of posts per day add up to a few gigabytes per day. Since I was running this on a VPS with a 256 GB disk (Netcup, RS 1000 – reflink), I have a cron job set up to regularly prune all older posts and keep only e.g. last 40 days worth of them (since I don’t really need to keep the older posts forever), so around 200-ish gigabytes total, and around 200 millions of rows in the posts table.

And until March this year, I was keeping all this data in… SQLite 🫠

Chapter 1: You’re probably wondering how I ended up in this situation

I think I had never used SQLite in a web app before this – I normally always used MySQL, since that was commonly used in PHP first and then in Ruby webapps (Rails/Sinatra w/ ActiveRecord). I was used to it, I knew how it worked more or less, and I always thought SQLite was only meant to be used in embedded scenarios like native desktop/mobile apps. But the example feed-generator project in JS shared by Bluesky used SQLite, and since I started out by porting that to Ruby, I ended up also using SQLite, planning to switch to something else later. But you know how it is, that “later” time never comes – and if it ain’t broke, don’t fix it. SQLite worked surprisingly well for much much longer than I expected, with much more data than I expected, and it turns out it can be absolutely ok for server/webapp database purposes, at least in some scenarios. But eventually I started hitting some limitations.

The main problem is that SQLite doesn’t allow concurrent write access. This means that many processes can read posts or other data simultanously, but only one process at a time can write to the database. This could be a serious problem in most webapps, but it worked fine in this particular architecture. You see, there’s really one entry point to the system where the posts are saved: the firehose stream consumer process. All posts come from there, and nothing else saves posts, the Sinatra API server only makes queries to what was already saved from the firehose. This is why this has worked for me for as long as it did.

However… at some point I added a second parallel thread, which separately reads data from the plc.directory and saves data about some accounts' handles and assigned PDS servers. There are also cron jobs running scripts and Rake tasks, which sometimes modify data and sometimes take a bit to run (like that older posts cleaner), and I sometimes run Rake tasks manually to e.g. rebuild feeds.

And this is where I started running into a second related problem: how this concurrent writing is/was handled in ActiveRecord. I don’t know if I can explain this all correctly (see this GitHub issue and this StackOverflow comment), but the gist is, ActiveRecord used some mode of data locking in SQLite, which resulted in a flow like this:

A transaction is started which locks the data for reading.
Some records are loaded and turned into AR models (through a where/find_by call etc.).
Some updates are made to the model objects.
When I call save on the model, AR tries to change the lock mode that would allow it to also make a write.
But something else has made other writes in the meantime.
Because of how the transaction/locks were set up, SQLite decides that the data I’m trying to save might have been modified in the meantime, and aborts the whole transaction and throws an error (SQLite3::BusyException: database is locked).

Changing timeout settings doesn’t fix the problem, because the exception is thrown immediately, without waiting for the other process to finish. What worked around the problem was a mix of:

trying to avoid doing multiple writing operations in parallel at all

rearranging the code a bit artificially so it opens a transaction and then first does some kind of write, even a completely pointless one, before doing the reads, which makes it create the right kind of lock from the beginning:

def rescan_feed_items(feed)
  ActiveRecord::Base.transaction do
    # lulz
    FeedPost.where(feed_id: -1).update_all(feed_id: -1)

    feed_posts = FeedPost.where(feed_id: feed.feed_id).includes(:post).order('time')
    feed_posts.each do |fp|
      ...
    end
  end
end

or so that it does the write without touching the original model, e.g.:

# instead of:
@post.update(thread_id: root.id)

# do:
Post.where(id: @post.id).update_all(thread_id: root.id)

This has mostly let me avoid the problem for a long time, but this meant it kept popping back up sometimes, and I had to write some code sometimes in a way that didn’t logically make sense and was only like that to avoid the exceptions. In particular, with the plc.directory thread, I had to make it pass any changes back to the main thread through a queue so they can be saved to the database from there.

(Ironically, the ActiveRecord folks finally fixed this whole problem in the 8.0 release, just as I finished migrating away from SQLite…)

A second problem was that I started having some performance issues that I couldn’t find a good solution for – e.g. post write operations were occasionally randomly taking e.g. 1 or 2 seconds to finish instead of milliseconds; and I wanted to optimize the app to be able to potentially save as many posts per second as possible, to prepare for larger traffic in the future.

When I was asking for advice, everyone was telling me “dude, just switch to Postgres” 😛 But I haven’t really worked with Postgres before other than briefly, and I knew some things were different there, and I wasn’t sure if I want to switch to something unknown rather than what I knew (MySQL).

And since I have way too much time, no life, and probably a good bit of neurodivergence, I chose the most obvious solution: set up the app on both MySQL and on Postgres on two separate & identical VPSes, and compare how it works in both versions… 🫣

Chapter 2: Getting it to run

Turns out, SQL databases are a bit different from each other in a lot of aspects, and migrating a webapp from one to the other is a bit more work than just editing the Gemfile and database.yml – who would’ve guessed…

Beyond the obvious, here are some things I had to change on the MySQL branch:

Some column type changes:

integer column sizes – in SQLite, all numbers are just integers of any size, so here I changed some to smallint and some to bigint
similarly, some string columns were changed to text
for datetime columns, I’ve set the decimal precision explicitly to 6 digits (this is now the default since AR 7.0, I started on 6.x for some reason)

In queries:

I removed some index hacks like .where("+thread_id IS NULL”), which tell the SQLite query optimizer to use/not use a given index
some date operations had to be rewritten to use different functions, e.g. DATETIME('now', '-7 days') to SUBDATE(CURRENT_TIMESTAMP, 7)
some queries had to be rewritten or updated because they were just throwing SQL syntax errors – e.g. I had to explicitly list table names on some fields in SELECT; or there was this thing in MySQL where I had to nest a subquery for DELETE one level deeper
ActiveRecord::Base.connection.execute returns rows as arrays instead of hashes for some reason, indexed by [0] not by ['field']

For Postgres, in addition to most of the above:

I had to replace 0 / 1 used as false/true in boolean columns with an explicit FALSE / TRUE
date functions in queries were slightly different again, e.g. DATE_SUBTRACT(CURRENT_TIMESTAMP, INTERVAL '7 days')
strings in queries had to be changed to all be in single quotes, not in double quotes, which in Pg are reserved for field names like "post_id" (what SQLite and MySQL use the backticks for: `post_id`)

I could also finally remove all the code hacks added to work around the SQLite concurrency issues – start normally saving handles in the PLC importer thread, rewrite some transaction blocks to a more logical form, and so on.

Chapter 3: Migrating the data

For migration to MySQL, I used the sqlite3mysql tool, written in Python:

pip install sqlite3-to-mysql

sqlite3mysql -K -E -f bluesky.sqlite3 -d bluefeeds_production -u kuba -i DEFAULT -t feed_posts handles post_stats subscriptions unknown_records ...

For the posts table (which is the vast majority of the database size), I used the -c (--chunk) option to import posts in batches:

sqlite3mysql -K -E -f bluesky.sqlite3 -d bluefeeds_production -u kuba -i DEFAULT -t posts -c 1000000

For Postgres, I used pgloader. Unlike sqlite3mysql, it isn’t configured through command-line flags, but instead you need to write “command” files with a special DSL and then pass the filename in the argument. So my command files looked something like this:

load database
from sqlite://./db/bluesky.sqlite3
into postgresql:///bluefeeds_production

with data only, truncate
including only table names like 'feed_posts', 'handles', 'post_stats', 'subscriptions', 'unknown_records';

I’ve split the tables into several command files, because I wanted to do it a bit more step by step since some of the imports were failing.

For the posts table, I’ve similarly set a “prefetch rows” flag to do it in batches:

load database
from sqlite://./db/bluesky.sqlite3
into postgresql:///bluefeeds_production

with data only, truncate, prefetch rows = 10000
including only table names like 'posts';

Using the two importers are two very different experiences: sqlite3mysql takes quite a lot of time to import, but shows very nice progress bars and remaining time estimates; pgloader gives you basically no updates until it’s finished, and even if some tables fail to import, it’s not immediately clear from the summary what happened – however, it does the job in as much as two orders of magnitude less time 😅 I don’t know how much this is because of the tool or the database though (and there are probably ways to speed up the import in MySQL, e.g. by dropping indexes first).

One surprise realization I had during the import: in SQLite, when you define a column as string with limit 50, it doesn’t actually enforce that limit! Apparently I had a whole bunch of records in some tables where the values were much longer than the expected max length… because I was missing Ruby-side AR validations (validates_length_of) in some models – and those records were being rejected by both new databases. So I had to add all those missing length validations and clean up the invalid data first.

An additional problem cropped up in MySQL, which has different text collation rules depending on accents and unicode normalization than SQLite & Postgres. I have a “hashtags” table listing all hashtags that appeared anywhere in the posts, with a unique index on the hashtag name – but the import to MySQL was failing, because some hashtags were considered by MySQL as having the same text as some others, while SQLite had considered them different… I tried to pick a different collation for the table (utf8mb4_0900_as_cs, i.e. both accent-sensitive and case-sensitive), but that only partially helped with some name pairs (“pokemon” vs. “pokémon”), but not with others (different normalization, or invisible control characters, and there are *countless* different types of those, as I have learned…). I eventually gave up and ended up just dropping the unique index for now.

In Postgres, in turn, the problem was that it apparently doesn’t support strings that contain null bytes, and there are some occasional posts that somehow end up with a \0 in the post text… So I had to just filter out such posts as invalid.

if text.include?("\u0000")
  return
end

Finally, something that somehow caused an issue in both versions was a thing that every programmer loves – timezones… When I made a query to count posts added in the last 5 minutes, and it always returned 0, but “last 65 minutes” didn’t, I immediately knew what was going on 🫠

In Postgres, the solution was to tell ActiveRecord to use the timestamptz data type for timestamp columns instead of the default timestamp:

ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.datetime_type = :timestamptz

(and then migrate the existing columns to use that type).

In MySQL, you need to either tell AR to use the timezone the database is using, if it’s not set to UTC:

ActiveRecord.default_timezone = :local

Or tell the database to use UTC:

[mysqld]
default-time-zone = '+00:00'

(but not both…)

Chapter 4: Optimizing

To be able to test both databases with real production traffic in a way that would let me compare them in a fair competition, I’ve set up a kind of “database A/B test” 🙃

The feed was configured to load data from my original SQLite server as before, but in the request handler on that server, instead of calling the feed class locally, the code picked one of the two other servers based on either the “DID” (user ID) of the caller or current timestamp, proxied the call to that server, took the response, and returned it back to the caller:

get '/xrpc/app.bsky.feed.getFeedSkeleton' do
  feed_key = params[:feed].split('/').last

  if ['hashtag', 'follows-replies'].include?(feed_key)
    server = Time.now.hour.odd? ? SERVER_A : SERVER_B
  elsif ['replies'].include?(feed_key)
    server = Time.now.hour.even? ? SERVER_A : SERVER_B
  else
    did = parse_did_from_token
    server = did.nil? || did =~ /[a-m0-4]$/ ? SERVER_A : SERVER_B
  end

  url = "https://#{server}/xrpc/app.bsky.feed.getFeedSkeleton?" + request.query_string
  headers = env['HTTP_AUTHORIZATION'] ? { 'Authorization' => env['HTTP_AUTHORIZATION'] } : {}
  response = Net::HTTP.get_response(URI(url), headers)

  content_type :json
  [response.code.to_i, response.body]
end

This meant that each feed load took a bit longer, but it wasn’t very noticeable in practice, and I had the real traffic split into two more or less equal parts, going to the two servers. (Coincidentally, it’s exactly one year today since I deployed that change – I’ve been procrastinating way too long on this blog post 🫠)

And then started my months-long work of optimizing the databases and queries…

Some problems showed up immediately: a query was returning data immediately in SQLite, and in MySQL or Postgres it just hangs. So in those cases, I often had to add some missing index, or modify the index somehow (e.g. add an additional field, or switch a field in a composite index to DESC), or rearrange a query to make it use the intended index, add some limiting condition, or occasionally (in MySQL) add FORCE INDEX. Those issues were generally fairly easy to fix, and the fix either clearly worked or not. I think some queries I had were just logically not fully thought through, but they had been working fine before because SQLite has some things organized differently on disk and some access patterns work better, hiding the issue with the query.

The bigger problem and one I’ve spent a ton of time on (in the Postgres version) was one specific query in a set of “replies feeds”. I mostly wrote everything about in on my Journal blog on micro.blog back in January, and I remembered much more about it then than I do now, so I’ll just link to that old blog post here.

The TLDR is that I have a set of three feeds: Follows & Replies, Only Replies and Only Posts, which share the same code, just with slightly different filters; these are personalized feeds (i.e. having different content depending on who’s loading them), which for a given user fetch the list of the accounts that user is following, and then make a query asking the database for “most recent N posts from any of the users that this account follows” – so basically a reimplementation of the standard “Following” feed, with some changes.

This query was much slower on the Postgres server than on the other two databases, and Postgres insisted on using the posts index on (time) (scanning possibly millions of rows to find the right ones) instead of using the one on (user, time) some number of times and merging the results (and apparently asking “how to do FORCE INDEX in Postgres” is a terrible heresy 😛). I spent a lot of time on this and it took me a lot of trial and error, asking more experienced people on Bluesky, reading docs and articles, chatting with ChatGPT, and so on. I went through: bumping up the STATISTICS target and/or hardcoding n_distinct (and rolling those back), tweaking some configuration variables, rearranging the query/index in various ways – and what I finally settled on was:

changing the (user, time) index to also include the id primary key as the third field, i.e. (user, time DESC, id), to let it do “Index Only Scans” on it – I haven’t realized that indexes in Postgres don’t reference the primary key, so they can’t be used this way unless the id is explicitly included there!
and setting up a cron job to do very frequent manual VACUUM (4× a day, with forced index_cleanup), because otherwise it has to re-check some of the ids fetched from the index to verify if the rows haven’t been deleted

After those changes, it finally started working really nicely on Postgres, with the mean response time from this query going below 20 ms, while the MySQL version was doing around 50 ms, and the initial Postgres version before the index changes had slowed down to as much as 200-300 ms mean time. (It still occasionally picks the wrong index, for accounts that are somewhere in the middle follows range, over 1000 followed accounts – for those with many thousands, the (time) index is almost always better – but I think that’s somewhat unavoidable.)

Epilogue: There can be only one

In the end, after all the tweaks and optimizations, both servers on both databases were working quite fine, and I think I would probably be ok with either of them. But I had to pick one.

I ended up picking…

…

Postgres! 🏆

In those few months, I managed to read sooo many pages of the documentation, articles about various specific settings, spent so much time in the psql console, reading output from the analyzer, that I got much more comfortable with it than I was at the beginning… So ironically, the fact that I had to spend more time tweaking it to get it to work all smoothly made me prefer it in the end. I felt like specifically because there were so many different dials and switches, I felt more “in control” with Postgres than with MySQL – the tutorials for tuning Postgres mentioned 5-10 different settings at least, and the ones for MySQL basically said “ah, just set innodb_buffer_pool_size to half the RAM and you’re done”. And if you’ve already set that and you’d like to optimize things further? Well… ¯\_(ツ)_/¯

Postgres’s query analyzer output is also more readable and helps you more with figuring out how it’s actually handling the query, and generally various debugging commands seem to provide more readable info about current parameters of the system – while MySQL mostly has a SHOW ENGINE INNODB STATUS command, which just pukes several pages of text output at you.

I’ve been doing various manual benchmarks of how different parts of the system work, what the average response times and query times are and so on, on both versions, and keeping the results in tables, but I can’t really get any general conclusion from this on which database is better at what. It was often things like: one does single row deletes faster and the other does multi-row deletes faster, or one is faster at inserts and the other at counts… but generally it was changing a bit too much over time, and I wasn’t doing it in a super scientifically controlled way.

One thing that I could see on Munin charts in the end was that the Postgres server had higher numbers on the disk read IO/throughput charts, while the MySQL server had noticeably higher numbers on the disk write IO/throughput charts. Not sure if this is a good assumption, but my guess was that with higher traffic in the future, it would generally be easier to scale the read load in Postgres (with various caches, replicas etc.) than to scale the write load in MySQL. Also, in the end after all the optimizations, the key query in the “replies” feeds was working noticeably better in the Postgres version, and in the test “how quickly it can possibly process events when catching up at max speed” (where post record inserts are generally the bottleneck), the Postgres version also ended up with a slightly higher processing speed.

So since March, the app has been running on a new 512 GB VPS on a Postgres database, and it’s been working fine since then.

Introduction to AT Protocol

2025-08-20T17:32:45Z

(Last update: 15 Oct 2025.)

Some time ago I wrote a long blog post I called “Complete guide to Bluesky”, which explains how all the user-facing features of Bluesky work and various tips and tricks. This one is meant to be a bit like a developer version of that – I want to explain in hopefully understandable language what all the pieces of the network architecture are and how they all fit together. I hope this will let you understand better how Bluesky and the underlying protocol works, and how it differs from e.g. the Fediverse. This should also be a good starting point if you want to start building some apps or tools on ATProto.

This post is a first part of a series – next I want to look at some comparisons with the Fediverse and some common misconceptions that people have, and look at the state of decentralization of this network, but that was way too much for one post; so this one focuses on the “ATProto intro tutorial” part.

But before we start, a little philosophical aside:

What is “Bluesky”? Which “Bluesky” are we talking about?

Discussions about Bluesky sometimes get a little confusing because… “Bluesky” could mean a few different things. Language is hard.

First, we have Bluesky the company, the team. Usually, when people want to clarify that they’re talking about the group of people or the organization, they say “Bluesky PBC” (PBC = Public Benefit Corporation), or “Bluesky team”.

(If you want to read a bit about where Bluesky came from and what’s the current state of the company, read these two sections in the Bluesky Guide blog post.)

And we also have Bluesky the product, the social network, the thing that they’ve built. This network is not a single black box like Twitter or Facebook are (despite what they say about it on Mastodon), it’s more like a set of separate and actually very transparent boxes.

The system they’ve built, of which Bluesky was initially meant to be just a tech demo, is called the Authenticated Transfer Protocol, or AT Protocol, or ATProto. Bluesky is built on ATProto, and it is in practice a huge part of what ATProto currently is, which makes the boundary between Bluesky and non-Bluesky a bit hard to define at times, but it’s still only a subset of it.

Bluesky in this second meaning is some nebulous thing that consists of: the data types (“lexicons”) that are specific to the Bluesky microblogging aspect of ATProto, like Bluesky posts or follows; the APIs for handling them and for accessing other Bluesky-specific features; the rules according to which they all work together; and the whole “social layer” that is created out of all of this, the virtual “place” – the thing that people have in mind when they say “this website”, even when it’s accessed through a mobile app. One of the coolest things about Bluesky & ATProto, in my opinion, is that it connects many different independent pieces into something that still feels like one shared virtual space.

People outside the company can create (and are creating) other such things on ATProto that aren’t necessarily Bluesky-related – see e.g. WhiteWind or Leaflet (blogging platforms), Tangled (GitHub alternative), Frontpage (Hacker News style link aggregator), or Grain (photo sharing site). They use the same underlying mechanisms that are at the base of ATProto, but use separate data types, have different rules, goals, and UIs. How do we call these things as a whole, the different sets of “data types + rules + required servers + client apps” that define different use cases of the network?

Bluesky team usually calls them “apps”, but I’m not a big fan of this term, because “app” kinda implies a client app, and that’s just one small piece of it. I sometimes call them “services” – though it’s probably not perfect either, since it implies just the server part in turn. Suggestions welcome :) (I’m mentioning this at the beginning, because this is something that many different parts are related to.)

Personally, when I say “the Bluesky app”, I will generally mean the actual client app (mobile / webapp), not the “service”, and when I say “Bluesky-specific”, I will mean the “service”, not the company; and “Bluesky-hosted” will mean run by Bluesky the company. Hopefully in most cases, it can be guessed from context.

BTW, the commonly accepted term for the whole shared “multiverse” of all ATProto apps is “The Atmosphere”, or “ATmosphere” (though I much prefer the former personally, the weird capitalization bugs me somehow ;). It was coined by someone from the community, but was accepted by the team and is now mentioned on the official atproto site.

Let’s start with defining the various building pieces of the protocol:

Records & blobs

The most basic piece of the ATProto world is a record. Records are basically JSON objects representing the data about a specific entity like a post or profile, organized in a specific way. A post/reply, repost, like, follow, block, list, entry on a list, user profile info – each of these is one record. Most public actions you take on Bluesky, like following someone or liking a post, are performed by creating a record of an appropriate type (or editing/deleting one created before).

For example, this is a post record. This is one of the likes of that post.

Records are stored on disk and transferred between servers in a binary format called CBOR, although in most API endpoints they’re returned in a JSON form (they are equivalent, just different encodings of the same data).

The key thing about records, which has very real consequences for user-facing features, is that you can only create and modify your own records, not those owned by others (and there are no “shared” records at the moment, each record is owned by a specific account). This means that e.g. when you follow someone, you create a follow record on your account, and that other person can’t delete your record, which is why there’s currently no “soft-blocking” feature, i.e. you can’t make someone stop following you (though you can block them). There are workarounds though, as I’ll explain later in the AppView section.

This also means that there’s often an unexpected assymetry between seemingly similar actions: for example, getting a list of people followed by person X is very simple (they’re all X’s records, so they’re all in one place), but getting a list of all followers of X is much harder (each record is in a different place!). This is something that the AppView helps with too, as we’ll see later.

A second, complimentary way of storing user data is blobs. Blobs are basically binary files, meant mostly for storing media like images and video. For example, here is a direct link to an image blob showing a photo of when I started writing this blog post. Blobs are stored on the same server as records, but somewhat separate from them, since it’s a different type of data.

Lexicons

Each record belongs to a specific “record type” and stores its data organized in a specific structure, which defines what kinds of fields it can have with what types, what they mean, which are required, and so on – kind of like XML/JSON Schema. This schema definition which describes a given record type is called a lexicon in ATProto. (If you’re curious why make a new standard, see threads e.g. here, here, or here, or this blog post).

A lexicon needs to have an identifier (called NSID, Namespace Identifier), which uses the reverse domain name format, e.g. app.bsky.feed.post. All lexicons that are used to store the data of a specific app are usually grouped under the same prefix, e.g. Bluesky lexicons all start with app.bsky.

The structure of a given lexicon’s records is defined in a special JSON file – for example, this file defines the app.bsky.feed.post lexicon. As you can see, this is the place which for example specifies that a post’s text can have at most 300 characters (more specifically, Unicode graphemes). This also means that you can’t create a different server which would make posts longer than 300 characters that would be Bluesky-compatible and displayed on bsky.app – such posts would not pass the validation against the post record schema, and would be rejected by any server or client which performs such validation. Essentially, whover designs and controls the given lexicon, decides what kinds of data it can hold and any constraints on it. In order to store a different, incompatible type of data, you need to create a new lexicon (although you can add additional fields to a record that aren’t defined in its lexicon; many third party apps are doing that, like e.g. Bridgy Fed).

Lexicon name prefixes generally define boundaries between “apps” as in “services”, and between the “territory” that’s owned by different parties. The lexicons and endpoints defined by Bluesky are defined either under app.bsky.* – these are things specific to Bluesky the microblogging service – or under com.atproto.*, which are things meant to be used by all ATProto apps and services regardless of the use case. There are also a couple of other minor namespaces like chat.bsky.* for the (centralized) DM service, and tools.ozone.* for the open source Ozone moderation tool.

The lexicon prefix is generally (in most cases) a good way to tell if a piece of the protocol is something Bluesky-specific (specific to the Bluesky service), or something general for all ATProto. There are no record types defined in com.atproto, so things like post, profile, follow are all Bluesky-specific and under app.bsky, as are APIs for e.g. searching users, getting timelines, custom feeds and so on. Meanwhile, com.atproto APIs deal more with things like: info about a repository, fetching a repository, signing up for a new account, refreshing an access token, downloading a blob, etc.

Third party developers and teams building apps on ATProto/Bluesky, which either extend Bluesky’s features or make something completely separate, use their own namespaces for new lexicons, like blue.flashes, social.pinksky, events.smokesignal, sh.tangled, and so on. (There is a lot of nuance to whether you should use your own lexicons or reuse or extend existing ones when building things, and there have been a lot of discussions about it on Bluesky, and even conference talks. A good starting point is this blog post by Paul Frazee.)

Identity

Each user is uniquely identified in the network with their Decentralized Identifier (DID). DIDs are a W3C standard, but (as I understand) this standard mostly just defines a framework, and there can be many different “methods” of storing and resolving the identifiers, and each system that uses it can pick or create different types of those DIDs.

The format of a DID is: did:<type>:<…>, where the last part depends on the method. ATProto supports two types of DIDs, but in practice, almost everyone uses one of them, the “plc”. Each DID has a “DID document”, a JSON file (see mine) which describes the account – in ATProto at least, the document includes things such as: the assigned handles, the PDS server hosting the account, and some cryptographic keys.

An important thing to note is that DIDs are permanent; it’s the only thing that is permanent about your account, because something has to be. There needs to be some unique ID that all databases everywhere can use to identify you, which doesn’t change, and the DID is that ID. This means that you can’t change a DID of one type into another type later.

The main DID method is did:plc, where IIRC “plc” originally stood for “placeholder” (I think it was meant to be temporary until something better is designed), and was later kind of retconned to mean “Public Ledger of Credentials” 🙃 The DIDs of this type are identified by a random string of characters, which looks like this: did:plc:vc7f4oafdgxsihk4cry2xpze. The DID documents of each DID are stored in a centralized service hosted at plc.directory (Bluesky wants to eventually transfer the ownership to some external non-profit), which basically keeps a key-value store mapping a DID to a JSON file. It also keeps an “audit log” of the previous versions of the document (this means that, for example, the whole history of your old handles is available and you can’t erase it!). There’s also some cryptographic stuff there which, as I understand it, lets anyone verify that everything in the database checks out (don’t ask me how).

The other, rarely used method is did:web. Those DIDs look like this: did:web:witchcraft.systems, and the DID document is stored in a specific .well-known path on the given hostname, in this case witchcraft.systems (yes, that’s an actual TLD ;). It does not store an audit log/history like plc does.

The reason why it’s rarely used and not recommended, is because, first, it’s more complicated to create one (though that’s a solvable problem of course, see a just published guide); but second and more importantly, since DIDs are permanent, this means that your account is permanently bound to that domain. You need to keep it accessible and not let it expire, or you lose the account – you can’t migrate it to did:web:another.site at some point later. It gives you more independence, but at the cost of being tied to that domain you have, and this isn’t a tradeoff that most people are likely to want, and definitely not people who don’t understand what they’re getting into.

If you’re fine with that choice, you can create a did:web account and almost everything in Bluesky and ATProto should work exactly the same. “Almost”, because some services forget to implement that second code path, since it’s so rarely used 😉 but in that case, politely nudging the developer to fix the issue should help in most cases :>

Handles

What DIDs enable is that since they act as the unique identifier, your handle doesn’t have to, like it does on Mastodon. I can be @mackuba.bsky.social one day, @mackuba.eu the next day, and @mackuba.martianbase.net the week after. All existing connections – follows & followers, my posts, likes, blocks, lists I’m on, mentions in posts, etc. all work as before, because they all reference the DID, not the handle. With mentions specifically it works kinda funny, because they use what’s called a “facets” system (see later section), where the link target is specified separately from the displayed text. So you can have an old post saying “hey @mackuba.bsky.social”, where the handle in it links to my profile which is now named “@mackuba.eu”. The link still works, because it really links to the DID behind the scenes.

Unlike on the Fediverse, the format of handles is just a hostname, not username + hostname. You assign a whole hostname to a specific account, and if you own any domain name, that can be your username (and if you own a well known domain name, it’s strongly recommended that you do, as a form of self-verification!).

The handle to DID assignment is a two-way link – a DID needs to claim a given handle, and the owner of the domain needs to verify that they own that DID. On the DID side, this happens in the alsoKnownAs field of the DID document (see here in mine). On the domain side, there are two ways of verifying a handle, depending on what’s more convenient to you: either a DNS TXT entry, or a file on a .well-known path.

You might be wondering how handles like *.bsky.social work – in this case, each such handle is its own domain name, and you can actually enter a domain like aoc.bsky.social into a browser and it will redirect to a Bluesky profile on bsky.app. Behind the scenes, this is normally handled by having a wildcard domain pointing to one service, which responds to HTTP requests on that .well-known path by returning different DIDs, depending on the domain. That’s not only a bsky.social thing – e.g. there’s now an open Blacksky PDS server which hands out blacksky.social handles, and there are even “handle services” which only give out handles – e.g. you can be yourname.swifties.social if you want ;)

One place where handle changes break things is (some) post URLs on bsky.app. The official web client uses handles by default in permalinks, which means that if you link to a Bluesky post e.g. from a blog post and you change your handle later, that link will no longer work. You can however replace the handle after /profile/ with the user’s DID, and the router accepts such links just fine, they just aren’t used by default. So the form you’d want to use when putting links in a blog post or article (like the one you’re reading) would be something like: https://bsky.app/profile/did:plc:ragtjsm2j2vknwkz3zp4oxrd/post/3llwrsdcdvc2s.

AT URIs

Each record can be uniquely addressed with a specific URI with the at:// scheme. The format of the URI is:

at://<user_DID>/<lexicon_NSID>/<rkey>

Rkey is an identifier of a specific record instance – a usually short alphanumeric string, e.g. Bluesky post rkeys look something like 3larljiybf22v. So a complete post URI might look like this: at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3larljiybf22v. You can look up at:// URIs in some record browser tools, e.g. PDSls.

AT URIs are used for all references between records – quotes, replies, likes, mute list entries, and so on. If you look at this like record, for example, its subject.uri points to at://did:plc:vwzwgnygau7ed7b7wt5ux7y2/app.bsky.feed.post/3lv2b3f5nys2n, which is the URI of a post record you can see here. Since the URIs use DIDs in the first part, handle changes don’t affect such links.

There is a great guide to AT URIs and DIDs and how to handle them written by Dan Abramov, you may want to check it out here.

User repositories

All user data (records and blobs) is stored in a repository (or “repo”). The repository is identified by user’s DID, and stores:

records, grouped by lexicon into so-called collections
blobs (stored separately from records)
authentication data like access tokens, signing keys, hashed passwords etc.

Internally, an important part of how the repo stores user records is a data structure called “Merkle Search Tree” – but this isn’t something that you need to understand when using the protocol, unless you’re working on a PDS/relay implementation (I haven’t needed to get into it so far).

You can download the records part of your (or anyone else’s!) repo as a bundle called a CAR file, a Content Addressed Archive (fun fact: the icon for the button in the Bluesky app which downloads a repo backup is the shape of a car 🚘).

The cool part is that a repository stores all data of the given user, from *all* lexicons. Including third party developer lexicons. This means that if someone has their account hosted on Bluesky servers, but uses third party ATProto apps like Tangled or Grain, Bluesky lets them store these apps’ records like Grain photos or Tangled pull requests on the same server where it keeps their Bluesky posts. (And yes, of course someone made a lexicon/tool for storing arbitrary files on your Bluesky PDS… and did it in Bash, because why not 🙃)

XRPC

XRPC is the convention used for APIs in the ATProto network. The API endpoints use the same naming convention as lexicon NSIDs, and they have URLs with paths in the format of /xrpc/<nsid>, e.g. /xrpc/app.bsky.feed.getPosts. There are similar lexicon definition files which specify what parameters are accepted/required by an endpoint and what types of data are returned in the JSON response. PDSes, AppViews, labellers and feed generators all implement the same kind of API, although with different subsets of specific endpoints. Third party apps don’t have to use the same convention, but it’s generally a good idea, since it integrates better with the rest of the ecosystem.

Rich text / facets

This one is kinda Bluesky-specific, but it’s pretty important to understand, and I think you can reuse it for non-Bluesky apps too.

The “facets” system is something used for links and possibly rich text in future in Bluesky posts. It’s perhaps a little bit unintuitive at first, but it’s pretty neat and allows for a lot of flexibility.

The way you handle links, mentions, or hashtags, is that they aren’t highlighted automatically, but you need to specifically mark some range of text as a link using the facets. A facet is a marking of some range of the post text (from-to) with a specific kind of link. If you look e.g. at this post here, you can see that it has a facet marking the byte range 60-67 of the post text as a hashtag “ahoy25”. If there was no facet there, it would just render as normal unlinked text “#ahoy25” in the post (when you see that, it’s an easy tell that a post was made using some custom tool that’s in early stages of development). It works the same way for mention links and normal URL links.

(If you’re curious why they implemented it this way, check out this blog post.)

Note that the displayed text in the marked fragment doesn’t have to match what the facet links to; this means that you can have links that just use some shorter text for the link instead of a part of the URL, in order to fit more text in one post (although in the official app, clicking such link triggers a warning popup first). E.g. some Hacker News bots commonly use this format, see this post. The Bsky app doesn’t let you create such posts directly, but some other clients like Skeetdeck do.

Facets are also used for URL shortening – if you just put a long URL in the text of a post made through the API, it will be neither shortened nor highlighted. You need to manually mark it with a facet, and manually shorten the displayed part to whatever length you want.

Likely the most tricky part is that the from-to index numbers you need to use for the ranges are counted on a UTF-8 representation of the text string, but they’re counted in bytes and not in unicode scalars – this is somewhat of an unfortunate tech debt thing as I understand, and it was made this way mostly because of JavaScript, which doesn’t operate on UTF-8 natively, only in the form of byte arrays. This means you need to be extra careful with the indexes.

Ok, now that we got through the basic pieces, let’s talk about servers:

PDS

The original copy of all user data is stored on a server called PDS, Personal Data Server. This is the “source of truth”. A PDS stores one or more user accounts and repos, handles user authentication, and often serves as an “entry point” to the network when connecting from client apps. Most network requests from the client are sent to your PDS, although only some of them are handled directly by the PDS, and the rest are proxied e.g. to the AppView.

Each PDS has an XRPC API with some number of endpoints for things like listing repositories, listing contents of each, looking up a specific record or blob, account authentication and management, and so on. It also has a websocket API called a “firehose” (the subscribeRepos endpoint). The firehose streams all changes happening on a given PDS (from all repos) as a stream of “events”, where each event is an addition, edit, or deletion of a record in one of the repos, or some change related to an account, like handle change or deactivation.

One of the most important features of ATProto is that an account is not permanently assigned to a PDS. Unlike in ActivityPub, where if you sign up on mastodon.social, your identifier is bound to that hostname forever and it can never change, because everything uses it as the unique ID, here the unique ID is the DID. The PDS host is assigned to a user in the DID document JSON (e.g. on plc.directory), but you can migrate to a different PDS at any point, and at the moment there are even some fairly user-friendly tools available for doing that, like ATP Airport or PDS MOOver (although it’s still a bit unpolished at the moment, ~~and for now you can’t migrate back to Bluesky-hosted PDSes~~). In theory, you should even be able to migrate to a different PDS if your old PDS is dead or goes rogue, if you have prepared in advance (this is a bit more technical). If everything goes well, nobody even notices that anything has changed (you can’t even easily check in the app what PDS someone is on, although there are external tools for that, like internect.info).

Initially, during the limited beta in 2023, Bluesky only had one PDS, bsky.social. In November 2023, several additional PDSes were created (also under Bluesky PBC control) and existing users were quietly all spread to a random one of those. At that point, the network was already “technically federated”, operating in the target architecture, although with access restricted to only Bluesky-run servers. This restriction was lifted in February 2024 with the public federation launch.

Since then, ATProto enthusiasts started setting setting up PDS servers for themselves, either creating alt/test accounts there, or moving their main accounts. As of August 2025, there around 2000 third party PDS servers, although most of them are very small – usually hosting one person’s main and/or test accounts, and maybe those of a couple of their friends. I have a list of them on my website, and there’s also a more complete list here (mine excludes inactive PDSes and empty accounts).

As you can see there, there’s one massive PDS for Bridgy Fed, the Bluesky-Mastodon bridge service, hosting around 30-40k bridged accounts from the Fediverse, Threads, Nostr, Flipboard, or the web (blogs); then some number of small to medium PDSes for various services, and a very long tail of servers with single-digit number of accounts. At this moment, large public PDS in the style of Fedi instances aren’t much of a thing yet, although there are at least a few communities working on setting up one (e.g. Blacksky, Northsky, or Turtle Island). Blacksky specifically has opened up for migrations just last week and has now a few hundred real accounts.

The vast majority of PDSes at the moment use the reference implementation from Bluesky (written in TypeScript), but there are a few alternative implementations at various levels of maturity (Blacksky’s Rudy Fraser’s rsky written in Rust, cocoon in Go, or millipds in Python). The official version is very easy to set up and very cheap to run – it’s bundled in Docker, and there’s basically one script you need to run and answer a few questions.

As for the Bluesky-hosted PDSes, the number is currently in high double digits, and each of them hosts a few hundred thousands of accounts (!). And what’s more, they keep the record data in SQLite databases, one per account. And it works really well, go figure. The Bluesky PDSes are all given names of different kinds of mushrooms (like Amanita, Boletus or Shiitake), hence they are often called “mushroom servers”; you can see the full list e.g. here. bsky.social was left as a so-called “entryway server”, which handles shared authentication for all Bluesky-hosted PDSes (it’s a private piece of Bluesky PBC infrastructure that’s not open source and not needed for independent PDS hosters).

Relay

A relay is probably the piece of the ATProto architecture that’s most commonly misunderstood by people familiar with other networks like the Fediverse. It doesn’t help that both the Fediverse and Nostr also include servers called “relays”, but they serve a different purpose in each of them:

a relay in Nostr is a core piece of the architecture: your posts are uploaded to one or more relays that you have configured and are hosted there, where other users can fetch them from
a relay in the Fediverse is an optional helper service that redistributes posts from some number of instances who have opted in to others, in order to make content more discoverable e.g. on hashtag feeds

In ATProto, a relay is a server which combines the firehose streams from all PDSes it knows about into one massive stream that includes every change happening anywhere on the network. Such full-network firehose is then used as the input for many other services, like AppViews, labellers, or feed generators. It serves as a convenient streaming API to get e.g. all posts on the network to process them somehow, or all changes to accounts, or all content in general, from a single place.

Initially, the relay was also expected to keep a complete archive of all the data on the network, from all repos, from the beginning of time. This requirement was later removed in the updates late last year, at least partially triggered by the drastic increase in traffic in November 2024, which overwhelmed Bluesky’s and third party servers for at least a few days. Currently, Bluesky’s and other relays are generally “non-archival”, meaning that they live stream current events (+ a buffer of e.g. last 24 or 36 hours), but don’t keep a full archive of all repos (this change has massive lowered the resource requirements / cost of running a relay, making it much more accessible). An archival relay could always be set up too, but I’m not aware of any currently operating.

Bluesky operates one main relay at bsky.network, which is used as a data source for their AppView and pretty much everyone else in the ATProto ecosystem at the moment (internally, it’s really some kind of “load balancer” using the rainbow service, with a few real relay servers behind it).

The relay code is implemented in Go, and isn’t very hard to get up and running (especially the recent “1.1” update improved things quite a lot). Some people have been running alternative relay services privately for some time, and there is now e.g. a public relay run by Rudy Fraser at atproto.africa (with a custom implementation in Rust! 🦀), and a couple run by Phil @bad-example.com. I’m also running my own small relay, feeding content only from non-Bluesky PDSes.

Jetstream

There is also a variant of a relay called Jetstream – it’s a service that reads from a real CBOR relay and outputs a stream that’s JSON based, better organized, and much more lightweight (the full relay includes a lot of additional data that’s mostly used for cryptographic operations and other low-level stuff). For many simpler tools and services, it might make more sense to stream data from that one instead, if only to save bandwidth. (Bluesky runs a couple of instances listed there in the readme, but you can also run your own.)

AppView

The terribly named AppView is the second most important piece of the network after the PDS.

The AppView is basically an API server that serves processed data to client apps. It’s an equivalent of an API backend (with the databases behind it) that you’d find on a classic social media site like Twitter. AppView streams all new data written on the network from the relay, and saves a copy of it locally in a processed, aggregated and optimized form. For example, an AppView backed by an SQL database could have a posts table with a text column, a likes table storing all likes with a foreign key post_id, probably also an integer likes_count column in posts for optimization, and so on.

The AppView is designed to be able to easily give information such as:

the latest posts from this user
all the replies in a given thread organized in a tree
most recent posts on the network with the hashtag #rubylang or mentioning “iOS 26”
how many likes/reposts has a given post received, and who made them
how many follows/followers does a given user have, and who are they
is user A allowed to view or reply to a post from user B

All this data originates from users’ PDSes and has its original copy stored there, but the “raw” record don’t always allow you to access all information easily. For example, to find out how many likes a post has, you need to know all app.bsky.feed.like records referencing it from other users, and each of those like records is stored in the liking user’s repo on that user’s PDS. Same with followers, as I mentioned earlier in the section on records, or with building threads (again, different replies in one thread are hosted in different repos), or for basically any kind of search. So having this kind of API with processed data from the entire network is essential for client apps and various tools and services built around Bluesky by other people.

AppView also applies some additional rules to the data, sometimes overriding what people post into their PDSes, since anyone can technically post anything into their PDS. For example, the AppView prevents you from looking at the profiles of people who have blocked you, at least when you’re logged in. It also hides them from your followers list, even if they have a follow record referencing you, making it seem like they don’t; and if they try to make an app.bsky.feed.post replying to you (they can create such record on their PDS!), it excludes such reply from feeds and threads, as if it never happened. Same goes for “thread gates” which lock access to threads, and so on.

The AppView is one of the few components which aren’t completely open source. Initially, the AppView used Postgres as its data store; that version is still in the public repository. In late 2023, Bluesky has migrated to a “v2” version, which uses the NoSQL database ScyllaDB instead, to be able to handle the massive read traffic from many millions of concurrent users. The upper layer with the “business logic” is kept in the public repository, while the so called “dataplane” layer that interacts directly with Scylla is not. The reason is mostly that it’s built for a specific hardware setup they have and wouldn’t be directly usable by others, while it would add some unnecesary work for the team to publish it. It’s still possible to run the AppView with the old Postgres-based data layer (and I think the team uses that internally for development), it just can’t handle as much traffic as the current live version.

This is the piece that’s hardest to run yourself, and one that requires the most resources. That said, a private AppView should be possible to run right now for under $200/month – the biggest requirement is at least a few TB of disk space. The truly costly part is not collecting and storing all this data, but serving it to a huge number of users who would use it as a backend for the client app in daily use. An alternative full-network Bluesky AppView that is used by a few thousands of users shouldn’t be very hard to run, but to be able to serve millions, you’ll need a lot of hardware and something more custom than the Postgres-based version.

There have also been some attempts at alternative implementations – the most advanced right now is AppViewLite, built in C#, which goes to great lengths to minimize the resource use.

CDN

A part of the AppView (at least the Bluesky one) is also a CDN for serving images & videos. The API responses from e.g. getTimeline or getPostThread generally include links to any media on the Bluesky CDN hostname, not directly on the PDS, even though you can fetch every blob from the PDS, since that’s the “source of truth” (although IIRC the Bluesky PDS implementation doesn’t set the CORS headers there). It’s recommended to access any media this way in order to not use too much bandwidth from the PDS.

Labellers

(Or “labelers” officially, but I like the British spelling more here, sue me ¯\_(ツ)_/¯)

We’re now getting to more Bluesky specific things (i.e. specific for the Bluesky-service, although some parts of it are ATProto-general and mentioned on the atproto.com site).

A labeller is a moderation service for Bluesky (or other ATProto app), which can be run by third parties. Labellers emit labels, which are assigned to an account or a record (like a post). Each labeller defines its own set of labels, depending on what it’s focusing on; then, users can “subscribe” to a labeller and choose how they want to handle the labels it assigns: you can hide the labelled posts/users, mark them with a warning badge, or ignore given label.

Labellers were initially designed to just do community moderation of unwanted content, e.g. you can have a service focused on fighting racism, transphobia, or right-wing extremism, and that service helps protect its users from some kinds of bad actors; or you can have one marking e.g. posts with political content, users who follow 20k accounts, or who post way too many hashtags. In practice, many existing labellers are meant for self-labelling instead, letting you assign e.g. a country flag or some fun things like a D&D character class to yourself.

The way it works technically is:

a labeller either runs a firehose client pulling posts from the relay, or relies on reports from users and/or its operating team (usually using the Ozone tool for that)
labels, which are lightweight objects (not ATProto records) are emitted from labeller’s special firehose stream (the subscribeLabels endpoint)
the AppView listens to the label firehoses of all labellers it knows about, in addition to the relay stream, and records all received labels in its database
when a logged in user pulls data like threads or timelines from the AppView, it adds relevant label info to the responses depending on which labellers the user follows
the specific list of labellers whose labels should be applied is passed explicitly in API requests in the atproto-accept-labelers header (there is a “soft” limit of 20 labellers you can pass at a time, which is why the official app won’t let you subscribe to more)
in the official app, Bluesky’s official moderation service (which is “just” another labeller) is hardcoded as one of those 20 and you can’t turn it off; when connecting from your own app or tool, you’re free to ignore it if you want

(Read more about labellers here.)

Feed generators

Custom feeds are one of the coolest features of Bluesky. They let you create any kind of feed using any algorithm and let everyone on the platform use it (even as the default feed, if they want to).

The way this system works is that you need to run a “feed generator” service on your server. In that service, you expose an API that the AppView can call, which returns a list of post at:// URIs selected by you however you want in response to a given request.

A minimal feed service can be pretty simple – the API is just three endpoints, two of which are static, and the third returns the post URIs. One “small” problem is that in order to return the post URIs, you need to have some info about posts stored up front, which in practice means that you almost always need to connect to a relay’s firehose stream and store some post data (of selected or all posts, depending on your use case).

The flow is like this:

a feed record is uploaded to your repo, including metadata and location of the feed generator service, which lets other users find your feed
when the user opens that feed in the app, the AppView makes a request to your service on their behalf
your service looks at the request params and headers, and returns a list of posts it selected in the form of at:// URIs
the AppView takes those URIs and maps them to full posts (so-called “hydration”), which it returns to the user’s app

How exactly those posts are selected to be returned in the given request is completely up to you, the only requirement is that these are posts that the AppView will have in its database, since you only send URIs, not actual post data. In most cases, feeds use some kind of keyword/regexp matching and chronological ordering, but you can even build very complex, AI-driven algorithmic “For You” style personalized feeds.

You don’t necessarily have to code a feed service yourself and host it in order to have a custom feed – there are a few feed hosting services that don’t require technical knowledge to use, like SkyFeed or Graze.

Client apps

Ok, that’s technically not a server, but stay with me…

The final piece that you need to fully enjoy Bluesky is the client app – a mobile/desktop one or a web frontend. Unlike on Fedi, where an instance software like Mastodon usually includes a built-in web frontend that is your main interface for accessing the service, the PDS doesn’t include anything like that, just a database and an API (which also means it’s much more lightweight and needs less resources). All browsing is done through a separate client, and the client always does everything through the public API – kind of like when you run a custom web client for Mastodon like Elk or Phanpy, you connect it to your instance, and you view your timeline on elk.zone.

So when you go to bsky.app, that’s what you’re seeing – a web client that connects to your PDS (Bluesky-hosted or self-hosted) through the public API, no more, no less. The official app is built for both mobile platforms and for the web from a single React Native codebase (apparently React Native on the web and normal web React is not the same thing 🧐). This has allowed the still very small frontend team (and IIRC at first it was literally just Paul) to build the app for three platforms in any reasonable amount of time and maintain it going forward. The downside is that it’s kinda neither a great webapp nor a great mobile app… But the team is doing what they can to improve it, and it’s already much better than it used to be, and tbh more than good enough for me.

There aren’t nearly as many alternative clients as there are for Mastodon, and none of them are really great, but there are a few options; see the apps part of my Bluesky Guide blog post for links.

DMs

Notice that I haven’t mentioned DMs anywhere – that’s because they aren’t a part of the protocol at the moment. The Bluesky team wants to eventually add some properly implemented, end-to-end encrypted, secure DMs using some open standard, but they won’t be able to finish that in the short term, and a lot of people were asking for at least some simple version of DMs in the app. So they’ve decided as an interim solution to implement them as a fully centralized, closed source service. It is accessible to third-party Bluesky clients through the API (the chat.bsky.* namespace), but it’s not something you can run yourself. The team is very open about the fact that it’s not a proper replacement for something like Signal, and that for sensitive communication, you should ideally just use it for swapping contacts on Signal on iMessage and move the conversation there. They also kinda don’t want to spend too much time adding features there, because it’s considered a temporary solution, so it’s pretty basic in terms of available features.

There are also a few other closed-source helper services, like the “cardyb” they use for generating link card details, or the video service for preprocessing videos, but they’re all specific to some Bluesky use cases only and not strictly necessary to use.

How it all fits together

So the flow and hierarchy is like this:

the client app you use creates new records as a result of actions you take (new posts, likes, follows), and saves them into your PDS
your PDS emits events on its firehose with the record details
Bluesky relay and other relays are connected to the firehoses of each PDS they know about (your PDS generally needs to ask them to connect using the PDS_CRAWLERS ENV variable), and they pass those events to their output firehose
the Bluesky AppView (and other AppViews) listen to the firehose of their selected relay (though it could be multiple relays, or it could even just stream directly from PDSes, but in practice this will normally be one trusted relay)
the AppView gets events including your records, and if they are relevant, saves the data to its internal database in some appropriate representations
when other users browse Bluesky in their client apps, they load timelines, feeds and threads from the AppView, which returns info about your post from that database it saved it to

Additionally:

feed generators run by third party feed operators also stream data from Bluesky’s or some other relay and save it locally, so they can respond to feed requests from the AppView
labellers also stream data from Bluesky’s or some other relay, and emit labels on their firehoses, which get sent to the AppView (note: there is no official “labeller relay” sitting between labellers and the AppView, although one third party dev wrote one)

Note:

PDSes do not connect to each other directly, and they don’t store posts of users from other PDSes, only their own
although right now basically everyone uses the Bluesky relay and AppView, anyone can set up their own alternative relays and AppViews, which feed from all or any subset of known PDSes
PDS chooses which relays to ask to connect, but relays can also connect by themselves to a PDS or another relay; AppView chooses which relay(s) it streams data from; and PDS chooses which AppView it loads timelines & threads from
it’s absolutely possible and expected that two users using different PDSes, which use separate AppViews feeding from separate relays will be able to talk to each other and see each other’s responses on their own AppView, as long as the users aren’t banned on the other user’s infrastructure

The metaphor that’s often used to describe these relationship is that PDSes are like websites which publish some blog posts, and relays & AppViews are like search engines which crawl and index the web, and then let you look up results in them. In most cases, a website should be indexed and visible in all/most available search engines.

Where to go next

And that’s about it – I think with the above, you should have a pretty good grasp of the big picture of ATProto architecture and all the specific parts of it. Now, if you want to start playing with the protocol and building some things on it, a lot will depend on what specifically you want to build and using what languages/technologies:

SDKs:

Two languages are officially supported by Bluesky:

JavaScript/TypeScript, in which most of their code is written (see the packages folder in the atproto repo)
Go, which is used in some backend pieces like the relay, or the goat command line tool used e.g. for PDS migrations (see the indigo repo)

For Python, there is a pretty full-featured SDK created by Marshal, which is the only third party SDK officially endorsed by the Bluesky team.

For other languages, I have a website called sdk.blue, which lists all libraries and SDKs I know about, grouped by language. As you can see, there is something there for most major languages; I’ve built and maintain a group of Ruby gems myself. If you want to use a language that doesn’t have any libraries yet, it’s really not that hard to make one from scratch – for most things you just need an HTTP client and a JSON parser, and maybe a websocket client.

Docs:

There is quite a lot of official documentation, although it’s a bit spread out and sometimes not easy to find.

The places to look in are:

atproto.com – the official AT Protocol website; a bit more formal documentation about the elements of the protocol, kind of like what I did here, but with much more info and detailed specifications of each thing
docs.bsky.app – more practical documentation with guides and examples of specific use cases in TS & Python (roll down the sections in the sidebar); it shows examples of how to make a post, upload a video, how to connect to the firehose, how to make a custom feed, etc.
docs.bsky.app/blog – developer blog with updates about protocol changes
HTTP reference – a reference of all the API endpoints
something that I also find useful is to have the atproto repo checked out locally and opened in the editor, and look things up in the JSON files from the /lexicons folder

And a few other articles that might work better for you:

“ATProto for distributed systems engineers”, Bluesky’s technical overview of the server and data flow architecture
“ATProto Ethos”, also on the Bluesky blog, based on a conference talk
“What the hell is the atmosphere anyway: A slightly less technical intro to the technical side of Bluesky”, by Bailey Townsend (Sep 2025)
“Open Social” – a high-level overview of how ATProto brings back the openness of the original pre Web 2.0 web, by Dan Abramov (Sep 2025)
“Where It’s at://” – a well written guide to AT URIs and DIDs, by Dan Abramov (Oct 2025)
the “Statusphere” app example on atproto.com

Community:

Someone said recently that “bsky replies are the only real documentation for ATProto”, and honestly, they’re not wrong. We have a great community of third party developers now, building their own tools, apps, libraries, services, even organizing conferences. If you’re starting out and you have any questions, just ask and someone will probably help, and some of the Bluesky team developers are also very active in Bluesky threads, answering questions and clarifying things. So a lot of such knowledge that’s not necessarily found in the official docs can be found somewhere on Bluesky.

The two places I recommend looking at are:

the “ATProto Touchers” Discord chat – ping me or some other developer for an invite :)
my ATProto feed on Bluesky, which tries to catch any ATProto development discussions – it should include posts with any mention of “ATProto” or things like “AppView” or various API names and technical terms, or you can use #atproto or #atdev hashtag to be sure

Also, there’s a fantastic newsletter called Connected Places (formerly Fediverse Report) by Laurens Hof, who publishes two separate editions every week, about what’s happening in Bluesky/ATProto and in the Fediverse (and *a lot* of things are happening).

Ideas:

Some easy ways to start tinkering:

use one of the existing libraries for your favorite language and make a website or command-line tool which loads some data from the AppView or PDS: load and print timelines, calculate statistics, browse contents of PDSes and repos, etc.
make a bot that posts something (not spammy!)
make a simple custom feed service using one of the available templates
connect to the relay firehose and print or record some specific types of data

Tools:

And a couple of tools which will certainly be useful in development:

internect.info – look up an account by handle/DID and see details like assigned PDS or handle history
PDSls – PDS and repository browser, lets you look up repos by account DID or records by at:// URI (there are a few others, but this one is most popular)

Changelog:

15 Oct 2025:

added link to Dan’s AT URI guide

26 Sep 2025:

you can now migrate back to Bluesky’s PDSes
added links to Bailey Townsend’s and Dan Abramov’s blog posts
some small corrections

Social media update 2025

2025-06-30T14:43:43Z

So here we are, halfway through 2025, a bit over 2.5 years after the Eloncalypse… For better or worse, the Twitter as we knew it in the 2010s and the communities we had there are mostly gone. But it doesn’t feel like we’ve all settled on anything comparable.

If you’re a software developer who was active on Twitter before, by now you’ve almost certainly tried at least one of the alternatives – Mastodon, Bluesky, and Threads, and you’re probably posting actively on at least one of these, but probably not on all of them. The problem is that nobody has enough mental space to be active on 3-4 similar social networks, so we’ve split into different camps which only partially overlap. You’re probably still missing some friends from Twitter and some interesting content. It’s all a bit in flux and a bit of a mess.

Myself, I’ve basically left Twitter; I haven’t spent much time on Threads (among other reasons, it was unavailable in Europe for a long time); and I’m mostly hanging out on Bluesky and somewhat on Mastodon.

So where do we go from here?

Obviously everyone has their own take on that, this is just mine. But I really think we should all try to make an effort to focus on the widely understood “open social”, or what Laurens Hof from Fediverse Report now calls “Connected places”. That means Bluesky and Mastodon/Fediverse (with emphasis on “and”), and to some degree maybe also Threads, although that depends on how their integration with ActivityPub progresses (and it’s looking more and more like they aren’t very serious about it).

My advice:

→ If you’re currently cross-posting or bridging between Mastodon and Bluesky: awesome! ❤️

→ If you’re active on Mastodon, but currently ignoring or forgot about Bluesky: please reconsider it. I know that these two communities have a lot of differences between them, and we love to hate each other (I fully admit I’m guilty of that myself). It’s likely you prefer one or the other of these for various reasons, and you might not be a fan of the other one. But I think it’s clear at this point that none of them will disappear in the near-term at least or replace the other for everyone.

It would be great if we all made some effort to connect to the other side, for those who like it more there. What are the options? Depending on what’s more convenient to you:

there are some native apps which let you post to two or more services in parallel, e.g. Croissant, Openvibe or SoraSNS
most social media management services like Buffer now support both Fediverse and Bluesky, so you can use that to post to both, including scheduling etc. There are several others like this, and they usually have some free plans.
- e.g. Fedica was one of the ones that had support for Bluesky from very early on
- also my friend from my first job, Peter Solnica (known from some Ruby libraries like DataMapper/ROM, dry-rb, Hanami, and now some Elixir libs too) is building his own called JustCrossPost
I use a little tool in Ruby I wrote for myself named tootify, which lets me selectively cross-post relevant posts to Mastodon, almost effortlessly: I post on Bluesky and then “like” my own post if I want it to be copied to Mastodon (which clears the like). So this way I can cross-post e.g. cat photos or iOS related posts, but skip Bluesky-specific content.
There are probably similar tools going in the other direction, although it’s a bit more complicated this way because of the post length limits (usually 500 on Mastodon vs. 300 on Bluesky).
I know some people have also written some iOS Shortcuts, scripts, browser extensions etc. (I don’t have any links at hand)
and last but not least, there’s Bridgy Fed: basically enable it once by following the bridge account, and you can forget about it. It creates a “mirror” account of yours on the other side, but when people interact with it there, the likes/reposts/comments go back to you (as long as that other person also has the bridge enabled).
there are probably other options too, let me know in the comments :)

→ If you’re active on Bluesky: wonderful! ☺️ But again, all of the above applies. Don’t forget about the friends and strangers who prefer the elephant site 🦣. At the very least, enable the Bridgy bridge.

→ If you do have both Mastodon and Bluesky accounts, but you’ve decided that you want to use them for different kind of content (e.g. tech vs. non-tech)… please reconsider, in light of what I wrote above. Most of the people who know you online would probably prefer to follow you in one or the other place they like more, not to have to follow you everywhere in parallel. (Though nobody says you can’t have e.g. two different accounts which are both bridged.)

→ If you had a bridged account, but turned off the bridge because you prefer to be posting there directly, but you don’t really post there directly (you know who you are 😛) – I am begging you, please either figure out some cross-posting solution (see above), or enable the bridge 🙏🏻

→ If you’re mostly active on Threads (is that a thing?…) – turn on the fediverse sharing option (it might not be available in the EU though, according to the support article?), and follow the Bridgy account to enable bridging to Bluesky (there aren’t many accounts connected like this, but it should work, let me know if you have any problems).

→ If you’re still mostly active on Twitter (I see you 👀 and I am kinda judging you)… please rethink it. I mean… you really don’t mind helping Elon and his buddies? I know, there’s more content there, more engagement (maybe), big accounts are still there, news is still there, more people talking there about startups, AI, indie dev or whatever. But wouldn’t you want to change that? Wouldn’t you prefer to use and build on a network with an open API that isn’t controlled by one rich American far-right guy1) who thinks he’s the president of the world?… Where you don’t see a full screen ad every few posts, and don’t need to pay a fuckton of dollars to build some fun tool on it? We need to make an effort to move away from there. Someone’s gotta start, and then maybe others will come.

→ If you’re posting both on Twitter and on Mastodon/Bluesky, then, well… it’s ok I guess 🙃 I think the most important thing is to let the people who do want to move away from Twitter completely, have the content they want to follow in the new place. That’s the first step. A natural second step is then to start decreasing the amount of content that there is on Twitter, so people have more incentive to look for it elsewhere, but I understand if not everyone is ready for that step yet.

→ If you tried Mastodon and/or Bluesky before, but you felt like it was too empty there, you didn’t have enough content to read or you felt like you were shouting into the void – please give it another try, and please give it some time. Twitter also wasn’t immediately the place you remember from the first day you signed up, was it? You need to put in some effort, like you did everywhere else. Some tips:

on Bluesky: find some good custom feeds and/or starter packs to follow
on Mastodon: follow some hashtags, and use hashtags when posting to get more reach (but within reason!). On a private instance, this gets a bit more tricky due to the ActivityPub architecture, so it might make sense to start on a larger one at first.
on both: try to find some people you recognize from Twitter, and then look who they follow or repost, and recursively look through their profiles too. Also, interact with people, give likes/faves, good replies, and so on.

→ If you’re on Nostr, there are some kind of Nostr ↔ Fedi bridges or gateways, and you can use those + Bridgy to reach Bluesky too (e.g. here’s a Nostr account “double-bridged” to Bluesky).

→ If you’ve moved to something like Micro.blog, or just blogging – that’s also cool! But I hope you’re somehow posting the links to Bluesky & Fedi too :)

→ If you’ve just given up on microblogging or social media in general… I understand. It’s probably not a bad choice in the current times. I hope we somehow meet again someday, digitally or in person 🩵

So let’s connect, let’s build bridges. But also, let’s finally help the X-shaped zombie die 🧟‍♂️

(You can find me on Bluesky at @mackuba.eu (I have my private PDS at lab.martianbase.net), which is my main account these days, and on Mastodon at mackuba@martianbase.net (also a private instance), where I’m cross-posting a good chunk of the posts from Bluesky using Tootify. If you want to see everything including some shitposting, politics and ATProto-specific posts, the Bluesky account is also bridged as mackuba.eu@bsky.brid.gy. Twitter account @kuba_suder is left as an archive, because I don’t like deleting useful content from the Internet, but I don’t use it anymore. Lately I’ve been also blogging somewhat more regularly than here on my new “journal” Micro.blog.)

1) If you now want to write a comment mentioning someone with the initials “J.D.”, don’t even think about it! 🫠

Micro.blog journal

2025-02-04T16:00:05Z

Update 17.11.2025: I’ve migrated this journal blog now from Micro.blog to Leaflet, a new blogging service built on top of Bluesky’s ATProto. I wrote about this here, the new URL is https://lab.mackuba.eu (I’ll add a redirect from ‘journal’ later).

Just a quick update, if you’re following this blog via RSS: I’ve started a separate “journal” blog on micro.blog: journal.mackuba.eu.

Micro.blog is an interesting service: it’s a one-man indie business that’s sort of a hybrid between a blogging platform and a microblogging social network. You can write anything between full-size blog posts and tweet-sized single messages, and you can cross-post them to Bluesky, Mastodon etc. You can also follow people from the community that’s formed there and reply to them, all in the form of those mini-blogposts (there are no likes or retweets though). The idea, as I understand, is to use a network of blogs to build a social network that uses the web itself as the foundation.

I’m not really planning to use it in this social network mode, since I’m pretty happy now posting on Bluesky and to limited degree on Mastodon (I’ve completely stopped posting on Twitter at this point, since last autumn, when Elon started openly supporting Trump). I’m also not completely sold on this “web as a social network” idea. And I don’t intend it to replace this blog here either – I will still be (very) occasionally posting those super long articles here like the one about NSButtons or the guide to Bluesky.

But I’ve felt the need for a while to have a place to post something in between those – not full blog, and not a micro blog, but a “mediumblog” so to say (not to be confused with a Medium blog) – like this post, for example. Something where I can sometimes post my thoughts more easily, when I want to write something that doesn’t really fit in a few skeets/toots, with less effort required to start and finish it. This seems like it could work for that.

It’s also nice that it’s supposed to sync replies from Bluesky/Mastodon under the posted link back to the blog page as comments below (I’ll try to implement the same thing here). I also have it configured with my own domain, so I can possibly migrate it to something self-hosted like Jekyll or Hugo at some point, keeping all the links and content.

For now, I’ve posted two updates about what I’ve been working on recently:

about tuning a Postgres database to which I’m trying to migrate my Bluesky feeds service
and a review of all I’ve done in 2024

I don’t know how often I will end up posting there, I don’t want to pressure myself, just to have a place to post when I have a need. So if you’re curious, follow me there via RSS (or on Bluesky or Mastodon).

March 2024 projects update

2024-03-27T01:14:35Z

I’ve been still pretty busy with various Bluesky- and social-related projects recently, so here’s a small update on what I’ve been working on since my November post, if you’re interested:

Skythread – quote & hashtag search

I was missing one useful feature that’s still not available on Bluesky: being able to see the number of quote posts a post has received and looking up the list of those quote posts. The Bluesky AppView doesn’t currently collect and expose this info, so it’s not a simple matter of calling the API. But since everything’s open, anyone can build a service that does this, they just need to collect the data themselves.

Since I’m already recording all recent posts in a database for the purposes of feeds and other tools, I figured I could just add an indexed quote_id column and set it to reference the source post on all incoming posts that are quotes, and later look up the quotes using that field.

Skythread, my thread reading tool, seemed like a good place to add a UI for this. When you look up a thread there, it now makes a call to a private endpoint on my server which returns the number of quotes of the root post, and if there are any, it shows an appropriate link below the post. The link leads you to another page that lists the quotes in a reverse-chronological order, like this (it doesn’t currently do pagination though). You can open that page directly by appending the bsky.app URL of a post after the quotes= parameter here: https://blue.mackuba.eu/skythread/?quotes=.

In the same way, I also indexed posts including hashtags, since hashtags were being written into post records since the autumn, but it wasn’t possible to search for them in the app. However, this has now been added to the Bluesky app and search service, so you don’t need to use Skythread for that. I hope that the quote search also won’t be needed for much longer :)

Handles directory

One very cool feature of Bluesky is that you can verify the authenticity of your account by yourself, by proving that you own the domain name that you’ve used as your handle. So for official accounts like The New York Times, The Washington Post, or Alexandria Ocasio-Cortez, it’s enough if they just set their handle to their main website domain (or a subdomain of house.gov in AOC’s case) to prove they’re legit – they don’t need to apply anywhere to get a blue or gold tick on their profile.

I was thinking one day that it would be nice to see how many e.g. .gov handles there are and notice easily when new ones show up. So I grabbed a list of all custom handes from the plc.directory and started recording new and updated ones from the firehose.

In the end, I decided to build a whole catalog of all custom handles, grouped by TLD, and show which TLDs are the most popular. At first I only included the “traditional” main TLDs and country domains, but a lot of people liked it and I got a lot of requests to also include domains like .art, .blue, .xyz and so on, so in the next update I’ve added all other domains too. (I gave it an old-school tables-based design as a homage to the old “web directory” websites like Yahoo Directory 😉)

Apart from handles, the website now also tracks third party PDS servers that started to show up after the federation launch in February.

Bluesky activity charts

I’ve also made a page that shows some charts tracking Bluesky user activity – the number of daily posts and unique users that have posted in a given day. The activity has been gradually falling since October until February, then there was a huge spike when Bluesky opened up for registrations without an invite (when Japan suddenly took over), and then it’s been falling down again since then (currently around the level of the October top).

You can also see some other interesting stats on Jaz’s page and Eric Davis’s Munin charts, especially the one tracking daily/weekly/monthly active user count. (I also have a few more ideas for what to add to my charts.)

DIDKit

In the last few weeks, I’ve been updating the code that tracks custom handles again to adapt to some protocol changes. The #handle event in the firehose, which included handle info on every handle change, is now deprecated and being replaced with a new #identity event, which only tells you to go fetch the account info from the source again (source being usually plc.directory).

At the same time, I also implemented validation of custom handles – clients and services that display handles are supposed to verify the handle reference in both directions themselves, because some accounts may have handles in the PLC registry assigned to domains that they don’t actually own or which don’t exist (the Bluesky official app shows such accounts with an “⚠ Invalid Handle” label, which you’ve probably seen before). For example, the handles directory page initially listed an amongus.gov account under .gov TLD, which was loaded from plc.directory, but is not in fact a real domain.

This should ideally be done by not relying on Bluesky servers, and instead checking the DNS TXT entry and the .well-known URL of a given domain manually. There’s a bunch of pretty generic logic there that will be needed in most projects that need to convert between DIDs and handles, so I extracted it to another Ruby gem named DIDKit, which lets you do things like:

get the DID of an account with a given handle
load the DID JSON document, which includes info like assigned handle(s) or hosting PDS server
check if any of the assigned handles from the document resolve back to the same DID
fetch all updates to all DIDs in batches from the PLC directory

mackuba ∕ didkit

A library for handling DID identifiers used in Bluesky AT Protocol

Skyfall

I’ve also been making some minor updates to my Skyfall library for streaming data from the Bluesky relay firehose.

One thing I’ve been trying to fix is a rare but annoying issue with the websocket connection getting stuck. From time to time, it manages to get into a state where no data is coming, but the connection doesn’t time out and just waits for new packets for hours, until I notice it and restart it. It isn’t only happening to me, others have mentioned it too (and not only in Ruby code); but it happens rarely enough that it’s really hard to debug.

My proposed fix is adding a “heartbeat” timer, which runs with some interval like every 30 seconds, and checks if there have been any new packets in some period of time; if there haven’t been any in a while, then it will forcefully restart the connection. (This isn’t included in the latest release yet, I’m waiting for it to get triggered a few times first.)

Another thing I’ve added is being able to connect to a new kind of firehose exposed by “labellers” a.k.a. moderation services. Bluesky has released this new important piece of the federated architecture earlier this month – third party developers and communities can now set up independent moderation services, which manually or automatically add various “labels” to accounts or specific posts, flagging them e.g. as “racism” or “disinformation”. Anyone can subscribe to any labellers they choose, and they’ll see the labels from those selected services shown in the app. The new firehose (the subscribeLabels endpoint) allows you to connect to a specific labeller and stream all new labels that it’s adding.

I’m also tracking all new registered labeller services and keeping a list here (it’s not curated, just a dump from a database table, so it also includes various test servers etc.).

mackuba ∕ skyfall

A Ruby gem for streaming data from the Bluesky/AtProto firehose

The “Bluesky guide”

Last month I wrote a long blog post titled “Complete guide to Bluesky”, where I included various info and tips for beginners about Bluesky history, available apps, handles, custom feeds, privacy, or currently missing features. I’m now updating it every time Bluesky releases another big feature :) Check it out if you’ve missed it.

I have ideas for a few more Bluesky introduction posts with a developer focus – a general intro to the protocol and architecture, and about working with the XRPC API and the firehose. I hope I’ll be able to find time for that in the next few months.

Tootify – cross-posting to Mastodon

I still want to finish my Mac app for cross-posting to Twitter, Mastodon and Bluesky one day, but it’s a lot of work and I’ve got too many different things in progress at the same time, so it’s moving at a glacial pace… In the meantime, I started thinking if I could maybe quickly build something much simpler that also does the job. I’ve been mainly hanging out on Bluesky in recent months and posting on Mastodon only occasionally, because having to copy-paste things from one tab to another is annoying, especially if images and alt text are involved. But the folks I know from Twitter still mostly follow me on Twitter and Mastodon only and aren’t coming to Bluesky.

I also didn’t want to simply copy every single post from here to there, because a lot of things I post on Bluesky are specifically about Bluesky stuff, so it doesn’t always make sense to post them to Mastodon – I only want some selected ones to be copied. But at the same time, I wanted to minimize the amount of friction this would add.

So the idea I had one night was that I could mark the Bluesky posts to be copied to Mastodon by simply “liking” my own posts that I want copied; a service or a cron job would then periodically look at the list of my recent likes, and when it notices one made on my own post, it would copy that post to Mastodon (and remove the like).

I managed to build it in about a day and a half, complete with image support with alt text and copying of quote-posts as posts with plain links. It’s now running happily on a Raspberry Pi on my local network 😎

The code is published here, if you’re interested – but it’s a bit of a proof of concept at the moment, just enough to make it work for myself, so it’s probably not very user-friendly. But maybe I’ll build it up into something bigger if people find it useful. (Just to clarify, this is meant to be a one-way sync by design – syncing in the other direction would be harder for various reasons, e.g. because of the complex “facets” system that Bluesky uses for post record data, and because Mastodon’s post length limit is higher than on Bluesky.)

mackuba ∕ tootify

Toot toooooooot

And One More Thing ;)

Paul Frazee, Bluesky’s lead dev, has a lovely cat named Kit and often posts photos of her. I’m a big fan of Kit, so I made a feed named the Kit Feed, which only includes posts with these photos 🙂 Like and subscribe! 🐱

A complete guide to Bluesky 🦋

2024-02-21T18:05:12Z

(Last update: 18 Nov 2025.)

For the past year and a half, I’ve been a pretty active user of Bluesky. I enjoy it a lot, and I’ve managed to learn a lot about how it works, what works well and what doesn’t, and also what’s likely coming next.

I’ve decided to write down some of the tips & tricks that I often give to friends when I invite them there, or the advice and answers that I sometimes give to people that I find in some feed asking about things.

This of course got much longer than I planned 😅 so if only have a moment, here’s a TLDR:

there are official iOS and Android apps, but you can also use bsky.app in the browser, or try e.g. Skeets (iOS), Skywalker (Android), or deck.blue (multi-column webapp)
tweak the algorithm in your “Discover” feed by opening the “…” context menu on a post in that feed and selecting “Show more like this” or “Show less like this”; or, if you prefer a classic chronological feed, you can set the Following feed as your main feed and remove Discover
if your timeline feels empty, you can find some people to follow through “starter packs”, or you can go to the “Feeds” tab, scroll down to the “Discover New Feeds” section and look for some feeds on the topics that interest you (on the top list or in the search); follow these feeds, and then if you find some interesting people posting in those feeds, follow them too. You can also search for feeds on goodfeeds.co.
don’t be afraid to interact with people, repost good posts, like good comments, comment in threads and so on – that’s how you make friends! (but be nice :)
if you see too much NSFW stuff, look for “Content filters” settings in the Moderation tab in Settings
everything you post here is very public, so don’t share anything too private 😏
if you own some cool domain name like “taylorswift.com”, you can set it as your handle
bookmarks, trends, thread composer, pinned posts, videos, GIFs and DMs (simple version) are now available
2FA and more DM stuff are coming, post editing is planned; some version of private posts shared to limited audience is probably coming at some point, but not in near future
Jack Dorsey has nothing to do with Bluesky anymore ;)

And now the long version:

What is Bluesky?
Apps
Feeds & algorithms
Safety & moderation
Privacy of your data
Account security
Handles & IDs
How are things called here?
What is this federation thing?
Search
Hashtags
Video & GIFs
Starter packs
Trending topics
Bookmarks
Settings
Missing features
Other tools

What is Bluesky?

(A bit of history, skip if you’re not interested :)

Bluesky is a project started originally by Twitter (now an independent company), whose goal is to create a decentralized Twitter-like social network, or more generally, a platform for building various decentralized social networks.

The project was started in Dec 2019 by Jack Dorsey, former Twitter CEO. The basic idea was to design a protocol on which you could build something that would work like Twitter, but which would not be under the control of a single company that makes unilateral decisions about everything on it. It would be more like web and email, which are open standards that anyone can build on – any company can set up an email service or write an email app, and anyone can sign up for an account and start sending emails. There’s no one central authority on the Internet that can ban you from email altogether.

Such network would consist of many servers owned by different companies and people connecting together, and the idea was that eventually, Twitter itself could become a part of that network, as just one of its elements.

(If this all sounds a lot like the Mastodon social network, or “the Fediverse”, then you’re right – there are a lot of similarities between these two. However, Bluesky is built on a completely different system they’ve designed from scratch, called the AT Protocol or ATProto. They’re hoping that this will let them build some things better than they are done in Mastodon, making the network less confusing, more useful and more user-friendly. Bluesky does not directly connect with Mastodon servers and apps, although there are some unofficial ways to connect the two worlds.)

After an initial research phase, in 2021 a team was chosen to build the platform and the Bluesky company was formally created. A woman named Jay Graber, formerly a developer at Zcash, was chosen as the CEO. Thankfully, Jay had the foresight at that point to insist that they’d set it up as an independent company, which was funded, but not controlled by Twitter. Had they not, it almost certainly would have been shut down last year after Elon’s Twitter takeover.

The team has been working on designing and building the pieces of the system throughout 2022, and in February 2023 they’ve launched a very early and rough beta and started slowly letting in some users who wanted to try it out and have signed up on a waitlist. However, the whole Elon thing happened in the meantime and that was a moment when everyone was looking for a Twitter alternative, so the interest has wildly exceeded expectations and they weren’t ready yet to take in everyone.

Since then, the user base has been gradually growing, with people being let in from the waitlist and existing users inviting their friends using invite codes. Meanwhile, the team had to speed some things up to adapt to the new situation and has been working hard on adding the most important features, and building up the backend to allow for more and more traffic. Finally, almost a year later, in February 2024 Bluesky has opened up for registrations from everyone.

The Bluesky company

Bluesky is still a fairly small team at the moment. The dev team is probably something like a dozen people altogether, and that’s for the frontend, backend, protocol, servers and so on. So they just can’t add new features as fast as they’d like to, but they’re doing what they can.

The team members interact with people on the platform all the time, answering questions and just having fun in general. They’re also building almost everything in public – the source code of the app and servers is available on GitHub, so we can track in real time what they’re working on next, report bugs and sometimes submit code with some new features they can merge in.

The company is set up as a “public benefit corporation”, which basically means (in my non-US layman understanding) that it is a business and it’s meant to make profit, but that profit is not it’s only and main goal. It can and should have other, more noble goals that benefit the public, as the term implies, in this case: creating a protocol for decentralized social apps that everyone can build on.

Bluesky isn’t really making any money at the moment (other than a small domain reselling service). The general plan is that, rather than the standard route of eventually putting ads everywhere and selling user data, they will resist “enshittifying” the platform and will instead add some optional premium plans and services, but in such a way that wouldn’t change the social dynamics of the platform:

Bluesky will always be free to use — we believe that information and conversation should be easily accessible, not locked down. We won’t uprank accounts simply because they’re subscribing to a paid tier.

The first planned step is a “Discord-like” subscription, which was planned for the end of 2024 / beginning of 2025, but was delayed because of the huge influx of new users that happened in November. More long term, they were also talking about coming up with some ways of letting creators and devs on the platform earn some money from their followers, with Bluesky taking some commision from the payments.

In any case, they’re explicitly building the network to be resilient even in the unlikely scenario that they themselves “turn evil” in the future – the network is meant to be “billionaire-proof”, impossible to completely take over by one guy with too much money. To quote the lead dev:

“Our culture doc includes the phrase “The company is a future adversary” to remind us that we won’t always be at the helm – or at our best – and that we should always give people a safe exit from our company. It’s weird at times to frame our priorities as protecting users from us, but that’s exactly what we’re trying to do.

The Bluesky team is made up of users. None of us come from big tech companies. We all came together because we were frustrated by the experience of feeling helpless about how our online communities were being run. We don’t want to give that same feeling to other people now that we’re the builders.

When we build an open protocol, we’re giving out the building blocks. We want to start from the premise that we’re not always right or best, that when we are right or best then it might not last, and that communities should be empowered to build away from us. Sometimes this can all feel very intangible and abstract, and for the average user the goal is to just feel like a good & usable network. But this is one big reason why we put all the Fancy Technology under the hood.

Also, contrary to what you might have heard, this isn’t “Jack Dorsey’s company”. Yes, he started the whole thing, but he isn’t running the company – Jay Graber is. Jack was very little involved in the project after they started building; he basically gathered a team, gave them a lot of money and let them do their thing.

In fact, he deleted his account on the platform last summer, after he was booed off it by the users, and now he’s mostly hanging out on Nostr instead. In early May 2024, it was announced that Jack has left the board of directors too – he’s been replaced by Mike Masnick later. Dorsey also doesn’t own any shares of Bluesky.

Apps

Bluesky has an official mobile app for iOS and Android. It’s written in React Native, so it doesn’t feel fully native in all places and some system integration features take a while to be added – the reason is that they’ve started with a very small team at first (I think initially just one guy did all the frontend), so the only way they could do it was to build for both platforms & the web from one codebase.

At this point, after various improvements made later, the mobile app is mostly ok and gets better with every update, it’s also obviously the most feature-complete one. One issue is that it doesn’t support iPad yet.

There is of course also a web interface, at bsky.app, which is pretty good – this is the main UI that I use Bluesky with (also works on the iPad). At the moment it’s mostly meant to be used while logged in, although some pages like posts/threads and profile views can be viewed unauthenticated (the search doesn’t currently work when logged out for performance reasons).

But there is also a small but enthusiastic group of third party developers building various apps, tools and experimenting with the protocol. They’ve built several independent apps, libraries to access the API in various languages, and they often manage to build various new features in their apps before the Bluesky team gets around to doing that in official apps.

Here’s a few of these apps (in various stages of development):

Graysky – a mobile app, first full-featured third party app, although its author was hired by Bluesky later, so it hasn’t been updated much lately
deck.blue – a web-based “Tweetdeck” column UI, written in Flutter (pending rewrite in React)
Skeetdeck – another web-based, more lightweight “Tweetdeck”
Tokimeki – a web app (+ PWA) with a column UI from a Japanese developer
Skeets – native iOS app with iPad support and some interesting features
Skywalker – a native app for Android
Catbird – new iOS client in beta
SkyFeed – a web app with a column UI that also lets you build custom feeds
SoraSNS – a multi-network client for iOS
Openvibe – another multi-network client with support for cross-posting and a unified timeline
Dhaaga – a multi-network client for Android

The Ivory team (Tapbots) is also working on their own client called Phoenix, but at the moment it’s still work in progress.

More recently, a new wave of client apps and services built on Bluesky/ATProto have also started appearing that are focused on either photos or videos, hoping to create a more open alternative for Instagram and TikTok:

Bluescreen, Skylight, Spark, Skyswipe, and Twilight for video
Pinksky, Flashes, and Grain for photos

Feeds & algorithms

Social networks generally include two kinds of feeds: a chronological one, showing all posts from the people you follow in order, and an algorithmic one, showing what the service thinks you will like (which often means though: what they think will bring them more profit). Centralized platforms generally push you towards an algorithmic feed and often make the chronological feed harder to reach (if at all). Mastodon on the other hand only includes chronological feeds and no algorithms.

Bluesky has both – and much, much more.

When you sign up, you start with two default feeds. “Discover” is Bluesky’s main algorithmic feed – it mixes some posts from the people you follow with some other posts that you might like. You can pick the option “Show more like this” or “Show less like this” from the menu on each post to give it some hints on what you like or don’t (note: if you tried it before and didn’t see any effect from these hints, there have been some fixes there very recently, June/July 2025, so try again). The devs are constantly tweaking it and asking for feedback, so it should be getting better over time.

The second one, “Following”, is a classic chronological feed. Initially it had a sort of unique twist, in that it could show you replies from the people you follow made to anyone, regardless if you follow that other person, but this option was removed in August 2025. If you miss that old mode, which was more noisy, but allowed you to meet friends of friends more easily, I made two custom feeds that let you peek at those replies: Follows & Replies and Only Replies.

But that’s just the tip of the iceberg. Bluesky has built a system where anyone with a server and some knowledge of coding can implement their own algorithmic feeds that they can share with everyone else. There are currently about 40 thousands custom feeds (as of Feb 2024) made by the Bluesky community that you can add to your app. And more importantly, the “Following” and “Discover” feeds are just what you start with by default – you can set any of the thousands of other feeds as your main feed, and you can even remove the two built-in feeds if you don’t like them, and leave e.g. only the “Cat Pics” custom feed as your only feed tab. Nothing here is forced on you.

The way a feed works is that it basically reads all new posts on Bluesky from a giant stream and decides which of them to keep and how to arrange them (this can be a shared feed, same for everyone, or a personalized feed that looks different to each user). Most feeds match posts by keywords – these are feeds on some specific topics like Linux, food, gardening, climate change, astronomy, and so on. They usually define some sets of words, phrases, hashtags, sometimes emojis, and include all posts that contain any of these, chronologically.

There are also various “top posts of the week / all time” feeds, posts using AI models to match some specific kinds of photos like pictures of cats, frogs, or moss, or personal algorithmic feeds that show you posts selected for you according to some specific idea: posts from your mutual follows, from people who follow you, posts with photos only, posts from those of your friends who post less than others, and so on. These are all feeds built by third party developers who just had an idea and implemented it, without having to register or apply anywhere or ask anyone for permission.

Some people have also built web-based user friendly UIs for building feeds, which let you build feeds using a web form and have them hosted for you, without having to write code or host it yourself, which allowed a lot of people without programming knowledge to build their own feeds. The first such tool was SkyFeed, built by one German developer, which at some point ran the vast majority of all feeds on Bluesky; another newer one is Graze, a larger service with a bit friendlier interface, which recently partnered with Bluesky to run a trending feed for the New York mayor election night.

There’s a nice guide to feeds that describes them in more detail on the Goodfeeds site (archived), there is also a blog post about feeds on Bluesky’s blog.

Useful feeds

There is a feed search engine integrated in the official app, in the Feeds tab (the “Discover new feeds” section). You can also search for interesting feeds on these two external sites: goodfeeds and SkyFeed Builder Feed Stats.

Some general feeds that you might find useful:

What’s Hot, Catch Up and Week Peak Feed – general feeds with most popular posts
Quiet Posters – posts from people you follow who post less than others
Latest From Follows or Latest From Mutuals – just one most recent post from each person you’re following
Popular With Friends – recent posts liked by the people you follow
Follows & Replies and Only Replies – my feeds that include all replies from your follows to anyone
Only Posts – picks only top-level posts from Following without replies or reposts
The ‘Gram – only posts with images from the people you follow

And some “utility feeds”:

All-Time Bangers – posts with the highest number of likes on the whole platform
My Bangers – your own posts with the most likes
Quotes – all quotes of your posts
Mentions – all replies to you or mentions of you
My Pins – your “bookmarks” made by commenting with the 📌 emoji

Safety & moderation

Like on most other networks, you can mute someone if you find them annoying, or you can block them if you find them really annoying. It’s also possible to mute words, phrases or hashtags. You can now also mute words for a specific period of time (there’s no way to mute an account for a specific time yet).

(Note, the blocking mechanism here is pretty aggressive, in that it also hides all previous interactions between the two users *for everyone*; so don’t be surprised if someone blocks you and your reply or quote “disappears” – it wasn’t deleted, just hidden.)

There’s also a number of features for controlling interactions with your posts or threads:

you can lock replies in a thread to only your followers, only the people you follow yourself, or some other combination, or disable them completely (also some time later after replies appear)
you can choose to “hide” some specific negative replies, like on Twitter (they’re moved to a “hidden replies” section at the bottom of the thread)
you can disable the option of quoting your post
you can “detach” existing quote posts of your post – the quoting post stays visible, but without the embed showing your post
and finally, you can temporarily “deactivate” your whole account – this makes it appear deleted to others so people won’t bother you if you need to take a break from social media

You can also create “moderation lists” for muting or blocking some groups of people all at once, which can be shared with others. This is meant to let various communities on Bluesky build their own “defences”, by collecting lists of people who are unpleasant or annoying in some way and letting others mute or block them in advance before they come across them.

If you get added to a user list (the kind meant for following) or a starter pack that you don’t want to be on, and the author refuses to take you off it despite your request, you can solve the problem by blocking the author – you will “disappear” from their list then. For obvious reasons, this doesn’t apply to mute/block lists, since usually no one wants to be on those, but you can now report lists that are clearly hateful or made in bad faith, and they are taking those down. If you don’t know what lists you’re on, you can look that up on Clearsky.

Bluesky’s own moderation seems to generally work ok, though there are some occasional problems, controversies, and periods when they get a bit overwhelmed with new waves of users; but obvious trolls, spams and scams are usually got rid of pretty quickly. They claim to have around 100 people in the moderation team now, as of January 2025.

The general high-level plan for moderation at Bluesky and on the AT Protocol is something they call “composable moderation” (old blog post) or “stackable moderation” (recent post). It’s an idea that moderation will have many layers – from server operators including the Bluesky company, through various tools and services provided by other companies, organizations, and communities, ending with some ways to privately personalize your experience according to your personal needs.

Labellers

A core part of this is a feature called “labellers” that they’ve released in March 2024, which are basically third-party moderation services. They work by assigning a set of labels/tags (manually or automatically) to accounts and posts – this can be because one of the labeller’s moderators has come across an offending post, or because it was detected automatically using some custom software, or because the post or account was reported to the service by a user (users can send moderation reports to any set of these services).

All users on the platform can “subscribe” to one or more of these services and configure how they want these labels to affect their experience: for any label type, they can choose if the user/post marked with such label should be hidden from their view, just marked with a label, or if this kind of label should be ignored. (A labeller doesn’t have the full power of a built-in platform moderation in that it can’t just ban someone from the site and delete their account – but they can make someone effectively disappear for those users who trust and agree with the given service.)

Labellers will usually be specialized in some area: they could be protecting their users from things such as racism, antisemitism, or homophobia; they could be automatically detecting some unwanted behaviors like following a huge number of people quickly; marking some specific types of accounts like new accounts without an avatar, or accounts from a different network; fighting disinformation or political extremism; or they could be serving a community using a specific language or from a specific country.

A simple labeller can be run by one person, but bigger ones can be managed by a whole group of people that collaborate on processing the reports (Bluesky has built an open source tool for this called Ozone). This system allows different communities to handle moderation in their own way independently, to make their members feel safer and have a better experience in the aspects that are important for them. And most importantly, different communities could often have somewhat conflicting or even completely opposing views on some things – and Bluesky as a company doesn’t have to try to satisfy everyone (which is impossible) or always pick a side. They also don’t necessarily have to specialize in every country, language and culture on Earth. Of course they reserve the right to take down some accounts completely, because some things and some people have to removed from the platform for everyone (e.g. things that are just illegal), but in less serious or less clear cases, they can just use labels or defer to other labellers (the Bluesky built-in moderation is now “just” another labeller among many others, using the same API, and with only some special powers). They also have a few country-specific labellers now, so they can comply with government takedown orders by hiding given posts/accounts in a given country, but leaving it online for everyone else.

You can read more about labellers in the guide titled “Bluesky Crash Course: Labelers” written by Kairi, who used to run one of the most popular labellers called Aegis (now defunct).

There’s no easy way to search for labellers in the app yet, but I’m keeping a rough list myself on this page. I also made a “Label Scanner” tool where you can find all labels assigned to a given account from any labeller.

By the way, it’s fascinating how the open architecture of Bluesky allows its features to be used sometimes in completely unexpected ways. Labellers were initially designed to be used mostly for negative, unwanted things, but quite a lot of them ended up being built to let users label themselves with some badges they want to show to others: there are labellers to let you assign a country flag, pronouns, RPG class, Zodiac sign, Hogwarts house and other things.

Some other useful labellers:

XBlock, which lets you hide screenshots of posts from other platforms like Twitter
Profile Labeller, which marks e.g. accounts created recently, without an avatar, ones that changed handle recently etc.
No GIFs Please, which is exactly what it sounds like ;)
Asuka’s Anti-Transphobia Field

Privacy of your data

One important thing from the privacy aspect that may not be obvious at first, which you need to be aware of: the underlying protocol on which Bluesky runs is extremely open. Anyone who knows how to code can write an app or tool that can read practically any data about anyone, without having to ask anyone for permission (since there’s no central authority that can require registration and payment to get API keys like on Twitter). This is by design, because all the different pieces of the network that make it work, apps, tools and services, need to be able to access the data to provide their functionality, and we want everyone to be able to build those to keep the network decentralized and not controlled by one corporation.

This has both advantages and disadvantages. For a developer, it means that the only limit is your time and imagination (and maybe API rate limits). You can build feeds that show all posts with cat photos, a bot that responds to the text “/honk” with a random photo of a goose, implement some new features before the Bluesky team gets around to that, count the statistics of how the percentage of languages used in posts has changed over time, and whatever else you can think of. You don’t have any monthly quotas or paid plans.

For a user though, this means that everything you do is very public – kind of like it was on Twitter, just more so, because there are fewer restrictions.

Specifically, all of these are publicly accessible (even if they aren’t all displayed in the official app):

your posts
your likes
the photos you’ve attached to posts
all the handles you’ve previously used (you can’t delete those)
the list of people you follow
the list of people you block (!)
the user lists and moderation lists (mute/block lists) that you’ve created
which moderation lists (yours or others’) you are blocking people with

And these things are private and known only to you (and the apps and tools that you’ve explicitly granted access to your account):

the people you’re muting (individually or through lists)
the words, phrases, hashtags etc. that you’re muting
your “saved posts” / bookmarks (the new built-in ones, not the 📌 style)
your selected languages and other preferences
your email address, birthday and phone number
who invited you and who you have invited
the moderation services you’re subscribed to
the accounts you’re subscribed to for post update notifications
the custom feeds that you’ve saved or pinned
- one caveat though: the provider of the feed knows when you are opening it

DMs are private between you and the person/people you’re chatting with, but they’re currently not end-to-end encrypted, so the Bluesky team can theoretically access them, and will access them if ordered to. A fully encrypted version will come some time later. For sensitive conversations, Bluesky devs recommend that you use the DMs to just exchange e.g. Signal usernames and then continue there.

The difference between muting and blocking is because muting is simply a filter applied only for you – nobody else needs to know that you’ve asked your app to hide some of the posts. On the other hand, blocking is inherently a two-way thing – that other person, their app/server and any other pieces of the network that process their posts need to be aware of the block, so that they can prevent them from interacting with you. So the fact that the block exists needs to be publicly known.

Now, what all of this can mean in practice:

anyone can download anyone’s posts and do various targeted or global analysis on it, track your likes and contact graph and so on
if you are posting personal photos, especially NSFW photos or photos that can be geolocated, anyone can be downloading all of them automatically (though the official apps strip metadata from photos)
some (any) companies can potentially train some kind of AI models on the data (speaking purely about technical possibility, not legality of course; there aren’t any secret clauses in the ToS that let Bluesky sell your data to AI companies)
blocking someone only adds friction, but it can’t completely prevent them from seeing your posts (same as it always was on Twitter, since you could always open a post in an “incognito” window or use an alt account)
there is no way to add a feature that would let you “lock” a profile for followers only, hiding your content from others, because all post data has to be public for the network to work
copies of any posts you delete might still remain on some third party servers (most services do delete their copies when you delete a post on Bluesky, but you can’t prove it or enforce it)

Some of this might sound scary, but most of this is or was always the case on other social networks too, those that have APIs at least – if you’re posting something publicly anywhere, you need to realize that anyone can record it forever. The main difference is that it’s easier to do it here, because the API has fewer restrictions than on centralized platforms, and that it’s currently not possible to do any semi-private content that’s visible to some people but not to others.

Account security

For logging in to third party apps and tools, Bluesky has initially added a temporary system of “app passwords”. Recently, they’ve also implemented more convenient OAuth authorization, where you authorize a service to use your account like on Twitter and other sites. However, it’s pretty complex to implement, so not all third party apps and tools support it yet, and you might still need to use the app passwords for some of those.

An app password is a special one-time password that you can generate in the official app (Settings / App Passwords), which look something like this: abcd-ef56-vxyz-qq34. You can generate a separate password for every tool and app that you log into. Such password grants almost the same privileges as the main password, but without a few critical ones, and you can revoke it at any time from the Settings screen if you’re not using that app anymore, which disables access to your account for that app. You can also specify if the app password should give the app access to your DMs or not.

For apps and tools that use OAuth, it works just like when authorizing apps to use your Twitter or Facebook account – you get redirected to your Bluesky server, you log in to your account, grant access for the app, and are redirected back there. You can see and manage your list of currently authorized apps on the account page (if your account is not hosted on a Bluesky server, you need to open that on your server’s domain instead).

For additional security, there is for now a simple email-based Two-Factor Authentication (2FA) feature (note: not currently working if you’re on a third-party server). A more complete 2FA system is coming.

Handles & IDs

Bluesky has a really cool system of handles. They couldn’t have just used single-element handles like “@donaldtusk”, because that wouldn’t really make sense in a decentralized system. They also didn’t want to bind your account permanently to the name of the server you’re on like in Mastodon, where you’re e.g. “ivory@tapbots.social” and you can’t change that unless you make a new account.

So here’s what they’ve come up with: internally, your account is identified by a unique identifier called “DID” (Decentralized Identifier) – an ugly string of random letters (mine is did:plc:oio4hkxaop4ao4wz2pp3f4cr). To that DID you assign a handle, which you can switch at any moment to a different one, and any contacts, references and connections will (mostly) stay intact; and the handle is actually just any domain name, usually displayed with an “@“ at the beginning, but without any additional username before it.

By default, when you first join Bluesky (the current official server) you’re given a handle which is a subdomain of bsky.social, e.g. “georgetakei.bsky.social”. This is a real domain name, you can type it into the address bar of the browser and it will redirect you to the profile on Bluesky.

But at any moment you can switch to a different handle by assigning any domain name that you own. It can a very short name like retr0.id, or something long with one of those quirky new TLDs like .horse or .computer, or it can even be a very official sounding domain like washingtonpost.com.

There are two ways to assign a domain, either via HTTP by putting a file in a specific place on the website hosted on the domain, or via DNS by putting a new entry in your domain configuration – the complete instructions are here. (BTW, Bluesky also runs a service that resells and automatically configures domains through a partnership with Namecheap.)

This also means that you don’t need to rush to “reserve your handle” at ***.bsky.social – because custom handles are cooler anyway 😎 (if you change your handle from *.bsky.social to a custom domain, that old handle is now reserved and unavailable for others, that didn’t work like this at first). This system also makes it much easier to move your account to a different server – you can take your content and connections with you and keep your existing identity, because your DID identifier never changes.

There’s even a number of “handle services” now that let anyone use a subdomain of their domain as the handle – e.g. go to swifties.social if you want your handle to be “yourname.swifties.social” 👩🏻‍🎤

Verification

The system of domain names in handles serves as a primary way of verifying accounts on Bluesky. If someone has a handle that matches the domain of e.g. some newspaper, organization or government branch that you recognize, you can assume that the account is operated by someone who was authorized by that entity. So e.g. @wyden.senate.gov is definitely US Senator Wyden (or at least his staff), and @cnn.com is definitely CNN – no one has to manually verify their documents. We also have here e.g. the European Commision @ec.europa.eu, government of Brazil @brasil.gov.br, Interpol @interpol.int, or European Space Agency @esa.int 🚀

If you’re setting up an account for some well known organization, it’s highly recommended to switch to your domain as the handle from the start to make it clear that it’s an official account.

As an additional verification factor, e.g. for publicly known people who don’t have a well known domain or can’t use one, Bluesky has now added classic “blue check” verification badges. They’re not really meant as a common thing like they are on Twitter now, and they have some important limitations, e.g. they expire if you modify your handle or display name in any way, but they’re useful for making sure that, for example, yes, it’s the real Barack Obama.

The checkmark verification system is designed in such a way that Bluesky can grant other organizations the right to verify the people they vouch for themselves; so you can see that e.g. a Financial Times journalist has a blue checkmark, but if you click on it, you see that he’s been verified by Financial Times, not by the Bluesky team. That way, Bluesky folks don’t need to verify each account themselves manually.

How are things called here?

The app generally uses “neutral” terms like “post”, “repost”, “feed”, “timeline” and so on. That said, pretty early on someone came up with with the word “skeet” for posts, for “sky + tweet”, and it stuck, despite (or likely because of) the team’s protests. So the term is used pretty commonly, though maybe a bit ironically, despite being a bit controversial because of its existing, other slang meaning (see Urban Dictionary)… By analogy, you can also “reskeet”, “subskeet” and so on.

The timeline/home feed is also sometimes called a “skyline”.

New users that have joined Bluesky recently are often called “newskies” – there is even a Newskies feed, which includes every new user’s first post (and only their first post). On the opposite end, some folks sometimes jokingly call people with a long experience on the platform “Bluesky elders” (a reference to one post that was widely made fun of). There is a labeller that gives you an elder label if you had an account before summer 2023.

A “hellthread” is something that existed for some time in the spring of last year – the initial implementation of notifications notified you of any reply somewhere below your post or comment, to an unlimited depth. People have started creating extremely long and nested threads, which notified everyone involved of any reply, and there was no way to opt out of it. A certain community has formed around these hellthreads, of people who hang out together and sometimes waged wars in them. Eventually, the notifications were fixed, but due to protests, the devs have kept an option to still create hellthreads in one place, hardcoded in the app code. This was finally removed a few months later.

A “nuclear block”, alternately “apocablock”, is a name for the feature where when one user blocks another, it hides all previous replies between the two from everyone – it basically “nukes” the whole conversation to discourage other people from joining in (though you can still find the posts though if you’re determined, e.g. on the users' profile page feeds or in Skythread).

A “contraption” was an informal name for set of popular mutelists/blocklists maintained by a user named Kairi in 2023 (which were later turned into a widely used labeller called Aegis, which eventually shut down a few months later) – the trolls and haters who have crossed a line were told “okay, you’re going into the contraption”. The term is still being used as a generic name for any set of blocklists.

What is this federation thing?

The goal of Bluesky is to be a network that consists of many, many servers run by a lot of different companies, organizations and people that connect with each other – that’s roughly what federation means. Initially, all the critical pieces were controlled by Bluesky PBC; however, this is gradually changing. They’ve taken the first big step towards federation in February 2024, by letting people migrate their accounts to self-hosted servers. This is still a technically complex process, and there aren’t really any public non-Bluesky servers which allow open signup, but there are currently a couple thousands of mostly personal “PDS” servers, where people keep their accounts and data. I’m currently posting from my own PDS named lab.martianbase.net.

If you’re worried that things will get more complicated, maybe you have some bad experiences from Mastodon – then don’t worry. They’ve specifically designed everything to be less confusing. The Bluesky-managed accounts have actually already been spread out internally on a number of separate servers – they’ve been migrated sometime in November 2023, and few people have noticed, because everything just kept working. Now, you have an option to move your account to a server controlled by someone else, if you want to – but you can just ignore the whole thing if you don’t care about it. You can’t even easily see who is on which server, unless you check it with a third party tool like internect.info.

(Fun fact: the Bluesky PDS servers are all named after different kinds of mushrooms, e.g. my original PDS was “amanita” 🍄 – so if you see someone talking about “mushroom servers”, they’re probably talking about those :)

Bridgy Fed

Bluesky opening to federation does not mean that it will connect with Mastodon servers though, since they use different, incompatible protocols. There is however a “bridge” service called Bridgy, built and operated by a third party developer, but supported by the Bluesky team.

The way it works is that it “mirrors” Mastodon accounts and their posts to Bluesky or Bluesky accounts to Mastodon (for accounts that have enabled the bridge). It’s possible to create whole threads where some replies are made by Mastodon accounts and some by Bluesky accounts, all of them being visible in both places. See e.g. here the bridged profile of Eugen Roshko (Gargron), creator of Mastodon, as seen on Bluesky.

If you want your Bluesky profile to be visible on the Fediverse, you need to “opt in” by following the official Bridgy account on Bluesky, @ap.brid.gy. Your profile will be seen on the Fedi side as @your.handle@atproto.brid.gy.

To follow Mastodon accounts that are already bridged (like Gargron’s) from the Bluesky side, just look them up in the search and follow them as normally. If someone you want to follow is not bridged yet, you need to either ask them yourself to enable Bridgy (by following the Mastodon equivalent of the Bridgy account, @atproto.brid.gy@atproto.brid.gy), or you can DM the @ap.brid.gy account on Bluesky and tell the bot the Mastodon handle of the user you want to follow, and it will ask them on your behalf.

Note that there are some obvious limitations because of the differences in supported features, e.g.:

posts from Mastodon longer than 300 characters are truncated, and a link is added to the full original post
Bluesky doesn’t support post editing yet, so edits made after you create a post aren’t visible on Bluesky

The Atmosphere

The “Atmosphere”, also often spelled “ATmosphere”, is a name given to the wider network of apps and services that are being built by third party developers on the Bluesky platform and the AT Protocol. It includes not only Bluesky-specific clients and tools, but also somewhat separate apps/sites like:

blogging platforms, e.g. WhiteWind or Leaflet
photo sharing sites like Grain
Tangled, a GitHub-like code hosting & collaboration site
the video apps mentioned earlier

These are not directly a part of Bluesky, aren’t run by Bluesky PBC and aren’t always closely integrated with Bluesky, but they are built on the same system, and depending on the specific tool, they can potentially integrate and share data with Bluesky and with each other. In each of those, you can usually sign in using your existing Bluesky account and use the same handle/avatar/name that you have configured on Bluesky.

Search

Search works pretty well now on Bluesky. You can search for words, phrases and hashtags, and sort by popular posts or by latest. This is a global search like on Twitter, so it finds posts from everyone everywhere, not like the limited full text search on Mastodon.

You can also add “from:some.handle” to find only posts from a given user, or “from:me” to search within your own posts. There are several more filters available, like filtering by date or by language, although there’s no easy UI for everything yet – but the Bluesky team has posted a tutorial “Tips and Tricks for Bluesky Search” on their blog recently.

Hashtags

Support for hashtags was added in February 2024. When you click on a hashtag you have an option to search for all posts with this hashtag, only posts from the given person, or to mute that hashtag.

Note that for various reasons, hashtags aren’t as integral part of the platform and aren’t as commonly used here as on the Fediverse; people also are wary of using them because they have a bit of a bad reputation from Twitter or Instagram, where spammers often abuse them. Try not to overdo hashtags, e.g. don’t use more than 1-2 in a post – ideally just take note of how other people are using them.

One thing that’s defined in the protocol but not implemented in the official app yet is that hashtags were designed to have two forms: inline tags like on Twitter, and external (outline) tags which are shown below the post, which I think is the way they work on Tumblr (Mastodon now also shows trailing hashtags at the end of a post in a similar way). You will be able to use either or both in a post according to your preference, and they will be interchangeable, with both being returned in the same search. These tags are currently supported in some third party apps like Skeetdeck.

Video & GIFs

Videos are available on Bluesky since September 2024. They’re currently limited to 3 minutes.

For GIFs, there is a built-in support for adding Tenor GIFs in the post compose dialog, by pressing the GIF button and picking something from the search results, and you can also upload custom GIFs – now also on mobile.

You can also embed e.g. YouTube videos in posts, which will play inline inside a post when clicked. (This whole feature was actually implemented by a third party developer.)

Starter packs

Starter packs are a unique Bluesky feature added in June ‘24, which lets you create a list of accounts and feeds that you want to recommend to others. You can make e.g. a list of AT Protocol developers, climate scientists and reporters, or astronomers, and then people can use it to find some interesting new accounts to follow, or just follow them all at once with one click.

You can also share a link to a starter pack with people who don’t have a Bluesky account yet, and they can use it to sign up with to have some initial set of accounts to follow.

There’s no list/search of starter packs built-in in the app, but you can browse and search for them e.g. on the third party Bluesky Directory website.

Bookmarks

Native bookmarks (called “saved posts”) were added in early September. You can save a post using the “bookmark” icon below it, and you can access saved posts through the “Saved” section in the sidebar. Bookmarks are private – a counter of number of saves is shown below a post, but you can’t see who saved it.

An earlier, popular workaround was that you could reply to posts with a comment “📌”, and there’s a special bookmark feed which shows you all your comments with that emoji. This option is still available, although since these bookmarks are essentially normal comments, they are all public.

There is also a tool available to import all your previous “pins” to the new “saved posts” system.

Settings

Some things that you may want to look at in the settings, going from the top:

Switch account – you can log in to multiple accounts, and you can switch between them here in the Settings, by clicking your avatar in the top-left corner of the page on the web, or by pressing and holding your avatar in the tab bar on mobile
Account » Export my data – lets you download a backup of your data like posts and follows (at the moment it doesn’t include media like images)
Account » Deactivate account – lets you temporarily lock your account (it appears deleted to others)
Privacy and Security – enable Two-Factor Authentication and create “app passwords” for third party apps; you can also specify if you want others to be able to get notifications whenever you make a new post
Moderation – manage muted words & tags, muted and blocked accounts, and your moderation lists; you can also choose to hide “blue check” badges if they annoy you
Moderation » Content Filters – here you can set what kind of potentially objectionable content you may want to show or hide – generally various NSFW things. I’m not sure what the defaults are currently, but it’s worth checking and tweaking to your preferences. (Watch out, there can be quite a lot of somewhat NSFW content there that you can randomly come across in some feeds, although it’s generally hidden behind a content warning.)
In the “Advanced” section below, you can adjust which of the moderation labels from each specific labeller you want to apply in your feeds – this includes the built-in “Bluesky Moderation Service” labeller.
Notifications – since July 2025, you can configure here precisely what kind of notifications you want to get: you can e.g. turn off all notifications about likes, reposts or follows, or leave them on only for the people you follow
Content & Media » Thread Preferences – you can choose to have threads sorted by newest, oldest or most liked comments; there is also an experimental nested (tree-like) thread view that I highly recommend enabling (although for longer threads you may want to use my tool Skythread instead :]
Content & Media » Following Feed Preferences – choose if you want to see replies, quotes, reposts etc. in the home feed. (Some earlier options from this section were removed last year, see the Feeds section for more info & workaround.)
Content & Media » Autoplay videos and GIFs – turn off to prevent videos and gifs from automatically playing in your feeds; instead you get a play button on each that you have to press first to see it
Content & Media » Enable trending topics – turn off if doomscrolling isn’t your thing
Appearance – you can make the fonts smaller or larger, or switch light/dark mode
Accessibility » Require alt text before posting – you can turn this on to always be reminded to set an alt text on photos (it’s generally considered nice to add the alt text to images whenever possible, for people who use tools like screen readers or VoiceOver; as a bonus, it also makes your posts easier to find in search and feeds)
Languages – turn on all the languages that you understand or want to see; Bluesky generally hides posts in languages that you don’t have enabled from most places like feeds and search results, except your Following timeline. For your own posts, you set a post’s language yourself in the compose post window – you can switch between a few languages, and if you have the wrong one set when writing, a popup with a warning should appear.

Also in the “Chat” section of the app, there is a separate Chat Settings section under the “cog wheel” icon, where you can specify who you want to be able to contact you via DMs: everyone, no one, or only people that you follow yourself (default is people you follow); conversations you’ve started before are accessible even if you change the setting.

Missing features

There are a few things missing on Bluesky that are available on some other networks. Some of these are limitations of the protocol, and some are just a matter of too much work and too few hands to do it – the team is still pretty small and they have a ton of things to build to catch up with more mature platforms (Mastodon) or those with more people and funds (Threads), and they need to prioritize and some things are always put off.

If you’re a developer and want to help, the app and most of the related services are open source, and the team is happy to accept outside contributions at least for bug fixes and smaller tweaks.

Some things that are still missing:

Private profiles / circles

Like I’ve mentioned in the Privacy section, the AT Protocol as built currently requires all data apart from your private settings to be completely public. There is no way to make something that you only share with some people but not others. There may very well be something like this in the future, because a lot of people are asking for this and the team wants to look into it – but they will have to first invent some other, separate way to share content in the protocol, which will take a lot of time and thinking. So it’s likely to come at some point, but not anytime soon, because it’s much harder than it may look.

DMs on the protocol

For the same reason, sharing messages with only one or a few people using the AT Protocol is currently not possible. The team wants to eventually add DMs to the protocol, but this is something that will require a lot of research first.

But since *a lot* of people wanted to have some way of talking privately with friends, even if it’s an imperfect one, the team has recently added a simple implementation of DMs that isn’t currently a part of the protocol. The DMs are currently using a single centralized service hosted by Bluesky (although third-party apps can access this API), and are not end-to-end encrypted – so they basically work like on Twitter. The first version also doesn’t support group chats and images, only 1-to-1 text chat – but more features are coming soon.

Eventually, the team wants to figure out and add a more full-featured, decentralized and private version of DMs (which may involve integrating with some existing private messages standard). This is however pretty far down the list at the moment, so something not likely to come this year.

Post editing

This will definitely be added at some point, but it’s also a relatively complex feature, because of the need to store the previous versions of an edited post that you should be able to access somehow. They want to do it right and that will require some thinking on how to solve the problem in the most general and elegant way.

Soft-blocking / removing followers

There is an issue currently that there is no way to remove someone from your followers except by having them blocked. If you block-and-unblock them, what some people call “soft blocking”, they stay on the followers list. This is a current limitation of how follows are designed in the protocol – when someone follows you, they do it by adding a “follow record” to their account, and only they can update or delete their own records, you can’t do that from your side.

I think this is likely to get fixed at some point with some kind of workaround, but it’s not trivial to add and not high priority at the moment – but they’re thinking about it.

Polls

This might be a bit tricky, because we probably don’t want to have everyone’s poll choices public to everyone, and right now everything is public… But this is also one of those things that people ask about regularly, so I hope they’ll figure something out.

Two-factor authentication

See the “Account security” section.

Longer posts

This seems to have been a conscious decision that the team wanted to create a medium that’s more like Twitter than like Mastodon when it comes to post length. This isn’t a simple matter of a field length, because this affects the way people communicate, and allowing longer posts has advantages and disadvantages, it’s just a different text form. (See a comment from lead dev about this.)

So it looks like this won’t be changing – although there might later be other “apps” implemented on the AT Protocol that aren’t a part of Bluesky that will allow longer posts, even complete articles, and they might be somehow integrated into Bluesky in the future (e.g. posts bridged from Mastodon by Bridgy, which can be up to 500 characters long, include the full original content in the record data and apps may choose to display the full text inline).

Disabling reposts per user

It’s not a hard technical problem, but it seems to be blocked by some other things right now – but it should be added eventually, since everyone is asking about it.

Links on the profile, scheduling, …

I haven’t heard much about those, but I’m assuming it’s all coming at some point once they get through the hard stuff they’re busy with now. (Scheduling can currently be done using some third party clients like deck.blue, or cross-posting services like Buffer.)

Other tools

Finally, here are a few tools written by third party devs that you might find useful:

Firesky – a site that shows you a live feed of every single new post made on Bluesky – feels like watching the Matrix screen
Clearsky – lets you look up the list of all people that are blocking you (or someone else), or the mute/block lists, user lists, and starter packs that you’ve been added to
Listifications sends notifications when you’re added to a list or starter pack, or when someone blocks you
wolfgang.raios.xyz – also shows your blockers, block statistics and can generate “interaction circle” images that show who you mostly keep in touch with
cred.blue – calculates your “Bluesky score”
Jaz’s Profile Cleaner – lets you delete old data (old posts etc.) from your account
internect.info – lets you look up the DID of an account, its server name and how the assigned handle has changed in the past
Jaz’s post stats (total count and daily posters), my stats (daily/weekly stats), and bskycharts (charts of firehose activity and daily/monthly active users)
Skythread – a thread reader by yours truly, mentioned earlier :]
Label Scanner, for checking if there are any labels assigned to an account or post
Bluesky quiet posters – shows the list of people you follow ordered by how long ago they’ve posted anything
Clean follow – lets you clean up your follows list of blocked and suspended accounts
Gentle Unfollow – lets you browse your follows one by one, showing each person’s recent posts, and lets you decide if you want to keep them or unfollow
Bluesky network analyzer – analyzes your 2nd degree connections (follows of your follows), and shows you suggestions of people that a lot of your friends are following
nws-bot.us tools – a set of tools for managing lists and starter packs

And some other guides (some mentioned earlier in the blog post):

Bluesky Guide (Amanda Wyatt Visconti, Aug 2023 + updates)
Bluesky Social New User Guide (Kairi, Nov 2023 – archived)
How to get started on Bluesky (Emily Hunt, Nov 2023)
Bluesky user FAQ (Bluesky, May 2023)
The Newskies' Guide to Safety and Privacy on Bluesky (eepy, Oct 2023)
How to set your domain as your handle (Bluesky, Apr 2023)
Tips and Tricks for Bluesky Search (Bluesky, May 2024)
The Guide to Feeds (Jerry Chen – archived)
Algorithmic Choice with Custom Feeds (Bluesky, Jul 2023)
How to use Bluesky to grow your brand (Dame, Jun 2025)
What the hell is the atmosphere anyway: A slightly less technical intro to the technical side of Bluesky (Bailey Townsend, Sep 2025)
Open Social – a high-level overview of how the AT Protocol brings back the openness of the original pre Web 2.0 web (Dan Abramov, Sep 2025)
Bluesky Crash Course: Labelers (Kairi, Apr 2024 – archived)

Thanks to Mozzius, Shreyan and Marshal for the feedback on the first draft :)

Changelog:

18 Nov 2025: added links to Tokimeki, Catbird, Dhaaga, and Graze, removed link to Skychat

26 Sep 2025: added links to Bailey Townsend’s and Dan Abramov’s blog posts

8 Sep 2025:

added native bookmarks
custom GIF upload now works on mobile

29 Jul 2025: added link to guide by Amanda Wyatt Visconti

9 Jul 2025:

added new sections about trending topics, verification badges, and the Atmosphere
videos have a 3-minute limit now
mentioned several new photo and video apps, and Tapbots' plans for their Bluesky client
added links to a few new sites and tools, removed US Politics Labeller, Skybridge and PLC Handle Tracker
reordered & expanded settings page descriptions
mentioned Bluesky’s subscription plans
mentioned recent fixes in Discover
mentioned that subscriptions for account new post notifications are private
mentioned reporting malicious lists
mentioned Ozone and country-specific moderation
added info that .bsky.social handles are now kept reserved after change
added some tips about hashtags use
added info about OAuth account management page
added recommendation of Signal for sensitive DM conversations
added info about GIF uploads

12 Nov 2024: added info about threads composer and the plans for disabling reposts

8 Nov 2024:

added info or mentions of new features: videos, starter packs, pinned posts, listing quotes, timed word muting, new safety features, and OAuth
added a list of popular labellers
added a mention of handle services
expanded the “how are things called” section a bit
updated section about feeds, added a list of recommended feeds
updated section about federation, added info about Bridgy Fed
updated info about Jack Dorsey’s involvement

24 Jun 2024: removed link to Aegis (rip)

19 Jun 2024:

added info about built-in Tenor GIFs and DMs
added new section about labellers
Jack Dorsey is no longer on the board
updated some mentions about the Mastodon bridge, which is now live
some changes to feeds section – defaults for Following have changed, Discover is now much better, and you can remove the default feeds

26 Mar 2024: added mention about handle history in the Privacy section

2 Mar 2024: hashtags and word muting are now available, updated the part about longer posts

23 Feb 2024: federation is live!

21 Feb 2024: search now returns results when you search for a hashtag.

2023: Year of social media coding

2023-11-09T14:46:07Z

I had different plans for this year… then, Elon Musk happened.

Elon took over Twitter in October last year, which set many different processes in motion. A lot of people I liked and followed started leaving the platform. Mastodon and the broader Fediverse, which has been slowly growing for many years but never got anything close to being mainstream, suddenly blew up with activity. A lot of those people I was following ended up there.

Then, Twitter started getting progressively worse under the new management. Elon’s antics, the whole blue checks / verification clusterfuck, killing off third party apps and effectively shutting down the API, locking the site behind a login wall, finally renaming the app and changing the logo – each step made some of the users lose interest in the platform, making it gradually less interesting and harder to use.

Changes, so many changes… and things changing meant that I had to change my workflows, change some plans, build a whole bunch of new tools, change plans a few times again, and so on. My GitHub looks like this right now, which is way above the average of previous years:

As usual, I ended up writing way more Ruby and JavaScript than Swift, which goes a bit against my general career plans – but I’ve built so much stuff this year and I had a ton of fun doing it. So in this blog post, I wanted to share some of the things I’ve been working on lately.

The Dead Bird Site 🦤

I had a bunch of private tools written for the Twitter API. For example, I had a script that downloaded all tweets from my timeline and some lists to a local database. I was also running various statistics on tweets, e.g. which people contribute how much to the timeline and list feeds, and automatically extracted links from tweets from some selected lists.

And then Elon shut off access to the API (unless you can afford $100 per month for a “hobbyist” plan), which meant I had to try to find other ways to get that data.

I quickly got the idea that I could somehow intercept the JSON responses that the Twitter webapp (I refuse to call it the new name, sue me) is loading from the JavaScript code. The JSON responses are very complicated with a lot of extra content, but they do contain everything I need. The problem is how to get them; I wanted to get data from my personal timelines, so I couldn’t do anonymous requests, and I didn’t want to make authenticated requests for my account from some hacked-together scripts, for fear of triggering some bot detection tripwire that would lock my account.

So the approach I settled on was to passively collect the requests in the browser, using Safari’s Web Inspector, and export them to a HAR file that can be parsed and processed like the data from the public API. (It would be even better to have a browser extension that intercepts XHR calls on twitter.com automatically, but as far I can tell, there is no way for request monitoring extensions to look at the content of responses, unless you inject scripts to the site.)

I initially tried to implement it as a Mac app, which gave me a chance to start experimenting with Core Data a bit. But in the end, I rewrote it in Ruby and released it as gem I called “BadPigeon” – named after the friends who visit my balcony every day 🐦

The gem is designed to output extracted data in the same form as the Twitter API, in a way that can be plugged into the popular twitter gem, so I could use all existing tools I had written with very little changes. The obvious downside is that it needs some manual help with the recording first, but I can live with that. I’ve been using this setup since June and it works pretty well for me so far.

I had one more Twitter-related project that I sadly had to shut down though – the Rails Bot which has been running non-stop since 2013, mostly unattended, picking and retweeting tweets from some developers in the Ruby community. It requires access to the API to fetch its home timeline periodically from crontab, so I couldn’t make it work this way.

mackuba ∕ bad_pigeon

A tool for extracting tweet data from GraphQL requests made by the Twitter website 🐦

Mastodon’t 🦣

As the migration of developer communities out of Twitter started, I was initially skeptical; looking back, I guess I just had to go through the “five stages of grief” at my own pace… I also didn’t initially see the change as that bad as some others did, and to be honest I still don’t – to me, Twitter still isn’t literal hell on Earth, it’s just that month after month, it got progressively less useful, less interesting and more annoying.

So I finally started looking at Mastodon with interest. The idea of the “Fediverse”, a distributed system of many independent servers with a completely open API, where I don’t need to pay absurd prices for an access key, don’t have monthly download limits and which can’t be taken over and locked down, was appealing to me.

You see, I’m a bit crazy about data hoarding and processing information – for many years I’ve been having various ideas about tools I could write to somehow automate finding more relevant content in the noise of social media, to let me waste less time on it while still finding what’s important (the Rails Bot was a very early example of that). So I thought that maybe in this new open world, where the only limit is my imagination, I could build any tools I ever wanted and share them with others.

Well, turns out it’s not that simple…

It’s true that the Mastodon APIs are completely open and generally permissionless; for example, you can easily download any account’s complete history of “toots”, going as far as a few years back, anonymously. The problem is that there is a certain culture of the existing community of the Fediverse that was there way before the great migration, which is extremely against any kind of data collection, archiving and indexing. Making information searchable – information which is broadcasted in the open to the world – is seen as a threat to safety, and anyone who attempts that is labelled a “tech bro”, derided and attacked.

Sometime in winter I went down the rabbit hole of many, many threads discussing several of such tools, with the authors being attacked and told that they shouldn’t have built them. Just by mentioning in one of the threads that I’m thinking about building a Mac app that allows you to search the history of your home timeline, I got called out on “#fediblock” (Fediverse’s popular channel for warning about bad actors) as someone worthy of blocking.

All of this has very quickly cured me of any ideas to build pretty much any public tool for the Mastodon API. I just don’t have the energy and mental strength to deal with people attacking me this way for simply building tools on an open API that they don’t like.

What I ended up doing though was setting up my own personal Mastodon instance, martianbase.net. I joked that I’m probably the only person who hates Mastodon and also has their own Mastodon instance… But the first instance I signed up on last year was shut down unexpectedly, giving me no chance to migrate the account. That’s another thing I dislike about the ActivityPub system – your account identity and data is bound to the domain of your instance, and there is no easy way out if your admin misbehaves or disappears, or just has a different view on which other servers you should be able to talk to. So at that point I decided not to trust another instance admin, but to set up my own place, so that I can have full control over it.

Blue skies ahead 🌤

And then, just as Twitter was slowly going down and Mastodon has disappointed me – I started hearing about Bluesky.

Started as an idea of Jack Dorsey from Twitter back in 2019, with a goal of building a “decentralized Twitter” that Twitter itself could possibly one day be a part of, the project has been going on for a few years, and just as the whole Twitter chaos started, Bluesky got to the point where it could be presented to the world.

(Important note here, since media has widely promoted Bluesky as “Jack’s social network” and his name puts a lot of people off: it’s not in fact Jack’s social network. He’s not the CEO (a woman named Jay Graber is), he does not manage or control the company, and AFAIK he’s actually been very little involved in it recently, having mostly switched his interest to Nostr – to the point that he has even deleted his Bluesky profile.)

The attention and interest that Bluesky has received after lauching an invite-only beta has widely exceeded the team’s expectations, but this was both a blessing and a curse. They weren’t really prepared to run a real Twitter competitor that could accept the “refugees” escaping Elon’s playground. The thing is, they were mostly focused on the underlying protocol before, and the site itself has been launched as a bit of a demo. A lot of things that people consider pretty essential in a social networking site weren’t ready. But the team – which at that point was less than 10 developers in total, AFAIK – started adapting to the new reality, working as hard as they could to make the site usable for much larger crowds that they had been planning to.

I got access to Bluesky in late April. I don’t want to get into too much detail here about what it’s like, how it’s evolved since then and so on – I’m going to write a few more blog posts about Bluesky specifically. But long story short, I was completely hooked from day one.

Yes, it’s invite-only, has a much smaller userbase than the Fediverse, it’s an early beta, it doesn’t have videos, gifs or even hashtags. The iOS/Swift developers there are as rare as a unicorn. But it has a really nice community of users, third party developers who hack on various tools and help each other, and team members who interact with us on the site all the time. It looks and feels more like Twitter than Mastodon does, and it somehow just feels more fun to be on.

But the thing that excites me the most is the AT Protocol it’s built on and its potential. It’s a completely open federated protocol, just like ActivityPub that Mastodon uses, and it’s intended to eventually create another “fediverse” of distributed social apps (though the federation part is not live yet, but coming soon). It’s designed to take some lessons from what doesn’t work well in ActivityPub (and would be hard to change) and design the architecture better. For example, it uses “Decentralized IDs” (DID) independent of the hosting server to identify accounts, which makes it easy to migrate accounts between servers (and your handle can be any domain name you own, like @mackuba.eu).

The code it’s running on is open source, the APIs are completely open, and it all just invites you to write some tools and libraries for it – to be the first person to write a Ruby library, a Swift SDK, a command line client, a website with statistics. To be the first to plant a flag where others will come later.

I’ve been spending most of the time since April working on one Bluesky-related project after another, sometimes switching between a few in parallel. In the rest of this blog post, I wanted to show you some of the things I’ve been busy building:

Minisky

On the first day after I got in, I already started digging in the API and I wrote a small Ruby script for archiving my timeline and likes (of course I did…). This eventually evolved into a Ruby gem I called Minisky, which provides a minimalistic API client that handles logging in, refreshing access tokens, making GET and POST requests to the API and returning parsed JSON responses.

It doesn’t include any higher-level features like “get posts”, you have to know the name of the endpoint, what params to pass and what fields it returns, but it handles all the basic boilerplate for you. I use it as a base for some internal scripts, and for manually getting or sending some data to the API in the Ruby console. If you want to start playing with the Bluesky API or build some more specific tool that uses it, you can give this library a try (see the example folder for some ideas). It has no dependencies apart from Ruby stdlib.

mackuba ∕ minisky

A minimal client of Bluesky/AtProto API

Custom feeds on Bluesky

Bluesky has a really cool feature that I think is pretty unique among all the social networks. On social sites, you normally have either a reverse-chronological timeline of posts from the people you follow, or some kind of algorithmic “home” feed that mixes them up with other suggested posts, in a way that you usually don’t fully understand and may not like (or both of these feeds).

Bluesky has both of these, but it also lets anyone build a custom feed that selects and orders posts however you like, and most importantly, lets you make this feed available to everyone else. Custom feeds are a core feature of the app; it lets you browse popular feeds from other people, feeds are listed in a separate tab on the feed author’s profile, and you can “pin” the feeds you use often, which puts them in the top bar in the mobile app, as if it was another built-in timeline. People build all kinds of feeds – thematic feeds like various scientific or art or NSFW feeds, feeds for specific communities like “Blacksky”, general “top posts this week” feeds, or different variations of an algorithmic “home feed” using various approaches.

The way the feeds work is that you need to provide an HTTP service on your server which implements a couple of endpoints. The Bluesky server then makes a request to your service on user’s behalf when they want to view the feed, and your service should respond with a JSON that includes a list of post URIs. Bluesky then takes these URIs and turns them into full post JSONs that it returns to the client.

When the team launched this feature back in May, they included a sample feed service project implemented in TypeScript. But I’m not a big fan of JS/TS and Node, so of course I had to reimplement it all in Ruby :]

I’ve spent quite a lot of time working on the feeds and related code this summer, and the result of this is three separate Ruby projects that I’ve open sourced on GitHub (in addition to my main project which is private).

BlueFactory

The first part is an implementation of the feed service itself. I based it on Sinatra, and it implements the three API endpoints required from a feed service. You need to provide some configuration (hostname, DID of the owner etc.) and your custom class to call back to in order to get the list of post URIs and the feed metadata. If you want, you can further customize the server using the Sinatra API, e.g. adding some custom routes with HTML content.

Feeds can generally be divided into two categories: general and thematic feeds that return the same content for everyone, and personalized feeds that show the feed from a specific user’s perspective. The latter are usually much more complicated to build, since you will often need much more data of different kinds to generate the response, depending on your algorithm. If you want to build a personalized feed, the request includes a JWT token that you can use to get the requesting user’s DID, and the gem can pass that as a param to your class (although note that at the moment it does not verify the token, so it can be easily faked).

mackuba ∕ blue_factory

A simple Ruby server using Sinatra that serves Bluesky custom feeds

Skyfall

To return the post URIs from the feed service, first you need to get the posts from somewhere. You could possibly get them from the API, but realistically, a much better option is to connect to a so-called “firehose” web service and stream and save them as they are created, keeping a copy in a local database.

The firehose streams every single thing happening on the network, live – every new and deleted post, follow, like, block, and so on. Depending on your specific feed idea, you will usually only need to keep a small fraction of this data, e.g. only posts and only those that match some regexps – but you need to parse it all first to know what to keep. What further complicates things is that the firehose data does not come in a JSON form, but instead uses a bunch of binary protocols originated from IPLD/IPFS.

The second Ruby gem is meant to simplify this for you. It uses an existing CBOR library to do some of the binary protocol parsing and faye-websocket for the websocket connection. It connects to the firehose websocket on a given hostname and returns parsed message objects with the info about specific add/remove operations and relevant JSON records.

The firehose (and the Skyfall gem) isn’t only useful for creating feed services – you could possibly use it for any other project that needs to track some kind of records from the network in real time, whether it’s follows (to create a connection graph of the whole network, or to track when a follower unfollows you), or blocks (to find out who is blocking you), or to monitor when you or your company or project are mentioned by anyone anywhere. I’ve also included an examples folder with some sample scripts in the repo.

mackuba ∕ skyfall

A Ruby gem for streaming data from the Bluesky/AtProto firehose

Bluesky feeds template

This project puts the previous two together and combines them into an example of a complete Bluesky feed service, which reads posts from the firehose, saves them to an SQLite database and serves them on a required endpoint – basically a reimplementation of the official TypeScript example in Ruby.

This is a “template” repo, which means it’s not meant to be used as-is, but instead forked and modified in your own copy. The reason is there are simply too many things that you may want to do differently – deployment method, chosen database, specific data to keep etc., and making this all configurable would be an impossible task. Instead, I’ve extracted the “input” and “output” parts as separate gems that can be used directly, and you build the parts in the middle – but you can use this template project as a good starting point.

My own feed service project is a private repo, but I’m keeping it in a similar structure to this template and I’m manually backporting some fixes and new features from time to time.

mackuba ∕ bluesky-feeds-rb

Template of a custom feed generator service for the Bluesky network in Ruby

My feeds

And now we get to the part that all of this was for – building my own custom feeds.

I mentioned earlier that I often think about and experiment with various ways to find most relevant content to me on social media. So when I heard about the custom feeds feature, I immediately had an idea to build a feed for Mac/iOS developers that filters only posts on this topic, using a long list of keywords and regexps (I’ve actually reused a lot of work I’ve done a while ago for an unfinished thing I played with on Twitter).

It took me a couple of months to build all the pieces of the “feed generator”, but I’ve launched the Apple Dev feed in July. It isn’t very busy so far, to put it mildly, because there still aren’t that many iOS devs on Bluesky 😅 But as of today, it has 35 likes – only 50 likes less than the other Swift feed :]

Apart from the iOS dev feed, I’ve also made a more general macOS users feed and a couple of other feeds that were mostly a proof of concept / playground while building the service, but a lot of people seem to find them useful anyway, so I’ve left them running:

Skythread

The last one of my Bluesky-related projects, also with a “sky” in the name (most of the third party projects so far have either the word “blue” or “sky” as part of the name 😄). And this one is written in JavaScript for a change.

If you use Twitter and/or Mastodon a lot, you probably have the experience of reading some complicated thread and getting lost, not knowing who replies to whom or if you haven’t missed a whole part of the discussion. These two display branching out threads a bit differently – Twitter hides some of the branches, while Mastodon shows all direct and indirect replies in one flat list. In both cases, it’s not a perfect solution for reading some heated “hellthreads” that branch out endlessly. For me, a UI more like the one on Reddit would be ideal. (Bluesky has recently a thread view with limited nesting, as an experimental feature.)

So that’s what I’ve built, as a web tool. You enter a URL of the root of the thread on bsky.app, and it renders the whole thread as a tree. You can use the +/– buttons to collapse and expand parts of the tree, just like on Reddit, and if you log in, you can also click the heart icons below a comment to like it:

The initial version of Skythread required logging in first to see anything, but I’ve recently switched it to a different API that allows me to load whole threads without an access token. Note that the official Bluesky web app currently does not allow viewing any content unauthenticated – just like Twitter after the recent changes – so tools like Skythread, and other similar ones (e.g. Skyview) are the only way right now to share links to posts and threads with people who don’t have an account; but this is a temporary situation and Bluesky should be open to the world (for reading at least) in near future.

mackuba ∕ skythread

Thread viewer for Bluesky

One app to rule them all

So where can you find me now on social media? As you might have guessed from the earlier sections, I’m spending most of the time on Bluesky now; which may be a bit strange, because that’s not where most of my friends and follows from Twitter ended up. A large part of the iOS/Mac/Swift programming community has moved to Mastodon and stayed there, with some stubbornly sticking to Twitter or posting to both. Possibly also to Threads, which I don’t even have access to.

But there’s something about Bluesky and the AT Protocol that really draws me to it… I think it’s some combination of a nicer UI/UX, tech/architecture that I like more, a new community that is only just forming, and having this feeling like I’m blazing the trail, being able to build all the tooling that doesn’t exist yet. I like being part of something that’s being created around me, flying on that plane that’s being built in the air, watching the devs build it live and feeling like I’m part of it all. I enjoy being there, I really want it to succeed, and I want to help with that as much as I can.

So I have friends on all three platforms, and even though I spend most time on Bluesky, I check all three everyday, for slightly different content – Twitter for news, Mastodon for Swift programming, Bluesky for… dopamine? And since some people only follow me here and some only there, I end up manually cross-posting a lot of things to 2 or 3 websites.

Wouldn’t it be nice to have a tool, kind of like Buffer, that can let you post to Twitter, Mastodon and/or Bluesky in parallel? There doesn’t seem to be, so I’ve decided to build one myself :] This one isn’t available yet and it still needs a lot of work before I can call it an “MVP”, but it’s going to look something like this:

In the meantime, you can follow me here on any of these platforms – listed in the order of preference :)

Social media update - Elon's Twitter and Mastodon

2022-12-22T16:21:01Z

Update 01.03.2023: Updated Mastodon address - my previous instance has been unexpectedly shut down and I had to make a new account. I’ve decided to set up my own server to make sure it won’t happen again.

Update 09.11.2023: I made a follow-up post which talks about the social media related projects I’ve been working on this year, and about Bluesky, where I’m spending most of the time now.

This is just a small update about Twitter and Mastodon, since things have been… very unstable and chaotic in the last few weeks, as you’ve surely noticed if you log in to these even occassionally.

Twitter has been my internet home for over 13 years now. I started using it when my colleagues from Lunar Logic showed it to me, and especially in the recent years it’s been my main source of information and news. It’s where I went to keep track of what was happening in the Apple/Swift world, find useful tips about UIKit, SwiftUI or Xcode, follow the news, rumors and dramas on the Crypto Twitter, and find out every day what important thing was happening in the world, including following the Covid pandemic and the Russian invasion of Ukraine this year.

Like most of the people I’m following, I’m not very happy about Elon’s takeover and his actions, how he randomly makes changes to the rules based on his current mood, blocks journalists who write about him and how he fired or scared away most of the people who kept the site working. I’m worried about how the future looks for the platform, if Twitter will even exist in this form a year or two from now. I wish this all hadn’t happened, and I’m angry at the people who made it happen for their own gain.

But so far, Twitter is still working and is still a great place to get the news, tips and information about so many things. I’m not ready to give up on this site as long as the feed is loading and there are some tweets left to read.

I’ve been trying out Mastodon like everyone else and I slowly get more comfortable there, but it still feels a bit alien to me. It feels like when you move in to a new apartment and everything is different there than you’re used to, some things are missing, some things are better, some things are worse than in your old place, but a lot of your subconscious habits and muscle memory stop working. I had some ways of using Twitter that worked for me and a bunch of private tools I wrote for myself to help me automate some things - I will have to figure this all out again now.

So I am on Mastodon, if only because I don’t want to miss out on things, but I am still on Twitter and I’m planning to stay and keep posting there, as long as it stays usable. I will probably be posting more on Twitter than Mastodon, because I feel more comfortable there. I hope some of my friends and people I follow stay on the platform, or at least check in from time to time.

So here’s where you can find and follow me (updated 09.11.2023):