kb-pixelfed

Stars8

Forks0

UpdatedMarch 13, 2026 at 00:51

Background knowledge about Pixelfed, the decentralized photo and video sharing platform. Load when the user asks about implementing a Pixelfed- compatible ActivityPub server, federating with Pixelfed instances, Pixelfed's actor model (Person actors, Application instance actor), Pixelfed's supported ActivityPub activities (Accept, Add, Announce, Create, Delete, Flag, Follow, Like, Reject, Undo, Update, View, Story:Reaction, Story:Reply), Pixelfed's non-standard extensions (capabilities object for announce/like/reply permissions, commentsEnabled boolean, Stories with Bearcap URIs, location geo-tagging with Place objects, blurhash on attachments, federated Groups via FEP-400e and FEP-1b12), Pixelfed's JSON-LD context namespaces (pixelfed.org/ns#, joinmastodon.org/ns#), Pixelfed's Mastodon API compatibility layer, cross-platform federation quirks (text-only posts hidden, album limits, Stories not federating outside Pixelfed, comment count inaccuracies), Pixelfed configuration environment variables (ACTIVITY_PUB,

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

reiver

reiver/vibefed

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

More from this repository

same repository

kb-mastodon

reiver/vibefed

Background knowledge about Mastodon, the dominant federated microblogging platform and de facto reference implementation for ActivityPub social networking. Covers Mastodon's JSON-LD @context structure (three-element array: activitystreams, security/v1, inline object defining toot: http://joinmastodon.org/ns# with Emoji/discoverable/featured/featuredTags/ blurhash/votersCount/indexable/memorial/suspended/attributionDomains, schema: http://schema.org# with PropertyValue/value, as: with Hashtag/manuallyApprovesFollowers/movedTo/sensitive), content-type and Accept header requirements (application/activity+json or application/ ld+json with ActivityStreams profile, content negotiation for actor discovery), HTTP signature requirements (RSA-SHA256, Digest header mandatory for POST, signed headers include request-target/host/date/ digest), authorized fetch / secure mode (AUTHORIZED_FETCH env var, requires signatures on GET requests too, breaks unsigned federation), supported object types (Note and Question first-class

2026-03-238

kb-writefreely

reiver/vibefed

Background knowledge about WriteFreely, the open-source federated blogging platform written in Go (AGPL-3.0) by Matt Baer / Musing Studio. Covers the origin story (Write.as anonymous writing platform launched 2014, open-sourced as WriteFreely November 2018 after adding ActivityPub), the write-only/broadcast federation model (blogs can be followed but cannot follow others, no incoming comments/replies displayed, no moderation), the actor model (each blog/collection is a Person actor with handle @blog@instance.com), the Article vs Note object type distinction (double-line break heuristic, notes_only config option), supported activities (outbound Create/Update/Delete, inbound Follow/Undo/Like), RSA-SHA256 HTTP signatures with per-blog keypairs, the tech stack (Go/MySQL or SQLite/single binary deployment/256 MB RAM/Raspberry Pi), configuration (single-user vs multi-user modes, federation toggle, .ini config file), NodeInfo with WriteFreely-specific metadata, the RESTful API (Posts/Collections/Users with token aut

2026-03-148

kb-mbin

reiver/vibefed

Background knowledge about Mbin, the federated content aggregator and microblogging platform (active community fork of Kbin). Covers the hybrid dual content model (threads as Page + microblogs as Note in one platform), magazines as Group actors with Announce relay, the three actor types (Application instance actor at /i/actor, Person user at /u/username, Group magazine at /m/name), the full activity reference (Create, Update, Delete, Like, Dislike, Announce, Follow, Accept, Block, Flag, Lock, Add, Remove), the voting system (Like for upvotes, Dislike for downvotes with historical federation issues, Announce for boosts — boosts and votes are separate unlike Lemmy), the hybrid thread+microblog model and why it enables superior Mastodon integration, the tech stack (PHP 8.3+/Symfony 7.4/ PostgreSQL/RabbitMQ/Redis, AGPL-3.0), the async message processing architecture (Symfony Messenger with 15 inbox + 15 outbox message types), the REST API with OAuth2 and Swagger docs, the Mbin fork history (forked from Kbin Octob

2026-03-148

kb-nodebb

reiver/vibefed

Background knowledge about NodeBB, the modern open-source forum software built on Node.js with native ActivityPub federation (core feature since v4.0.0, January 2025). Covers the three actor types (Person user at /u/username, Group category at /category/<cid> implementing FEP-1b12 Group Federation with Announce relay pattern, Application instance actor), the two-level content hierarchy (category as audience → topic as context → post), how topics map to resolvable OrderedCollection contexts per FEP-7888 and posts are Note/Article objects, extensive FEP support (12 implemented: FEP-1b12 Group Federation, FEP-7888 context property, FEP-f228 Backfilling Conversations, FEP-4f05 Soft Deletion, FEP-9098 Custom emojis, FEP-b2b8 Long-form Text, FEP-fe34 Origin-based security, FEP-ae0c Relay Protocols, FEP-11dd Context Ownership, FEP-f15d Context Relocation, FEP-fb2a Actor metadata, FEP-0151 NodeInfo), the tech stack (Node.js/WebSocket/Socket.IO/ MongoDB or Redis or PostgreSQL, GPL-3.0), content discovery (follow- base

2026-03-138

kb-kbin

reiver/vibefed

Background knowledge about Kbin and its active community fork Mbin, the decentralized content aggregator and microblogging platform for the Fediverse (Reddit + Mastodon hybrid). Covers the dual content model (threads/link aggregation via Page objects + microblogging via Note objects in a single platform), magazines as Group actors with Announce relay (same pattern as Lemmy communities), the three actor types (Application instance actor at /i/actor, Person user at /u/username, Group magazine at /m/name), supported activities (Follow, Like, Announce, Create, Update, Delete, Block, Flag, Lock, Add, Remove), the critical detail that downvotes do NOT federate, content object mapping (threads as Page, microblogs as Note, comments as Note with inReplyTo, private messages as ChatMessage), the tech stack (PHP 8.2+/Symfony/PostgreSQL/RabbitMQ/Redis, AGPL-3.0), the REST API with OAuth2 and Swagger docs at /api/docs, the Mbin fork history (Kbin discontinued after creator Ernest Wisniewski's absences, Mbin forked October

2026-03-138

kb-piefed

reiver/vibefed

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 fallb

2026-03-138

name	kb-pixelfed
description	Background knowledge about Pixelfed, the decentralized photo and video sharing platform. Load when the user asks about implementing a Pixelfed- compatible ActivityPub server, federating with Pixelfed instances, Pixelfed's actor model (Person actors, Application instance actor), Pixelfed's supported ActivityPub activities (Accept, Add, Announce, Create, Delete, Flag, Follow, Like, Reject, Undo, Update, View, Story:Reaction, Story:Reply), Pixelfed's non-standard extensions (capabilities object for announce/like/reply permissions, commentsEnabled boolean, Stories with Bearcap URIs, location geo-tagging with Place objects, blurhash on attachments, federated Groups via FEP-400e and FEP-1b12), Pixelfed's JSON-LD context namespaces (pixelfed.org/ns#, joinmastodon.org/ns#), Pixelfed's Mastodon API compatibility layer, cross-platform federation quirks (text-only posts hidden, album limits, Stories not federating outside Pixelfed, comment count inaccuracies), Pixelfed configuration environment variables (ACTIVITY_PUB, AP_REMOTE_FOLLOW, MAX_PHOTO_SIZE, MAX_ALBUM_LENGTH, STORIES_ENABLED, OAUTH_ENABLED), or Pixelfed's technical stack (PHP, Laravel, Vue.js, Redis). Also load when reviewing or writing code that needs to interoperate with Pixelfed instances or implement Pixelfed-specific extensions.
user-invocable	false

Pixelfed — Complete Reference

Overview

Pixelfed is a free, open-source, decentralized photo and video sharing platform — the Fediverse's answer to Instagram. Created by Daniel Supernault ("dansup") and launched December 25, 2018, it federates via ActivityPub. As of mid-2025, it has approximately 900,000 registered users across roughly 1,800 servers with 96+ million media items shared. Licensed under AGPL-3.0.

Pixelfed only displays posts with images or video — text-only posts from other Fediverse platforms are hidden. This is a fundamental design decision, not a bug.

1. Technical Stack

Layer	Technology
Backend language	PHP
Backend framework	Laravel (currently v12)
Database	MySQL 8.0 or PostgreSQL 13
Cache / Queue	Redis
Queue management	Laravel Horizon
OAuth	Laravel Passport
Frontend framework	Vue.js 2.6.14
Frontend state	Vuex
CSS	Bootstrap
Build	Webpack via Laravel Mix
Mobile	React Native (iOS + Android)
Storage	Local filesystem or S3/Object Storage
License	AGPL-3.0
Runtime	PHP 8.3+ (supports 8.4, 8.5), Node.js for assets

2. Actor Model

Pixelfed uses Person type actors for user accounts:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {"pixelfed": "http://pixelfed.org/ns#"}
  ],
  "type": "Person",
  "id": "https://pixelfed.example/users/alice",
  "preferredUsername": "alice",
  "name": "Alice",
  "summary": "<p>Bio text</p>",
  "inbox": "https://pixelfed.example/users/alice/inbox",
  "outbox": "https://pixelfed.example/users/alice/outbox",
  "following": "https://pixelfed.example/users/alice/following",
  "followers": "https://pixelfed.example/users/alice/followers",
  "manuallyApprovesFollowers": false,
  "indexable": true,
  "publicKey": {
    "id": "https://pixelfed.example/users/alice#main-key",
    "owner": "https://pixelfed.example/users/alice",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  },
  "icon": {
    "type": "Image",
    "mediaType": "image/jpeg",
    "url": "https://pixelfed.example/storage/avatars/alice.jpg"
  },
  "endpoints": {
    "sharedInbox": "https://pixelfed.example/f/inbox"
  },
  "alsoKnownAs": []
}

Key points:

The shared inbox path is /f/inbox (not /inbox as with some other implementations)
manuallyApprovesFollowers controls locked/private account behaviour
indexable signals whether the account should appear in search indexes
alsoKnownAs is present but account migration between servers is not currently supported

Instance Actor

Pixelfed uses an instance-wide actor with "type": "Application" to sign GET requests to remote instances. This is separate from the Person actors used by regular accounts. The instance actor is used for authorized fetch (secure mode) — when a remote server requires signed GET requests, Pixelfed uses this actor's key.

3. Supported Activities

Activity	Description
`Accept`	Approves follow requests
`Add`	Federates Stories (uses Bearcap URIs for access control)
`Announce`	Reblogs/boosts
`Create`	Creates Note and Question objects
`Delete`	Removes Person, Tombstone, and Story objects
`Flag`	Federated report functionality
`Follow`	Follow request
`Like`	Favorites a post
`Reject`	Denies follow requests
`Undo`	Reverses Announce, Follow, and Like
`Update`	Modifies Note (status) and Person (profile)
`View`	Story view tracking
`Story:Reaction`	Reaction to a Story (Pixelfed-only)
`Story:Reply`	Reply to a Story (Pixelfed-only)

Story:Reaction and Story:Reply are Pixelfed-specific activity types that are not understood by other Fediverse software.

4. Object Types and Post Structure

Pixelfed supports three object types: Note, Image, and Document.

Posts are represented as Note objects:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {"pixelfed": "http://pixelfed.org/ns#"}
  ],
  "type": "Note",
  "id": "https://pixelfed.example/p/alice/123456",
  "attributedTo": "https://pixelfed.example/users/alice",
  "content": "<p>Caption text with #hashtag</p>",
  "summary": null,
  "inReplyTo": null,
  "published": "2025-06-15T12:00:00Z",
  "url": "https://pixelfed.example/p/alice/123456",
  "sensitive": false,
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://pixelfed.example/users/alice/followers"],
  "attachment": [
    {
      "type": "Image",
      "mediaType": "image/jpeg",
      "url": "https://pixelfed.example/storage/m/photo.jpg",
      "name": "Alt text description",
      "blurhash": "LEHV6nWB2yk8pyoJadR*.7kCMdnj"
    }
  ],
  "tag": [
    {
      "type": "Hashtag",
      "href": "https://pixelfed.example/discover/tags/hashtag",
      "name": "#hashtag"
    }
  ],
  "commentsEnabled": true,
  "capabilities": {
    "announce": "https://www.w3.org/ns/activitystreams#Public",
    "like": "https://www.w3.org/ns/activitystreams#Public",
    "reply": "https://www.w3.org/ns/activitystreams#Public"
  }
}

Key points:

summary is used for content warnings (null when not set)
attachment contains Image objects with optional blurhash
Albums can have up to 20 items (some sources say 12 for photos)
Captions support up to 2,000 characters (configurable)
Three visibility levels: public, unlisted, followers-only

5. Pixelfed-Specific Extensions

Capabilities

Per-post access control added to Note objects:

"capabilities": {
  "announce": "https://www.w3.org/ns/activitystreams#Public",
  "like": "https://www.w3.org/ns/activitystreams#Public",
  "reply": null
}

Each capability value is either:

"https://www.w3.org/ns/activitystreams#Public" — allowed for everyone
null — disabled

This controls who can boost, like, or reply to a specific post. Other Fediverse software generally ignores this extension — they will still allow their users to interact with the post regardless of these settings.

commentsEnabled

A boolean property on Note objects:

"commentsEnabled": true

When false, replies are disabled on the post. Like capabilities, this is enforced by Pixelfed but generally ignored by other implementations.

Stories

Ephemeral 24-hour content, similar to Instagram Stories:

Federated only between Pixelfed instances — not visible on Mastodon, Pleroma, or other platforms
Use Bearcap URIs for access control (recipients must present a token to access the content)
Require STORIES_ENABLED=true in server configuration
Support activities: Add, Delete, View, Story:Reaction, Story:Reply
Transform to StoryReaction and StoryView internal models

Location Geo-tagging

Posts can include a Place object for location data:

"location": {
  "type": "Place",
  "name": "Paris, France",
  "longitude": 2.3522,
  "latitude": 48.8566,
  "country": "France"
}

Blurhash

Pixelfed includes blurhash on image attachments for compact preview placeholders. This uses the toot:blurhash property from Mastodon's namespace (http://joinmastodon.org/ns#). The blurhash is a short string that encodes a blurred preview of the image, useful for showing a placeholder while the full image loads.

Federated Groups

Pixelfed supports federated Groups via FEP-400e and FEP-1b12 extensions. Group actors use "type": "Group" with standard inbox/outbox collections.

6. JSON-LD Context

Pixelfed uses a multi-context approach with four namespaces:

"@context": [
  "https://www.w3.org/ns/activitystreams",
  "https://w3id.org/security/v1",
  {"pixelfed": "http://pixelfed.org/ns#"},
  {"toot": "http://joinmastodon.org/ns#"}
]

Namespace	Purpose
`https://www.w3.org/ns/activitystreams`	ActivityStreams 2.0 vocabulary
`https://w3id.org/security/v1`	W3C Security Vocabulary (publicKey)
`http://pixelfed.org/ns#`	Pixelfed-specific properties (capabilities, commentsEnabled)
`http://joinmastodon.org/ns#`	Mastodon compatibility (blurhash, indexable)

When processing Pixelfed JSON-LD documents, unknown properties from the pixelfed: and toot: namespaces should be ignored rather than causing errors.

7. HTTP Signatures and WebFinger

HTTP Signatures

Pixelfed signs every POST and GET request
All incoming POST requests must be signed
GET requests may require signatures (configurable — this is "authorized fetch" or "secure mode")
The instance Application actor's key is used for signing GET requests
Individual Person actor keys are used for signing POST requests (activities from that user)

WebFinger

Pixelfed requires each ActivityPub actor to uniquely map to an acct: URI resolvable via WebFinger at /.well-known/webfinger. Standard WebFinger resolution applies.

8. Collections

Three primary user collections using the OrderedCollection pattern:

Collection	Path	Content
Following	`/users/{username}/following`	Accounts this user follows
Followers	`/users/{username}/followers`	Accounts following this user
Outbox	`/users/{username}/outbox`	User's published statuses

totalItems may return 0 if the collection is hidden per user privacy preference. This is intentional, not a bug — do not assume an empty collection means the user has no followers/following.

9. Mastodon API Compatibility

Pixelfed implements a subset of the Mastodon REST API, allowing Mastodon client apps to work with Pixelfed instances.

Working endpoints

Account endpoints (verify_credentials, update_credentials, relationships, search)
Status endpoints (create, view, delete, favourite, boost)
Timeline endpoints (home, public, hashtag)
Notification endpoints
OAuth 2.0 authentication (requires OAUTH_ENABLED=true)

Known compatibility gaps

OOB OAuth redirect (urn:ietf:wg:oauth:2.0:oob) is not supported — apps relying on this flow will fail
Authorization code grant type has reported issues
Some public API endpoints incorrectly require OAuth tokens
Pixelfed-specific features (Stories, Collections, capabilities) are not accessible via the Mastodon API — only through Pixelfed's own API

10. Federation Interoperability

Cross-platform behaviour

Feature	Pixelfed to Mastodon	Mastodon to Pixelfed
Photo posts	Appear as image posts with text	Appear normally if image attached
Text-only posts	N/A (Pixelfed requires media)	Not displayed on Pixelfed
Album posts (>4 images)	Only first 4 images shown	N/A (Mastodon max 4)
Stories	Not visible	N/A
Boosts	Appear as boosts	Appear as boosts
Likes/Favourites	Federate normally	Federate normally
Replies	Federate, but display may be incomplete	Federate normally
Content warnings	Show as content warnings	Show as content warnings

Known federation issues

Pixelfed does not display older posts created before federation with a particular instance began
Comment counts may be inaccurate (showing N comments but not all visible) due to incomplete federation of reply threads
Nested reply threading can be incomplete across platforms
Profile photo updates sometimes fail to federate properly
The capabilities extension is not respected by other platforms — a post with "reply": null can still receive replies from Mastodon users

11. Configuration Reference

Federation

Variable	Description
`ACTIVITY_PUB`	Enable/disable federation entirely
`AP_REMOTE_FOLLOW`	Allow/prevent remote following

Media

Variable	Default	Description
`MAX_PHOTO_SIZE`	15000 (KB)	Per-file size limit (15 MB)
`MAX_ACCOUNT_SIZE`	1000000 (KB)	Per-user total storage (1 GB)
`MAX_ALBUM_LENGTH`	4	Items per post
`IMAGE_QUALITY`	80	JPEG quality 1-100
`PF_OPTIMIZE_IMAGES`	—	Automatic image optimization
`PF_OPTIMIZE_VIDEOS`	—	Automatic video optimization
`PF_ENABLE_CLOUD`	—	S3/Object Storage support

Accounts

Variable	Default	Description
`MAX_CAPTION_LENGTH`	500	Caption character limit
`MAX_BIO_LENGTH`	125	Bio character limit
`MAX_NAME_LENGTH`	30	Display name limit
`OPEN_REGISTRATION`	true	New account creation
`PF_MAX_USERS`	1000	User registration cap
`ENFORCE_EMAIL_VERIFICATION`	—	Email confirmation required

Features

Variable	Default	Description
`STORIES_ENABLED`	false	Stories functionality
`OAUTH_ENABLED`	—	Third-party app authentication
`INSTANCE_DISCOVER_PUBLIC`	—	Public explore feature access
`INSTANCE_PUBLIC_HASHTAGS`	—	Anonymous hashtag feed browsing

12. Common Implementation Mistakes

Ignoring the capabilities extension: when federating with Pixelfed, be aware that capabilities exists — even if you choose not to enforce it, you should not strip it when forwarding posts between instances
Sending text-only posts to Pixelfed: Pixelfed silently drops posts without media attachments — there is no error response, the post simply does not appear
Assuming Mastodon API parity: Pixelfed's Mastodon API implementation has gaps (no OOB OAuth, some endpoints require tokens when they should not) — test against a real Pixelfed instance
Not handling commentsEnabled: false: if your software creates replies, check this field before sending a reply to a Pixelfed post — while Pixelfed cannot prevent your server from delivering the reply, respecting this field is good federation citizenship
Expecting Stories to federate universally: Stories only work between Pixelfed instances — do not implement Story support expecting cross-platform compatibility
Treating totalItems: 0 as empty: Pixelfed returns 0 for hidden collections — a followers count of 0 does not mean the account has no followers
Wrong shared inbox path: Pixelfed uses /f/inbox as the shared inbox, not /inbox — always read the endpoints.sharedInbox value from the actor document rather than guessing
Not handling the Application instance actor: Pixelfed uses a separate Application-type actor for GET request signing — if your server requires signed fetches, be prepared to resolve and verify keys from actors with "type": "Application", not just "Person"