Get your bot handle

A name.bluesky.bot handle replaces your bot's default .bsky.social handle. It is free, and it works like any custom domain handle on Bluesky: Bluesky.bot serves your bot's DID at https://name.bluesky.bot/.well-known/atproto-did, which is the file Bluesky checks before it accepts the handle.

What you need

• Your own Bluesky account, to sign in as the creator. One creator can manage any number of bots.
• The bot's Bluesky account, and a way to sign in to it. Only an account you can sign in to can be added: nobody can claim a handle for someone else's account.

You never give your password to Bluesky.bot: both sign-ins go through Bluesky's own OAuth page. Signing in as yourself asks for the basic atproto access only. Adding a bot also asks for identity:handle, the permission to change that bot's handle, and nothing more.

1. Sign in

Open bluesky.bot and choose Sign in with Bluesky. You land on My bots.

2. Add the bot

On My bots, enter the bot's current handle (for example mybot.bsky.social) and choose Add a bot. Bluesky asks you to sign in, this time as the bot.

If your browser is already signed in to Bluesky as you, open the sign-in in a private window, or sign out of Bluesky first: the account that signs in is the one that gets added.

3. Pick a name

Open the bot from My bots, then the Handle tab. Names follow these rules, the same ones the server applies:

You can check a name before claiming it with the public API, no key needed:

curl https://bluesky.bot/api/v1/handles/weather/availability

Or from TypeScript:

// check-handle.ts: is a name free on bluesky.bot? Public API, no key needed.
const name = process.argv[2] ?? "weather";

const response = await fetch(
  `https://bluesky.bot/api/v1/handles/${encodeURIComponent(name)}/availability`,
);
if (response.status === 429) {
  const wait = response.headers.get("Retry-After");
  throw new Error(`Rate limited: retry in ${wait} s.`);
}
const result = (await response.json()) as {
  handle: string | null;
  available: boolean;
  reason: string | null;
};

console.log(
  result.available
    ? `${result.handle} is free.`
    : `${name} is not available (${result.reason}).`,
);

// Makes this file an ES module, which top-level await needs.
export {};

See the API reference for the possible reason values. From a terminal, the command-line tool does it too: bsbot check weather.

4. Claim and switch

Choose Claim Handle. Bluesky.bot saves the claim, then switches the bot's handle on Bluesky for you, using the identity:handle permission granted when you added the bot. When the switch is confirmed, the bot shows Live on Bluesky.

If Bluesky.bot cannot switch it (for example, the bot was added before the handle permission existed), the page asks you to add the bot again, or shows the steps to do it by hand:

1. Sign in to Bluesky as the bot, then open Settings → Account → Handle.
2. Choose I have my own domain, then the No DNS panel (file) option.
3. Enter name.bluesky.bot and verify: Bluesky.bot already serves the file Bluesky checks.

Then choose Check again on the bot's page.

Changing or releasing a handle

• Claiming another name frees the previous one.
• Release this handle gives it up. Bluesky.bot tries to switch the bot back to its previous Bluesky handle; if it cannot, pick another handle in the bot's Bluesky settings, or Bluesky shows it as invalid.
• A freed name stays blocked for everyone except you for a grace period (14 days by default), so nobody can impersonate your bot right away.

Next

• Verify a bot: what "Live on Bluesky" checks.
• List your bot in the directory from its Directory tab.