zhongli 2026.5.166

Bot to boost/reblog posts with specified tags

Zhongli

Automatically boost/reblog Fediverse posts. Formerly Fedibooster.

Overview

Zhongli consumes pre-filtered posts from FenLiu's queue and automatically reblogs them to your Fediverse account. FenLiu handles the heavy lifting (filtering, spam detection, curation); Zhongli handles the reblogging and duplicate prevention.

FenLiu configuration is required. There is no legacy mode.

Status

Phase	Status	Notes
1: Infrastructure	✅ Complete	FenLiu client, models, tests
2: FenLiu-Only Mode	✅ Complete	ReblogService, queue polling, attachments
3: Validation Optimization	✅ Complete	MinimalValidator, pre-filtered posts
4: Documentation	✅ Complete	FenLiu-only, updated config
5: UX Polish	⏳ Optional	Metrics, dry-run, progress indicators

Install

pip install zhongli

Or from source:

git clone https://codeberg.org/marvinsmastodontools/zhongli.git
cd zhongli
uv sync
uv run zhongli

Configuration

Zhongli requires FenLiu and a Fediverse account:

[fediverse]
domain_name = "mastodon.social"
api_token = "your-token"

[fenliu]
base_url = "https://fenliu.example.com"
api_key = "your-api-key"

# Optional
run_continuously = false
delay_between_posts = 300
reblog_sensitive = false
max_reblog = 5
# allow_insecure_http = false  # set true only if FenLiu is on a local network without HTTPS

Configuration explained:

• [fediverse] - Your Mastodon/Pixelfed/Misskey account
• [fenliu] - Connection to FenLiu queue service
• run_continuously - Keep polling or exit after max_reblog posts
• delay_between_posts - Seconds between reblogs (0 for no delay)
• reblog_sensitive - Whether to boost sensitive/NSFW posts
• max_reblog - Stop after boosting N posts (0 for unlimited)
• fenliu.skip_missing_alt_text - Skip posts where any attachment lacks alt text (default: false)
• fenliu.allow_insecure_http - Allow an HTTP base_url for private local-network deployments where HTTPS is not feasible. Never enable this in production. http://localhost and http://127.0.0.1 are always exempt and do not require this flag (default: false)

Security: config.toml is created with 0600 permissions (owner read/write only). If you copy or restore the file from another location, re-apply: chmod 600 config.toml. Zhongli will refuse to start if it detects the file is readable by group or world.

fenliu.base_url must use https:// to protect the API key in transit. The only exceptions are http://localhost and http://127.0.0.1 (always permitted for local development), and any URL when allow_insecure_http = true is set explicitly for private-network deployments.

Debug log: When using --logging-config logging-config.toml, debug output is written to ~/.cache/zhongli/zhongli.log. This directory is created automatically and is accessible only by the owner. Never configure /tmp/ as a log destination — it is world-readable.

Usage

zhongli config.toml                 # Run with config file
zhongli config.toml --max-posts 10  # Override max posts
zhongli --help                      # Show all options

How It Works

1. Poll FenLiu Queue - Get next curated post
2. Validate - Quick checks (has content, not a reply, respects sensitive setting)
3. Find on Fediverse - Search for post by URL
4. Check for Duplicates - Compare attachments (URL, hash, perceptual)
5. Reblog - Boost to your account with circuit breaker protection
6. Report Feedback - ACK (success), NACK (transient error), ERROR (permanent)
7. Repeat - Until configured limit or continuous mode ends

Features

• FenLiu Integration - Consume pre-curated, pre-filtered posts
• Duplicate Prevention - Three-layer attachment detection (URL, SHA-256, dHash)
• Reliable Reblogging - Circuit breaker pattern, retry logic, error classification
• Smart Feedback - ACK/NACK/ERROR reporting to FenLiu
• Production Ready - 132 tests, full type checking, comprehensive error handling

Development

uv sync              # Install deps
prek run --all-files # Pre-commit checks
uv run tryke test    # Run tests (132 tests; from repo root: uv run tryke test --root packages/zhongli)
nox                  # Full CI simulation

Recent Work

• ✅ Phase 3: Validation optimized for FenLiu pre-filtered posts
• ✅ Phase 2: Full FenLiu-only mode operational
• ✅ Phase 1: FenLiu infrastructure complete with 132 tests
• ✅ Attachment deduplication system (URL, content hash, perceptual hash)
• ✅ Circuit breaker pattern integrated
• ✅ Complete feedback mechanism (ACK/NACK/ERROR)

Next Steps

Phase 5 - UX polish and observability (metrics, dry-run mode, progress indicators)

License

GNU AGPL v3.0

Support

• Buy me coffee
• Monero: 88xtj3hqQEpXrb5KLCigRF1azxDh8r9XvYZPuXwaGaX5fWtgub1gQsn8sZCmEGhReZMww6RRaq5HZ48HjrNqmeccUHcwABg