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

Install

pip install zhongli

Or from source:

git clone https://forge.marvin8.zone/marvin8/dujiangyan.git
cd zhongli
uv sync
uv run zhongli

Container

Images are published to registry.marvin8.zone/marvin8/zhongli on every release.

Volumes

Config for container use

Add cache_db_path so the database lands on the persistent volume:

run_continuously = true
delay_between_posts = 300
cache_db_path = "/app/data/cache.db"

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

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

Run as a daemon

podman run -d \
  -v ./config.toml:/app/config/config.toml:ro \
  -v zhongli-data:/app/data \
  registry.marvin8.zone/marvin8/zhongli

Run as a one-shot / cron job

podman run --rm \
  -v ./config.toml:/app/config/config.toml:ro \
  -v zhongli-data:/app/data \
  registry.marvin8.zone/marvin8/zhongli \
  /app/config/config.toml --max-posts 10

The container starts as root, fixes config permissions to 0600, then drops to an unprivileged zhongli user (UID 1000) before running.

Health check

The image includes a HEALTHCHECK that passes as long as /app/data/zhongli.log was written within the last 15 minutes. To activate it, mount a logging config that writes to that path:

logging-config.toml:

[[handlers]]
sink = "sys.stdout"
format = "{message}"
level = "INFO"

[[handlers]]
sink = "/app/data/zhongli.log"
rotation = "1 day"
retention = 3
level = "DEBUG"
serialize = true

Then pass it to zhongli:

podman run -d \
  -v ./config.toml:/app/config/config.toml:ro \
  -v ./logging-config.toml:/app/config/logging-config.toml:ro \
  -v zhongli-data:/app/data \
  registry.marvin8.zone/marvin8/zhongli \
  /app/config/config.toml --logging-config /app/config/logging-config.toml

If your delay_between_posts exceeds 10 minutes, override the healthcheck interval to avoid false negatives: add --health-interval=<2× delay> to your podman run invocation, or set HealthInterval in your Quadlet unit.

Quadlet (systemd)

Quadlet is the recommended way to run zhongli as a persistent rootless systemd service (requires Podman ≥ 4.4).

Create ~/.config/containers/systemd/zhongli.container:

[Unit]
Description=Zhongli Fediverse reblog bot

[Container]
Image=registry.marvin8.zone/marvin8/zhongli:latest
AutoUpdate=registry
Volume=%h/.config/zhongli/config.toml:/app/config/config.toml:ro
Volume=%h/.config/zhongli/logging-config.toml:/app/config/logging-config.toml:ro
Volume=zhongli-data.volume:/app/data
Exec=/app/config/config.toml --logging-config /app/config/logging-config.toml
HealthOnFailure=restart

[Service]
Restart=on-failure
RestartSec=30s

[Install]
WantedBy=default.target

Create ~/.config/containers/systemd/zhongli-data.volume:

[Volume]

Then enable and start:

systemctl --user daemon-reload
systemctl --user start zhongli
systemctl --user status zhongli

Logs via: journalctl --user -u zhongli -f

Author Opt-Out Signals

Zhongli respects the following Fediverse opt-out conventions. When detected, the post is permanently rejected (not retried):

These checks run on every post before the duplicate-attachment scan.

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.

cache.db (attachment deduplication database) is also created with 0600 permissions. If the file already exists with looser permissions, zhongli logs a warning with a chmod 600 hint.

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)

Privacy / Federation behaviour

When Zhongli looks up a post by URL, it first queries its home instance's local index without triggering any outbound federation. If the post is already known (e.g. it appeared in a followed account's timeline), no federation request is made.

If the post is not in the local index, Zhongli falls back to a federated lookup (resolve=True). This causes the home instance to fetch the post directly from the remote instance. Remote instance administrators can observe this request, which reveals that your instance is interested in that post. This is an inherent consequence of ActivityPub federation and cannot be avoided when a post is not yet locally cached.

Operator note: If you are operating Zhongli on a small or single-user instance, remote administrators may be able to infer your curation patterns from federation traffic.

License

GNU AGPL v3.0

Support

• Buy me coffee
• Monero: 88xtj3hqQEpXrb5KLCigRF1azxDh8r9XvYZPuXwaGaX5fWtgub1gQsn8sZCmEGhReZMww6RRaq5HZ48HjrNqmeccUHcwABg