| name | kb-piefed |
| description | Background knowledge about PieFed, the federated link aggregation and discussion platform (Python-based Reddit/Lemmy alternative in the Threadiverse). Covers PieFed's tech stack (Python/Flask, PostgreSQL, Celery/Redis, htmx, Jinja2, AGPL-3.0), the Lemmy-compatible ActivityPub implementation (Community as Group, Post as Page, Comment as Note, Like/Dislike voting, Announce relay pattern, ChatMessage for DMs), the unique Feed actor type (FEP-1d80 for federated multi- community collections), private/anonymous voting via proxy user profiles, additional activity types (EmojiReact, PollVote, ChooseAnswer for Q&A mode, Event objects with startTime/endTime), the 95%-Lemmy-compatible REST API (/api/alpha/ with Swagger docs, enabling Voyager/Interstellar/Blorp/Summit mobile apps), custom JSON-LD extensions (genAI, nsfl, flair, postingWarning, interactionPolicy, lemmy:tagsForPosts compatibility), the federation architecture (Celery async processing, Redis dedup with 90s TTL, RSA-SHA256 HTTP signatures, LD signature fallback, batched federation between PieFed instances, retry queue), moderation tools (reputation/attitude tracking, 3000+ domain blocklist, AI content labeling, 4chan screenshot detection, authoritarian inoculation, web of trust, community-level downvote controls), content types (link/text/image/video posts, polls, events, wikis, emoji reactions, quote posts, cross-post deduplication with merged comments, scheduled posts), community features (local-only communities, private communities, NSFW/NSFL/genAI flags, moderator recruitment via newModsWanted, post flair via tagsForPosts), and interoperability with Lemmy, Mastodon (mention-to-follow, poll interop, quote-boost), PeerTube (channel following, embedded player), and Mbin/Kbin (accepts both attributedTo and moderators for mod lists). Load when the user asks about PieFed federation; implementing a PieFed- compatible ActivityPub server; how PieFed communities work; PieFed's voting system and private votes; PieFed's Feed actor; PieFed's API and mobile app compatibility; interoperating with PieFed instances; PieFed's moderation features; PieFed vs Lemmy differences; or the Threadiverse ecosystem.
|
| user-invocable | false |
PieFed โ Complete Reference
Overview
PieFed is a free, open-source, federated link aggregation and discussion
platform โ a Python-based alternative to Reddit and Lemmy in the
Fediverse "Threadiverse." Created by Rimu Atkinson (Christchurch, New
Zealand) with the first code published July 28, 2023 and the flagship
instance (piefed.social) launched January 4, 2024. Licensed AGPL-3.0.
PieFed federates via ActivityPub using the same Group/Page/Note model as
Lemmy, making it fully interoperable with Lemmy, Mbin, and the wider
Fediverse. Its distinguishing features are: cross-post deduplication
with merged comments, federated Feeds (multi-community collections
via a custom Feed actor type), private/anonymous voting via proxy
user profiles, trust & safety as a first-class design concern
(reputation tracking, 3,000+ pre-blocked disinformation domains, AI
content filtering), and a deliberately simple Python/Flask codebase
designed for contributor accessibility.
The name "PieFed" is a portmanteau of "Python" and "Federation." The
repository is named "pyfedi" and hosted on Codeberg (not GitHub). As of
early 2026: 75+ instances, ~2,000 MAU, 82,571 lines of code, 62
contributors. "Very High Activity" on Open Hub.
1. Technology Stack
| Component | Technology |
|---|
| Backend language | Python (3.9+, ~70% of codebase) |
| Web framework | Flask |
| Frontend | htmx + vanilla JavaScript + Bootstrap CSS |
| Template engine | Jinja2 |
| Database | PostgreSQL 17 |
| ORM | SQLAlchemy (Flask-SQLAlchemy) |
| Migrations | Alembic (flask db upgrade) |
| Task queue | Celery with Redis broker |
| Cache | Redis 6.2 (optional) |
| Application server | Gunicorn |
| Real-time notifications | FastAPI + Uvicorn (separate service) |
| Linting | Ruff |
| i18n | Babel |
| Deployment | Docker (5-service compose), bare metal, YunoHost |
| License | AGPL-3.0 |
Design philosophy: "Clean, simple code" with "no fancy design patterns
or algorithms." Only requires Python + PostgreSQL; Redis is optional.
Dramatically lighter resource usage than Lemmy โ one user reported
server load of ~1 vs Lemmy's ~12 on identical hardware.
2. ActivityPub Object Type Mapping
| PieFed Concept | ActivityPub Type | Notes |
|---|
| Community | Group | Relay actor; Announces content to followers |
| User | Person | Creates content, moderates |
| Bot | Service | Bot accounts |
| Feed | Feed | PieFed extension (FEP-1d80); federated multi-community collection |
| Post | Page | Primary post type, mandatory title (name) |
| Article | Article | Long-form content |
| Link post | Link | URL submissions |
| Comment | Note | Tree structure via inReplyTo |
| Poll | Question | oneOf/anyOf choices, up to 15 options |
| Event | Event | startTime, endTime, timezone, participantCount |
| Video | Video | PeerTube video embeds |
| Direct message | ChatMessage | Private user-to-user |
3. Communities as Group Actors
Communities are Group actors with their own inboxes, following the
same Announce relay pattern as Lemmy โ all content flows through the
community actor and is wrapped in Announce for distribution to
subscribers across instances.
Community-Specific Attributes
| Attribute | Description |
|---|
sensitive | NSFW flag |
nsfl | Not-safe-for-life flag (separate from NSFW) |
genAI | AI-generated content flag |
postingRestrictedToMods | Only moderators can post |
newModsWanted | Community is seeking moderators |
privateMods | Moderator list is hidden |
defaultPostType | Default content type for new posts |
questionAnswer | StackOverflow-style Q&A mode enabled |
moderators | OrderedCollection of moderators |
featured | Pinned posts collection |
tagsForPosts | Available flair/tag options (Lemmy-compatible) |
Moderator Attribution
PieFed accepts both attributedTo (Lemmy/Mbin style) and
moderators (Kbin style) for moderator lists, improving cross-platform
compatibility.
Community Types
- Federated (default): Full ActivityPub federation
- Local-only: Visible only on the home instance, no federation
- Private (v1.6+): Invitation-only, no federation, posts visible
only to members
4. Voting โ Like, Dislike, and Private Votes
PieFed uses Like (upvote) and Dislike (downvote) activities, same
as Lemmy. However, PieFed adds a private/anonymous voting system
that is unique in the Threadiverse.
Private Voting Mechanism
Users have two profiles: a main profile (for posting) and an
anonymous proxy profile (no name, avatar, or bio) used exclusively
for voting. When "Vote privately" is enabled:
- Votes sent to Lemmy/Mbin instances use the anonymous proxy profile
- New accounts have private voting enabled by default
- Votes can also be fully local (not federated at all)
Community-Level Vote Controls
- Moderators can restrict downvoting to subscribed members only
- Downvoting can be restricted to "trusted" instances (a third tier
between full federation and defederation)
- Communities can disable downvotes entirely
- "Low quality" communities (e.g., memes) don't award karma for upvotes
Reputation Tracking
- "Attitude" metric: tracks ratio of downvotes to upvotes per user;
flags excessive downvoters
- Comments scoring -10 or below are auto-collapsed
- Users with negative karma get red warning icons next to names
(double red for severely negative)
- New accounts (first 7 days) display a special indicator
5. The Feed Actor (FEP-1d80)
PieFed introduces a custom Feed actor type โ a federated equivalent
of Reddit's multi-reddits. This is defined in FEP-1d80.
A Feed is an ActivityPub actor of type Feed that aggregates multiple
communities (Group actors) into a single subscribable collection. Feeds
can include communities from any federated instance, PeerTube channels,
and Mastodon accounts.
- Feeds can be public (discoverable, subscribable) or private
- Feed actors are discoverable via WebFinger
- Users on remote PieFed instances can subscribe to a Feed like any
other actor
- Feeds are managed via
Add/Remove activities to add/remove
communities
This is a PieFed-specific extension โ Lemmy and Mbin do not support
the Feed actor type, though the FEP is open for adoption.
6. Full Activity Reference
Incoming Activities
| Activity | Purpose |
|---|
Follow | Subscribe to community/feed |
Accept / Reject | Subscription response |
Create | New post, comment, chat message, poll |
Update | Edit post/comment, update community profile |
Delete | Remove post, comment, PM, feed |
Like | Upvote |
Dislike | Downvote |
EmojiReact | Custom emoji reaction (unicode or :name: format) |
PollVote | Vote in a poll |
ChooseAnswer | Mark comment as answer (Q&A mode) |
Add | Add moderator, sticky post, add community to feed |
Remove | Remove moderator, unsticky post, remove from feed |
Lock | Lock post or comment (including children) |
Flag | Report content |
Announce | Boost/share (wraps other activities) |
Undo | Reverse any previous activity |
Community โ Followers
| Activity | Purpose |
|---|
Accept{Follow} | Automatic response to Follow |
Announce{*} | Rebroadcast received activities to all followers |
Community outboxes serve Announce(Create(Page)) activities even for
non-local posts, functioning as content relays.
7. JSON-LD Context and Extensions
Context
[
"https://www.w3.org/ns/activitystreams",
"https://w3id.org/security/v1"
]
Lemmy-Compatible Extensions
| Property | Used on | Description |
|---|
tagsForPosts | Group | Available flair/tag options (Lemmy CommunityTag) |
postingRestrictedToMods | Group | Restricted posting |
language | Page, Note | Language metadata (identifier + name) |
PieFed-Specific Extensions
| Property | Used on | Description |
|---|
genAI | Group, Page | AI-generated content flag |
nsfl | Group, Page | Not-safe-for-life flag |
flair | Note | User flair (custom extension on comments) |
postingWarning | Group | Contextual warning above comment form |
interactionPolicy | Page | Interaction restrictions |
newModsWanted | Group | Community seeking moderators |
questionAnswer | Group | Q&A mode enabled |
8. Federation Architecture
Activity Processing Flow
- Parse JSON request body
- Check federation pause status (normal / overload / permanently closed)
- Extract actor and validate HTTP signature
- Deduplicate via Redis (activity IDs stored with 90-second TTL)
- Route to handler based on activity type
- Process asynchronously via Celery task
HTTP Signatures
| Aspect | Detail |
|---|
| Algorithm | RSA-SHA256 (also accepts hs2019) |
| Key size | 2048-bit RSA |
| Signed headers | (request-target), Host, Date, Digest, Content-Type, Accept |
| Date tolerance | 3,600 seconds (1 hour) |
| Fallback | LD signatures via URDNA2015 normalization |
| Key cache | Up to 1,000 entries |
Reliability
- Failed deliveries enter a retry queue with retries over several days
- Batched federation between PieFed instances reduces load
- Redis-based locking minimizes database deadlocks
- Federation can be paused during overload conditions
Key Endpoints
| Path | Purpose |
|---|
/.well-known/webfinger | User, community, and feed discovery |
/.well-known/nodeinfo | NodeInfo schema links |
/nodeinfo/2.0, /nodeinfo/2.1 | Server stats and protocol info |
/u/<actor> | User actor (content-negotiated JSON/HTML) |
/c/<actor> | Community actor |
/inbox | Shared inbox |
/site_inbox | Site-level inbox |
/api/v1/instance | Mastodon-compatible instance info |
9. REST API
PieFed's API is intentionally "95% the same as the Lemmy API" to
enable reuse of Lemmy's mobile app ecosystem.
| Aspect | Detail |
|---|
| Base path | /api/alpha/ |
| Documentation | Swagger at /api/alpha/swagger |
| Total endpoints | 100+ |
| Rate limiting | Applied to creation endpoints |
Compatible Mobile Apps
Voyager, Interstellar (Android/iOS/Linux/Windows), Blorp (iOS),
Summit, with Boost and Photon in development.
Endpoint Categories
- Site (5): instance info, configuration
- Communities (17): CRUD, flair, bans, moderation
- Feeds (3): create, edit, list
- Posts (18): CRUD, polls, flair, voting
- Comments (13): CRUD, answer marking
- Private messages (8): send, read, delete
- Users (20): profiles, notifications, flair, bans
- Search (4): content discovery
- Images (4): upload, manage
- Admin (2): site management
Notable Unique Endpoints (beyond Lemmy)
/post/poll_vote โ poll voting/comment/mark_as_answer โ Q&A answer selection/feed/* โ Feed (multi-reddit) management/community/flair/* โ flair management/user/set_flair โ user flair
10. Moderation and Trust & Safety
PieFed was designed with safety as a first-class concern, drawing
inspiration from the Mastodon Covenant and "nudge theory."
Reputation System
- Karma tracking with sortable low-karma account lists
- "Attitude" metric: percentage of downvotes vs upvotes per user
- Visual indicators: red icons for negative karma, double-red for
severe, special icon for accounts < 7 days old
- Auto-collapse for comments at -10 or below
Content Filtering
- 3,000+ pre-loaded domain blocklist (disinformation, conspiracy,
fake news sites)
- 4chan screenshot detection via image recognition (auto-reported)
- AI content labeling: posts/communities tagged as AI-generated;
users can hide all AI content like NSFW
- NSFW and NSFL as separate flags
- Keyword filtering: user-configurable
- Bot content filter: single checkbox
Admin Tools
- Ban / Ban + Purge on user profiles
- IP-based ban evasion detection
- Username keyword filtering (blocks e.g. "1488")
- Web of trust: follow another instance's blocklist automatically
- Registration approval queue
- "Authoritarian Inoculation" feature with default blocks on known
extremist instances
Community-Level Moderation
- Per-community downvote policies
- Comment and post locking
- Post approval workflow (optional pre-publication review)
- Contextual warnings above comment forms
- Searchable moderation log
- Federated community bans
newModsWanted flag for moderator recruitment
11. Content Types
| Type | Details |
|---|
| Link posts | URL submissions |
| Text posts | Markdown body |
| Image posts | With alt text; width control via  |
| Video posts | Direct upload (v1.5+, admin-configurable) |
| Polls | Question with oneOf/anyOf, up to 15 options, Mastodon-compatible |
| Events | Time, timezone, location, participant count |
| PeerTube videos | Embedded player, auto-import from channels |
| Cross-posts | Deduplicated with consolidated comment views |
| Scheduled posts | With timezone support |
| Wiki pages | Per-community editable wikis |
| Emoji reactions | Unicode and custom (:piefed:), federated as Likes for Lemmy compat |
| Quote posts | v1.6+, Mastodon quote-boost interop |
| StackOverflow Q&A | Comments markable as answers via ChooseAnswer |
| Spoilers | Flair-based with image blurring + inline spoiler text |
12. Interoperability
Lemmy
- Fully compatible: Group communities, Page posts, Note comments,
Like/Dislike votes, Announce relay
- API is 95% Lemmy-compatible (mobile apps work)
- Shared extensions:
tagsForPosts, CommunityTag
- Limitation: polls and events cannot be posted TO Lemmy communities
(prevented in PieFed's code to avoid errors)
- Community outboxes follow Lemmy's
Announce(Create(Page)) pattern
Mastodon
- Users follow PieFed communities by mentioning them
- First paragraph becomes post title; rest becomes body
- Works: hashtags, images, alt text, videos, NSFW, polls, markdown,
mentions, comments, editing, likes, boosts
- Poll voting is bidirectional
- Quote-boost interop (v1.6+)
/api/v1/instance Mastodon-compatible endpoint
PeerTube
- Channels can be followed directly from PieFed
- Videos arrive with embedded player
- New channels auto-import 10 recent videos
- Posts restricted to channel owners
Mbin / Kbin
- Full community federation
- PieFed accepts Kbin's
moderators property alongside Lemmy's
attributedTo
Known Limitations
- "Discoverability between PieFed and other parts of the Fediverse is
limited"
- Markdown variants differ slightly from Lemmy's
- Remote Mastodon
Announce activities without full inlined objects
are logged but skipped
13. Installation and Deployment
Bare Metal
git clone https://codeberg.org/rimu/pyfedi.git
python -m venv venv && source venv/bin/activate
pip install wheel && pip install -r requirements.txt
cp env.sample .env # configure SECRET_KEY, DATABASE_URL, etc.
flask db upgrade && flask init-db
gunicorn -b 0.0.0.0:5000 pyfedi:app
Setup reported to take "within half an hour."
Docker (5 services)
| Service | Purpose |
|---|
db | PostgreSQL 17 |
redis | Redis 6.2 |
celery | Celery worker for async federation tasks |
app | Flask/Gunicorn web app (port 8030) |
piefed_notifs | FastAPI/Uvicorn real-time notifications (port 8040) |
Other Options
- YunoHost: available in app store (v1.4+)
- Managed hosting: fedihost.co (beta), Elest.io
- S3 storage: Cloudflare R2, Wasabi, Backblaze B2 for media and
post archival
Scaling (piefed.social reference: 8-core, 16GB, ~1000 MAU)
- PostgreSQL:
shared_buffers=6GB, effective_cache_size=9GB,
max_connections=300
- DB pool:
POOL_SIZE=30, MAX_OVERFLOW=70
- Nginx caching recommended (RAM-backed
/dev/shm/nginx)
- Post archival to S3 reduces database size over time
14. Codebase Structure
pyfedi/
โโโ app/
โ โโโ activitypub/ # Federation (routes, signatures, util, actor)
โ โโโ admin/ # Admin panel
โ โโโ api/alpha/ # Lemmy-compatible REST API
โ โโโ auth/ # Authentication
โ โโโ chat/ # Real-time chat
โ โโโ community/ # Community management
โ โโโ feed/ # Feed (multi-reddit) management
โ โโโ post/ # Post handling
โ โโโ search/ # Search
โ โโโ shared/tasks/ # Celery async tasks (adds, blocks, deletes,
โ โ # flags, follows, groups, likes, locks,
โ โ # notes, pages, removes, users, maintenance)
โ โโโ plugins/ # Plugin system
โ โโโ tag/ # Hashtag management
โ โโโ models.py # All DB models (209KB single file)
โ โโโ inoculation.py # Anti-propaganda feature
โ โโโ constants.py
โโโ migrations/ # Alembic migrations
โโโ tests/
โโโ docs/ # Developer docs, AP examples, ERD
โโโ compose.yaml # Docker Compose (5 services)
โโโ pyfedi.py # Entry point
โโโ FEDERATION.md # Federation documentation
โโโ CONTRIBUTING.md
Key namespaces: app.activitypub, app.api.alpha, app.community,
app.post, app.feed, app.shared.tasks
15. PieFed vs Lemmy โ Key Differences for Implementers
| Aspect | PieFed | Lemmy |
|---|
| Language | Python/Flask | Rust/Actix-web |
| Resource usage | ~1 load avg | ~12 load avg (same hardware) |
Feed actor type | Yes (FEP-1d80) | No |
| Private voting | Proxy user profiles | All votes public/federated |
| Cross-post dedup | Merged comment views | Separate posts |
| AI content flag | genAI property | No |
| NSFL flag | Separate from NSFW | No (NSFW only) |
EmojiReact | Yes (federated as Likes to Lemmy) | No |
ChooseAnswer | Yes (Q&A mode) | No |
Event objects | Yes | No |
PollVote | Yes (Mastodon-compatible) | No native polls |
| Flair federation | flair on Note + tagsForPosts | tagsForPosts only |
| API path | /api/alpha/ | /api/v3/ |
| API compatibility | 95% Lemmy-compatible | โ |
| JSON-LD processing | Plain JSON (no expansion) | Plain JSON (no expansion) |
16. Common Implementation Mistakes
-
Assuming PieFed is a Lemmy fork: PieFed is a completely separate
Python codebase, not a Rust fork โ protocol-compatible but
architecturally different
-
Not handling the Feed actor type: PieFed federates Feed
actors via WebFinger; other software should treat unknown actor types
gracefully rather than erroring
-
Expecting public votes: PieFed defaults to private voting โ vote
activities may come from anonymous proxy profiles or not at all.
Do not assume vote counts match federated Like/Dislike activities
-
Ignoring genAI and nsfl properties: PieFed adds these to
Group and Page objects โ unknown properties should be ignored, not
cause parsing errors
-
Sending polls/events to PieFed communities hosted on Lemmy:
PieFed prevents posting polls and events to remote Lemmy communities
because Lemmy doesn't support them โ but if you federate these object
types to PieFed-hosted communities, they will work
-
Not handling EmojiReact: PieFed sends EmojiReact activities
for emoji reactions โ these federate as Like activities to Lemmy
for compatibility, but other implementations may receive the raw
EmojiReact type
-
Assuming all communities federate: PieFed supports local-only
and private communities that are invisible to federation
-
Not supporting ChooseAnswer: In Q&A mode communities, PieFed
sends ChooseAnswer activities to mark accepted answers โ unknown
activity types should be ignored gracefully
