# Start from a template

Download a free Bluesky bot starter in TypeScript or Python: scheduled posts, the Automation label, opt-in safe replies and scoped listing sync.

[HTML version](https://bluesky.bot/docs/templates)

Download a small starter, inspect its code, and run it on your own computer or in your own GitHub repository. Bluesky.bot does not run it or store its app password.

## Choose a language

Both starters use the official/community SDKs shown below, a fixed dependency version and MIT-0 licensing. They include sample posts, tests and dormant workflows. These are downloads from this site; separate GitHub template repositories and bsbot init have not been released.

- **TypeScript**: [Download the starter](https://bluesky.bot/api/templates/typescript) · [Read the code](https://bluesky.bot/api/templates/typescript/source)
- **Python**: [Download the starter](https://bluesky.bot/api/templates/python) · [Read the code](https://bluesky.bot/api/templates/python/source)

## Try the dry run

Extract the archive. A dry run is the default and needs no credentials: it does not sign in or contact Bluesky. The README in each archive gives the complete commands.

```bash
# TypeScript: Node.js 24 + pnpm 12.18.0
cd bluesky-bot-typescript
pnpm install --frozen-lockfile
pnpm start
```

```bash
# Python 3.13
cd bluesky-bot-python
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python bot.py
```

## Publish from your own repository

Review posts.txt, create an app password while signed in as the bot, and set BLUESKY_HANDLE and BLUESKY_APP_PASSWORD as secrets in your own repository. Set DRY_RUN=false only when ready. The sample schedule runs every 30 minutes with no overlap. GitHub can delay schedules and disables public-repository schedules after 60 days without activity.

## Replies and rate limits

The first live run adds the Automation self-label with compare-and-swap, preserving your profile. Replies are off by default. If you enable them, only unread direct mentions and replies are considered; self-labelled bot authors, your own account, blocks and mutes are skipped. Five replies per run at most. A 429 or other failure stops the run; review a failed partial run before retrying.

## Sync your listing

Edit bluesky-bot.json yourself. A listing-only deploy token, ideally limited to this bot, goes in BSBOT_TOKEN; set BOT_DID too. The included workflow sends the creator-approved file through the HTTP listing API. No unpublished CLI command is required.

## Learn the pieces

- [Build a bot in TypeScript](https://bluesky.bot/docs/typescript-bot)
- [Build a bot in Python](https://bluesky.bot/docs/python-bot)
- [Schedule posts](https://bluesky.bot/docs/schedule-posts)
- [Automation and safe replies](https://bluesky.bot/docs/best-practices)
- [Explore the local Tracery playground](https://bluesky.bot/tools/tracery)
