hnmastodonbot (0.1.dev1+g19c6132f8)

Published 2026-01-09 13:27:30 +00:00 by cperrin

To install the package using pip, run the following command:

pip install --index-url  hnmastodonbot

For more information on the PyPI registry, see the documentation.

Reposts the top posts from news.ycombinator.com to mastodon

HNMastodonBot

A simple bot that fetches top stories from Hacker News and posts them to Mastodon.

Features

Fetches top stories from Hacker News at regular intervals. The number of stories is configurable (default is 10).
Posts the story title and URL to Mastodon.
Automatically posts a reply with a link to the Hacker News comments.
Tracks posted stories to avoid duplicates.
Supports Docker deployment.

Requirements

Python 3.10+
uv (recommended) or pip

Configuration

The bot is configured using environment variables. Secret values can also be provided via files by appending _FILE to the environment variable name.

Environment Variable	Description
`MASTODON_INSTANCE_URL`	The base URL of your Mastodon instance (e.g., `https://mastodon.social`).
`MASTODON_ACCESS_TOKEN`	Access token for the Mastodon account.
`MASTODON_COMMENTS_ACCESS_TOKEN`	Access token for posting comments (can be the same as above).
`TRACKING_FILE`	(Optional) Path to the file where posted story IDs are stored. Defaults to `tracking.pkl`.
`HASHTAG_CONFIG`	(Optional) Path to the JSON file containing hashtag mappings. Defaults to `hashtags.json`.
`TOP_STORIES_LIMIT`	(Optional) The number of top stories to consider. Defaults to `10`.

Usage

Command Line Arguments

--dry-run: Simulate actions without posting to Mastodon or updating the tracking file.
--limit: Set the number of top stories to consider. Overrides TOP_STORIES_LIMIT environment variable.

Local Execution

Using uv:

export MASTODON_INSTANCE_URL="https://your.instance"
export MASTODON_ACCESS_TOKEN="your_token"
export MASTODON_COMMENTS_ACCESS_TOKEN="your_token"
uv run main.py

Docker

You can build and run the bot using Docker:

docker build -t hnmastodonbot .
docker run -e MASTODON_INSTANCE_URL="..." \
           -e MASTODON_ACCESS_TOKEN="..." \
           -e MASTODON_COMMENTS_ACCESS_TOKEN="..." \
           hnmastodonbot