How to Build a Custom Labeler for Your Own Bluesky Community

Bluesky labelers let community managers and moderators add tags to posts or accounts without deleting content. A custom labeler can mark posts as misleading, flag accounts as trusted, or add context to discussions inside your community. This article explains how a labeler works, what you need to set one up, and the exact steps to deploy your own labeler service. You will learn how to configure moderation labels, publish a labeler feed, and avoid common setup mistakes.

What a Bluesky Labeler Does and Why You Need One

A labeler on Bluesky is a service that attaches labels to posts, accounts, or feeds. Labels are simple tags such as misleading, spam, trusted, or any custom string you define. When a label is applied, the Bluesky client shows a visual badge or hides the content based on the user’s moderation settings.

You need a labeler if your community has more than a few hundred members and you want consistent moderation without deleting posts. Labelers let you mark content without removing it, giving members the choice to see or hide labeled items. The labeler runs as its own service, separate from your personal account, so multiple moderators can manage labels through a shared tool.

Before you build a labeler, you need three things:

• A Bluesky account with a handle that will “own” the labeler. This can be a dedicated community account.
• A server or cloud instance where the labeler service will run. A small virtual machine with 1 GB of RAM and a public IP address is enough for most communities.
• Basic familiarity with the command line, Docker, or Node.js. The starter kit handles most of the complexity, but you need to edit configuration files and start the service.

Steps to Deploy a Custom Bluesky Labeler

Follow these steps to set up a labeler for your community. The instructions use the official Bluesky labeler starter kit available on GitHub. All commands assume a Linux server with Docker installed.

1. Create a Dedicated Bluesky Account for the Labeler
   Sign up for a new Bluesky account. Use a handle that represents your community, such as @mods.yourcommunity.bsky.social. This account will be the labeler’s identity. Do not use your personal account for the labeler.
2. Generate an API Key for the Labeler Account
   Log into the labeler account on Bluesky. Go to Settings > App Passwords. Click Add App Password. Name it labeler-service and copy the generated password. Store it securely.
3. Clone the Labeler Starter Kit
   On your server, run: git clone https://github.com/bluesky-social/labeler-starter-kit.git. Then change into the directory: cd labeler-starter-kit.
4. Configure the Labeler Settings
   Copy the example configuration file: cp config.example.yaml config.yaml. Open config.yaml in a text editor. Set the following values:

   – handle: The handle of your labeler account (e.g., mods.yourcommunity.bsky.social).
   – password: The app password you generated in step 2.
   – service: Set to https://bsky.social for the main Bluesky network.
   – labels: Define the labels your community will use. Each label needs a rkey (a short ID), a displayName, and a description. Example:

   labels:
     - rkey: misleading
       displayName: Misleading
       description: Content that contains false or misleading information
     - rkey: trusted
       displayName: Trusted Source
       description: Verified community member or reliable source

5. Build and Start the Labeler Service
   Run docker compose up -d. Docker will build the labeler image and start the service. The labeler listens on port 2583 by default. Verify the service is running with docker compose ps.
6. Register the Labeler with Bluesky
   Once the service is running, it needs to announce itself to the Bluesky network. Run: docker compose exec labeler node register.js. This script sends a registration request to the Bluesky relay. You should see a success message with your labeler’s DID.
7. Grant Moderator Access to Your Team
   Only the labeler account can apply labels by default. To let other community moderators use the labeler, you need to add their DIDs to the configuration. In config.yaml, add a moderators list:

   moderators:
     - did:plc:xxxxxxxxxxxxx
     - did:plc:yyyyyyyyyyyyy

   Find a user’s DID by visiting their profile on Bluesky and looking at the URL: bsky.app/profile/did:plc:xxxxxxxxxxxxx. Restart the service with docker compose restart after adding moderators.

8. Test the Labeler
   Open the Bluesky app. Search for your labeler account’s handle. You should see a labeler badge on the profile. Go to any post, click the three-dot menu, and select Report or label. If you are a moderator, you will see your custom labels in the list. Apply one and check that the post shows the label badge.

Common Mistakes and Limitations When Building a Labeler

Labeler service fails to register with Bluesky

If the registration step fails, check that your server’s firewall allows inbound connections on port 2583. Also verify that the handle and password in config.yaml are correct. The app password must be generated from the labeler account, not your personal account.

Custom labels do not appear in the Bluesky client

Bluesky caches label definitions for up to 30 minutes. After adding new labels to config.yaml, restart the service and wait. Also confirm that the labels are defined under the labels key in the YAML file and that the YAML indentation is correct. Use an online YAML validator if needed.

Moderators cannot see or apply labels

Only DIDs listed in the moderators section of config.yaml can apply labels through the labeler. Make sure you added the correct DID and restarted the service. Also check that the moderator is logged into Bluesky with the account that matches the DID.

Labeler stops working after a Bluesky update

The AT Protocol evolves frequently. Watch the Bluesky developer blog and the labeler starter kit repository for breaking changes. Update your local clone with git pull and rebuild the Docker image with docker compose up -d --build.

Labeler Options: Self-Hosted vs Managed Services

Item	Self-Hosted Labeler	Managed Labeler Service
Setup effort	Requires server, Docker, and CLI skills	Minimal; provided by a third party
Cost	Server hosting fees only	Monthly subscription or per-label fees
Customizability	Full control over label definitions and logic	Limited to predefined label types
Data privacy	All label data stays on your server	Label data is processed by the service provider
Maintenance	You handle updates, backups, and uptime	Provider handles maintenance

You can now deploy a custom Bluesky labeler for your community and give your moderators a shared tool to tag content without deleting it. After the labeler is running, explore the labeler’s moderation dashboard at http://your-server-ip:2583 to see applied labels in real time. For advanced use, look into the labeler’s webhook feature, which lets you trigger automatic label applications based on external data sources such as blocklists or community reports.