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

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

flask db upgrade

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

Group

Person

Service

Feed

Page

name

Article

Link

Note

inReplyTo

Question

oneOf

anyOf

Event

startTime

endTime

timezone

participantCount

Video

ChatMessage

3. Communities as Group Actors

Communities are

Group

Announce

Community-Specific Attributes

sensitive

nsfl

genAI

postingRestrictedToMods

newModsWanted

privateMods

defaultPostType

questionAnswer

moderators

featured

tagsForPosts

Moderator Attribution

PieFed accepts both

attributedTo

moderators

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

Dislike

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

A Feed is an ActivityPub actor of type

Feed

• 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

6. Full Activity Reference

Incoming Activities

Follow

Accept

Reject

Create

Update

Delete

Like

Dislike

EmojiReact

:name:

PollVote

ChooseAnswer

Add

Remove

Lock

Flag

Announce

Undo

Community → Followers

Accept{Follow}

Announce{*}

Community outboxes serve

Announce(Create(Page))

7. JSON-LD Context and Extensions

Context

[
  "https://www.w3.org/ns/activitystreams",
  "https://w3id.org/security/v1"
]

Lemmy-Compatible Extensions

tagsForPosts

CommunityTag

postingRestrictedToMods

language

identifier

name

PieFed-Specific Extensions

genAI

nsfl

flair

postingWarning

interactionPolicy

newModsWanted

questionAnswer

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

hs2019

(request-target)

Host

Date

Digest

Content-Type

Accept

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

/.well-known/webfinger

/.well-known/nodeinfo

/nodeinfo/2.0

/nodeinfo/2.1

/u/<actor>

/c/<actor>

/inbox

/site_inbox

/api/v1/instance

9. REST API

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

/api/alpha/

/api/alpha/swagger

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

![alt :: width=300px](url)

Question

oneOf

anyOf

:piefed:

ChooseAnswer

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)

db

redis

celery

app

piefed_notifs

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

Feed

genAI

EmojiReact

ChooseAnswer

Event

PollVote

flair

tagsForPosts

tagsForPosts

/api/alpha/

/api/v3/

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