Honkbot (Rust)

A single Bluesky bot that listens to the full firehose via Jetstream and replies to animal commands with random Flickr images.

Rewrite of bskybots/honkbot in Rust for reliability and performance.

A command only triggers a reply when it starts a post or is preceded by whitespace, so URLs like https://mysite.com/meow are ignored while i want to /hoot still works.

Container image

Published to ATCR — an OCI registry built on the AT Protocol:

atcr.io/goose.art/honkbot:latest

Single layer, ~48 MB, linux/amd64. .tangled/workflows/build.yaml builds and pushes it on every push to main.

Authentication

ATCR authenticates pulls, so log in first:

$ docker login atcr.io -u goose.art      # ATProto handle + app password
$ docker pull atcr.io/goose.art/honkbot:latest

Or install ATCR’s credential helper (curl -fsSL https://atcr.io/static/install.sh | sh), which uses an OAuth device flow instead of storing a password.

Anonymous pulls require the image’s storage hold to be public. This image currently lives on ATCR’s shared hold (did:plc:wnbpdx4bn5uts5yd2o2g3gnm), which is private; see Bring your own storage to publish from your own public hold.

Running the container

The image bundles the binary and the fallback_images/ tree, so it needs no volumes — only credentials through environment variables.

docker run

$ docker run -d \
    --name honkbot \
    --restart unless-stopped \
    -e BSKY_HANDLE=your-bot.bsky.social \
    -e BSKY_PASSWORD=your-app-password \
    -e FLICKR_KEY=your-flickr-api-key \
    atcr.io/goose.art/honkbot:latest

Docker Compose

docker-compose.prod.yml runs the bot alongside watchtower, which polls for new images every 60 seconds and restarts the container when latest moves:

$ docker login atcr.io -u goose.art   # once, so the pull and watchtower can authenticate
$ docker compose -f docker-compose.prod.yml up -d

Credentials go in a .env file next to the compose file (see .env.example). Watchtower reads the credentials from the Docker config.json that docker login writes — the compose file mounts it into the watchtower container at /config.json, so a single login covers both. Set DOCKER_CONFIG_FILE in .env if the file lives elsewhere (NAS paths often do).

To build the image locally instead of pulling, use docker-compose.yml (docker compose up --build).

Commands

Running from source

1. Copy .env.example to .env and fill in your credentials:

   • BSKY_HANDLE — your bot’s Bluesky handle
   • BSKY_PASSWORD — an app password for the bot account
   • FLICKR_KEY — a Flickr API key (get one here)

2. Seed fallback images (used when Flickr is down or rate-limited):

   $ ./seed_fallback_images.sh
   

   This downloads ~12 images per category into fallback_images/. They are committed so the container image ships with them; you can also add your own .jpg/.png/.webp files.

3. Build and run:

   $ cargo build --release
   $ ./target/release/honkbot
   

Tests live next to the code (cargo test) and cover the command-matching rules.

Features

• Single binary handles all 13 animal commands
• Jetstream WebSocket for efficient firehose consumption (only receives app.bsky.feed.post events)
• Automatic reconnection with cursor tracking on disconnect
• Bounded concurrency (10 concurrent reply tasks) to avoid flooding APIs
• Session refresh with automatic retry on auth failures
• Flickr fallback images — if Flickr is down or rate-limited, picks a random image from fallback_images/<command>/
• Image resizing for images over 1MB (Bluesky blob limit)
• Structured logging via tracing (set RUST_LOG=debug for verbose output)

Architecture

Jetstream (WSS) → match post text against triggers → spawn bounded task:
  1. Search Flickr for random animal image
  2. Download & resize if needed
  3. Upload blob to Bluesky
  4. Create reply post with image

Bring your own storage

The container image lives on ATCR, which stores image manifests as AT Protocol records in the owner’s PDS and layer blobs in a hold service (S3-compatible). Anonymous pulls are only served by holds with server.public: true; the shared hold used above is private.

To serve pulls without credentials:

1. Deploy a hold service with server.public: true (BYOS guide).
2. Point your ATCR profile at it by setting defaultHold in your io.atcr.sailor.profile record.
3. Push again (git push origin main) so new blobs land on the public hold.

The OCI annotations emitted by the build (org.opencontainers.image.*, io.atcr.readme) let ATCR populate this repository page from this README automatically.