← Learn

Learn

How bots work on Bluesky

A bot on Bluesky is an ordinary account run by a program. It has a DID, a handle and a PDS like any other account, and it posts by writing records to its repository. What makes it a bot is who runs it, and it can say so with the Automation label.

Last reviewed on November 14, 2026

There is no special kind of account for bots on Bluesky. A bot is a program that uses an ordinary account, and everything it does goes through the same protocol as the Bluesky app.

A bot is an ordinary account

Like any account, a bot has a DID, its permanent identifier, a handle that people read, and a PDS that hosts its repository. When it posts, likes or follows, it adds a record to that repository, exactly as the app does for a person. To the relay and the AppView, a bot's post is a record like any other.

The protocol's own bot tutorial starts the same way: create an account for the bot, then an app password for it.

How a bot posts

A bot talks to its own PDS over HTTPS. First it signs in, in one of two ways:

  • with an app password, a password made for one app, separate from the account's main password and revocable on its own. The protocol's documentation says single-purpose programs, such as bots and command-line tools, may sign in with a password, and an app password keeps the main one out of their code;
  • with OAuth, the standard sign-in of atproto apps, where the account grants access without sharing a password. Apps that sign people in are meant to use it.

Then it creates a record, such as a post in its app.bsky.feed.post collection. The PDS signs the change with the account's key and adds it to the repository, and from there the post takes the same journey as any other: relay, AppView, readers. The developer docs show the code in TypeScript and in Python.

Going deeper. A post is a call to com.atproto.repo.createRecord on the PDS, with a body like the one below. The PDS picks the record key, usually a TID made from the clock, and answers with the post's AT URI and its CID, the hash of that exact version.

json
{
  "repo": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
  "collection": "app.bsky.feed.post",
  "record": {
    "$type": "app.bsky.feed.post",
    "text": "Hello from a bot!",
    "createdAt": "2026-11-14T09:00:00.000Z"
  }
}

How a bot listens

Many bots only post, on a schedule. Others react: to a mention, a reply or a new follower, or to something happening anywhere on the network. There are two common ways to listen:

  • Notifications. The bot asks for its own notifications from time to time, the same list a person sees in the app, and answers the mentions and replies it finds. The protocol's bot tutorial works this way.
  • The firehose or Jetstream. A bot that watches the whole network, for example for posts with a keyword, reads a stream. The firehose of a relay is binary: its events are encoded in CBOR, and the records they carry are in DAG-CBOR. Jetstream sends the same changes as plain JSON over a WebSocket, filtered to what the bot asks for, which Bluesky recommends for most developers.

Both streams are public: reading them needs no account and no password. A bot only signs in to write.

Going deeper. Notifications come from app.bsky.notification.listNotifications on the AppView, through the bot's PDS. The firehose is com.atproto.sync.subscribeRepos on a relay. Jetstream can filter by collection, such as app.bsky.feed.post, and by account.

The bot loop

Put together, most bots run the same loop:

  1. Schedule or eventA timer, a mention, or a post seen in Jetstream.
  2. Bot codeRuns anywhere: a server, a laptop, a scheduled job.
  3. Its PDSSaves the post in the bot's repository.
  4. The networkThe relay and the AppView pass it on.
  5. ReadersSee it in their timelines, feeds and notifications.

Replies and mentions come back to the bot as notifications, and the loop starts again.

A bot's loop: a schedule or an event starts the bot's code, which writes to its PDS; the network carries the post to readers.

Each step is a separate piece. The bot's code can run anywhere, on a server, a laptop or a scheduled job, while its account and its posts live on its PDS.

Saying it is a bot

The protocol does not mark bots by itself: an account says that it is automated. There are three common ways, and they work best together:

  • The Automation label. In the Bluesky app, an account can turn it on in Settings → Account → Automation label. The app then shows the label next to the account's name, on its profile and its posts. Under the hood, it is the bot self-label of the account's profile record, which the protocol's bot tutorial recommends as a best practice.
  • The profile. A bio that says the account is automated, what it posts and who runs it.
  • The handle. A name that says "bot" before anyone opens the profile.

How people find a bot

People find a bot the way they find any account: in search, through replies and reposts, in custom feeds and lists, and in starter packs, the lists of recommended accounts and feeds that people make in the Bluesky app and share as a link.

The rules

Bots follow the same rules as everyone else, plus limits that matter more to them. This page does not restate them; read them at the source:

  • Bluesky's Community Guidelines, which apply on Bluesky's services to every account, automated or not, and its Terms of Service;
  • Bluesky's Developer Guidelines, for apps and services that talk to Bluesky's services, whose definition of spam includes automated or bulk interactions and spambots;
  • the rate limits of Bluesky's PDSes and services, which mostly affect prolific bots;
  • the best practices for bots, a checklist that links to Bluesky's rules.

How Bluesky.bot uses this

Bluesky.bot is made for bots. It gives each one a name.bluesky.bot handle, served from Bluesky.bot's domain, so the bot keeps its DID, its PDS and its code; it lists bots in a public directory; and its checkup reminds creators to turn on the Automation label. Its labeler also adds a bot label to accounts with a live *.bluesky.bot handle. What is a Bluesky bot?

Frequently asked questions

Does Bluesky allow automated accounts?
Yes. An automated account can post like any other, as long as it follows Bluesky's Community Guidelines and Terms of Service, respects its Developer Guidelines, which count automated or bulk interactions and spambots as spam, and stays within the rate limits. All are linked under "The rules" on this page.
Do bots need a special account?
No. A bot uses an ordinary account, usually one of its own rather than its creator's. It signs in with an app password or with OAuth, so the account's main password stays out of its code, and it can turn on the Automation label to show that it is automated.

Sources

The official pages this explanation relies on. They are in English.

Give your bot a recognisable handle

Bluesky.bot gives bot accounts a free name.bluesky.bot handle, proven to the whole network, and a place in the public bot directory.