bsky-dice

Bluesky dice bot. Mention it with standard dice notation and it replies with results.

Listens for @mentions via Spacedust (a Bluesky firehose relay), parses dice notation with pyhedrals, and replies.

Supported notation

Notation	What it does
1d20	Roll one 20-sided die
2d6+3	Roll two 6-sided dice, add 3
4d6kh3	Roll 4d6, keep highest 3
2d20kl	Roll 2d20, keep lowest
1d6!	Exploding die
(2d6+2)+1d100	Compound expressions

Mention the bot with help to get this list in a reply.

Setup

Prerequisites

• uv for dependency management
• A Bluesky account with an App Password

Configuration

cp .env.example .env

Edit .env with your credentials:

Variable	Required	Default	Description
BSKY_HANDLE	Yes	—	Bot's Bluesky handle
BSKY_PASSWORD	Yes	—	App password (not main password)
PDS_URL	No	https://bsky.social	PDS base URL
MAX_DICE	No	100	Max dice per expression
MAX_SIDES	No	10000	Max sides per die
DRY_RUN	No	false	Log replies instead of posting (true/yes/1)

Running

Local with uv

# Install dependencies
uv sync

# Run the bot
uv run python -m src

# Dry run (logs replies, doesn't post)
DRY_RUN=true uv run python -m src

Docker Compose (production)

# Build and start
docker compose up -d

# View logs
docker compose logs -f

# Restart
docker compose restart

# Stop
docker compose down

Docker manually

# Build
docker build -t bsky-dice .

# Run
docker run --env-file .env bsky-dice

Pull from Forgejo registry

docker pull git.brads.house/brad/bluesky-dicebot:latest
docker run --env-file .env git.brads.house/brad/bluesky-dicebot:latest

The registry image is built for linux/arm64.

Testing

# Run all 124 tests
uv run pytest -v

# Quick summary
uv run pytest --tb=short

# Run a specific test file
uv run pytest tests/test_dice.py -v

CI/CD

Forgejo Actions workflows in .forgejo/workflows/:

1. test.yml — Runs pytest on every push to main and on PRs. On success, triggers the Docker build.
2. build.yml — Builds the arm64 Docker image and pushes to the Forgejo registry at git.brads.house/brad/bluesky-dicebot.

Requires a REGISTRY_TOKEN secret on the repo for registry login and workflow dispatch.