Kb Piefed

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

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

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

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

Community → 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

PieFed-Specific Extensions

8. Federation Architecture

Activity Processing Flow

1. Parse JSON request body
2. Check federation pause status (normal / overload / permanently closed)
3. Extract actor and validate HTTP signature
4. Deduplicate via Redis (activity IDs stored with 90-second TTL)
5. Route to handler based on activity type
6. Process asynchronously via Celery task

HTTP Signatures

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

9. REST API

PieFed's API is intentionally "95% the same as the Lemmy API" to enable reuse of Lemmy's mobile app ecosystem.

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

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)

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

16. Common Implementation Mistakes

1. Assuming PieFed is a Lemmy fork: PieFed is a completely separate Python codebase, not a Rust fork — protocol-compatible but architecturally different

2. Not handling the Feed actor type: PieFed federates Feed actors via WebFinger; other software should treat unknown actor types gracefully rather than erroring

3. 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

4. Ignoring genAI and nsfl properties: PieFed adds these to Group and Page objects — unknown properties should be ignored, not cause parsing errors

5. 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

6. 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

7. Assuming all communities federate: PieFed supports local-only and private communities that are invisible to federation

8. Not supporting ChooseAnswer: In Q&A mode communities, PieFed sends ChooseAnswer activities to mark accepted answers — unknown activity types should be ignored gracefully