Fediverse, Social Web, and ActivityPub knowledge, skills, and slash-commands. Detects WebFinger, NodeInfo, and understands HTTP signatures, hashtags, follows, and likes at the ActivityPub level.

GitHub stars
9

Install

/plugin install vibefed@vibefed

Run it inside Claude Code after adding the marketplace with /plugin marketplace add reiver/vibefed.

Contents

Discovered from source

Skills 29

Detect NodeInfo Endpoint

NodeInfo is a protocol used by federated social network servers to expose instance metadata in a standardized format. It is widely used in the Fediverse (Mastodon, Misskey, Pleroma, Diaspora, etc.).

How NodeInfo Works (Two-Part Architecture)

NodeInfo is always two endpoints, not one. This is important for classification:

Part 1 — Discovery endpoint (required):

  • URL: GET /.well-known/nodeinfo
  • Returns a JSON object with a links array, each entry pointing to a versioned schema document
  • Example response:
    {
      "links": [
        {
          "rel": "http://nodeinfo.diaspora.software/ns/schema/2.1",
          "href": "https://example.org/nodeinfo/2.1"
        }
      ]
    }
    

Part 2 — Schema endpoint (required):

  • URL: typically /nodeinfo/2.1 or /nodeinfo/2.0 (path is not standardized, but this convention is near-universal)
  • Returns the full instance metadata document
  • Key fields: version, software, protocols, usage, openRegistrations, metadata

Variant — NodeInfo2 (optional, separate spec):

  • URL: GET /.well-known/x-nodeinfo2
  • A different, simpler schema by a different author (jaywink/nodeinfo2)
  • Less common; treat as a separate positive signal if found

Step 1 — Fast Signal Search

Search the codebase for nodeinfo (case-insensitive) across all source files, excluding: node_modules, vendor, .git, dist, build.

If no matches are found, proceed to Step 2 (fallback search). If matches are found, proceed to Step 3 (classify results).

Step 2 — Fallback Search (if Step 1 found nothing)

Some implementations use only generic well-known routing. Search for:

  • /.well-known/nodeinfo (the discovery path literal)
  • diaspora.software/ns/schema (the rel URL used in the links array — a very specific signal)
  • x-nodeinfo2 (NodeInfo2 variant path)
  • openRegistrations (a distinctive field name in the schema response)
  • activeHalfyear or activeHalfYear (unique usage stats field)

If still nothing — report: NodeInfo not detected.

Step 3 — Classify Each Match

For each file containing a match, determine which category it falls into:

Category A — Discovery endpoint (confirmed)

The file registers a route at /.well-known/nodeinfo that returns a links array pointing to a versioned schema document.

Category B — Schema endpoint (confirmed)

The file registers a route (commonly /nodeinfo/2.0, /nodeinfo/2.1, /nodeinfo/2.2) that returns the full instance metadata document with fields like software, protocols, usage, openRegistrations.

Category C — Both endpoints present

The codebase implements both Part 1 and Part 2 — this is a complete implementation.

Category D — Library/Framework delegation

The file imports or references a NodeInfo library (e.g. go-nodeinfo, @semapps/nodeinfo, nodeinfo-rack, ActivityPub frameworks like Fedify which auto-register NodeInfo) without directly defining the handlers.

Category E — Reference only (not an implementation)

The match appears in comments, test fixtures, README files, or configuration pointing to an external NodeInfo server.

Category F — NodeInfo2 variant

The file handles /.well-known/x-nodeinfo2 — a valid but separate implementation of the NodeInfo2 spec (jaywink/nodeinfo2). Report alongside standard NodeInfo findings.

Step 4 — Check for Framework-Specific Patterns

Framework / LanguagePattern to look for
Railsget '/.well-known/nodeinfo' in routes.rb; nodeinfo_controller.rb
Djangopath('.well-known/nodeinfo' in urls.py
Express / Nodeapp.get('/.well-known/nodeinfo'
Spring Boot@GetMapping("/.well-known/nodeinfo")
Gonodeinfo.NodeInfoPath constant; NodeInfoDiscover handler
MastodonWellKnown::NodeinfoController
Misskey / Calckeynodeinfo in route definitions
Fedify (TS/JS)NodeInfo auto-registered — look for setNodeInfoDispatcher
PHP (ActivityPub)well-known/nodeinfo near json_encode

Step 5 — Check Schema Version Support

If a schema endpoint is found, note which version(s) are supported:

  • 1.0 — original, rarely seen today
  • 1.1 — adds services
  • 2.0 — adds usage.localComments; most common
  • 2.1 — adds software.repository and software.homepage; current standard
  • 2.2 — draft; uncommon

The rel URL in the discovery response encodes the version: http://nodeinfo.diaspora.software/ns/schema/2.1

Step 6 — Report Results

Provide a clear summary with:

  1. Verdict: NodeInfo detected / Not detected / Possibly delegated to library
  2. Parts found:
    • Discovery endpoint (/.well-known/nodeinfo): Yes / No / Via library
    • Schema endpoint (/nodeinfo/x.y): Yes / No / Via library
    • NodeInfo2 variant (/.well-known/x-nodeinfo2): Yes / No / N/A
  3. Schema versions supported (if determinable)
  4. Evidence: File names and line numbers containing the implementation
  5. Implementation style: Direct / Library delegation / Framework built-in
  6. Completeness notes (if applicable):
    • e.g. "Discovery endpoint found but no schema endpoint detected"
    • e.g. "Schema endpoint found but usage stats appear hardcoded rather than queried from a database"
    • e.g. "Missing openRegistrations field in schema response"
  7. Caveats: e.g. "NodeInfo may be handled by a reverse proxy or middleware layer not visible in application code"

What a Complete NodeInfo Implementation Looks Like

For reference, a complete implementation provides:

Discovery (/.well-known/nodeinfo):

{
  "links": [
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.1",
      "href": "https://example.org/nodeinfo/2.1"
    }
  ]
}

Schema (/nodeinfo/2.1):

{
  "version": "2.1",
  "software": {
    "name": "myapp",
    "version": "1.0.0",
    "repository": "https://github.com/example/myapp",
    "homepage": "https://example.org"
  },
  "protocols": ["activitypub"],
  "usage": {
    "users": {
      "total": 100,
      "activeHalfyear": 50,
      "activeMonth": 20
    },
    "localPosts": 1000,
    "localComments": 500
  },
  "openRegistrations": true,
  "metadata": {}
}

Detect WebFinger Endpoint

WebFinger (RFC 7033) is a protocol that allows discovery of information about people or resources using a standard URL pattern: /.well-known/webfinger. It is commonly used by ActivityPub implementations (Mastodon, etc.) and federated identity systems.

Step 1 — Fast Signal Search

Search the codebase for the string webfinger (case-insensitive) across all source files. This single search catches the vast majority of implementations.

Search query: webfinger
Case: insensitive
Scope: all source files (exclude: node_modules, vendor, .git, dist, build)

If no matches are found, proceed to Step 2 (fallback search). If matches are found, proceed to Step 3 (classify results).

Step 2 — Fallback Search (if Step 1 found nothing)

Some implementations register WebFinger indirectly under a generic well-known handler. Search for:

  • /.well-known/ (route registration)
  • well_known (snake_case variant common in Python/Ruby)
  • jrd+json (the WebFinger response MIME type — very specific signal)
  • acct: (the URI scheme WebFinger uses for user lookups)

If any of these match, include the files in Step 3 classification. If still nothing — report: WebFinger not detected.

Step 3 — Classify Each Match

For each file containing a match, determine which category it falls into:

Category A — Implementation (confirmed)

The file contains executable code that:

  • Registers a route or handler at /.well-known/webfinger
  • Processes a resource query parameter
  • Returns a JSON response (JRD format) with a subject field

Category B — Library/Framework delegation

The file imports or references a WebFinger library (e.g. node-webfinger, ostatus, activitypub, webfinger-rack, go-webfinger) without directly defining the handler. The endpoint likely exists but is provided by the dependency.

Category C — Reference only (not an implementation)

The match appears in:

  • Comments or documentation strings
  • Test fixtures or mock data
  • Configuration files referencing an external WebFinger server
  • README or markdown files

Category D — Ambiguous

The file handles /.well-known/ generically and may or may not route WebFinger requests. Read the surrounding logic to determine.

Step 4 — Check for Framework-Specific Patterns

If the codebase language/framework is identifiable, also look for these common patterns:

FrameworkPattern to look for
Express / Nodeapp.get('/.well-known/webfinger'
Railsget '/.well-known/webfinger' in routes.rb
Djangopath('.well-known/webfinger' in urls.py
Spring Boot@GetMapping("/.well-known/webfinger")
Mastodon / ActivityPubCheck for webfinger_controller or webfinger_resource
PHP$_GET['resource'] near a well-known path check

Step 5 — Report Results

Provide a clear summary with:

  1. Verdict: WebFinger detected / Not detected / Possibly delegated to library
  2. Evidence: List the specific files and line numbers (if available) that contain the implementation
  3. Implementation style: Direct route handler / Library delegation / Framework built-in
  4. Completeness notes (if applicable): e.g. "Handler found but no rel parameter filtering detected" or "Missing application/jrd+json content type header"
  5. Caveats: e.g. "WebFinger may be handled upstream by a reverse proxy (nginx/caddy) and never reach the application code"

What a Complete WebFinger Implementation Looks Like

For reference, a complete implementation handles:

  • Route: GET /.well-known/webfinger
  • Required query param: resource (e.g. acct:user@example.com)
  • Optional query param: rel (filters which link types to return)
  • Response Content-Type: application/jrd+json
  • Response body: JSON with at minimum a subject field, typically also links and/or aliases
  • HTTP 404 if the resource is not found
  • HTTP 400 if the resource param is missing

Fediverse Activity Intents (FEP-3b86) — Complete Reference

Overview

Activity Intents enable cross-server social interactions on the Fediverse. A server publishes machine-readable URL templates in its WebFinger response, advertising endpoints where users can perform activities like Follow, Like, Announce, or Create. Remote websites use these templates to display interactive buttons that let users act on content using their home server account — without copy-pasting URLs or leaving the page.

FEP-3b86 (authored by Ben Pate, received 2024-04-19, status DRAFT) formalizes and generalizes the pattern established by the oStatus "remote follow" mechanism. It is inspired by Twitter Web Intents (2011) and Facebook's Share Button — centralized URL-based interaction flows — adapted for a decentralized system where the user's home URL must be discovered dynamically via WebFinger.

The Problem: Broken Remote Interactions

Without Activity Intents, cross-server interaction on the Fediverse is painful. If a user on Server A wants to follow, like, or share content from Server B, the typical workflow is:

  1. Copy the URL of the content or actor
  2. Paste it into their own instance's search bar
  3. Wait for it to resolve
  4. Then interact

The only partially-standardized alternative was the oStatus subscribe template — a link in WebFinger with rel="http://ostatus.org/schema/1.0/subscribe" pointing to Mastodon's /authorize_interaction endpoint. But this mechanism:

  • Only supports Follow — no Like, Announce, Create, Reply, etc.
  • Is undocumented in the ActivityPub context
  • Was reverse-engineered from Mastodon's behavior, not formally specified
  • Uses an oStatus-specific rel value from a superseded protocol
  • Provides no callbacks — no way for the remote server to know when the action completes

How Activity Intents Work

WebFinger Response Structure

Activity Intent links appear in the standard WebFinger JRD links array. Each link has a rel identifying the activity type and a template containing an RFC 6570 URI Template:

{
  "subject": "acct:alice@example.social",
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://example.social/users/alice"
    },
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://example.social/authorize_interaction?uri={uri}"
    },
    {
      "rel": "https://w3id.org/fep/3b86/Follow",
      "template": "https://example.social/authorize_interaction?uri={object}"
    },
    {
      "rel": "https://w3id.org/fep/3b86/Like",
      "template": "https://example.social/intents/like?id={object}"
    },
    {
      "rel": "https://w3id.org/fep/3b86/Announce",
      "template": "https://example.social/intents/announce?id={object}"
    },
    {
      "rel": "https://w3id.org/fep/3b86/Create",
      "template": "https://example.social/share?text={content}"
    }
  ]
}

Link Properties

rel: Uses the https://w3id.org/fep/3b86/* namespace (per FEP-888d's w3id.org convention) where * is the Activity type name from the W3C Activity Vocabulary. Examples:

  • https://w3id.org/fep/3b86/Follow
  • https://w3id.org/fep/3b86/Like
  • https://w3id.org/fep/3b86/Announce
  • https://w3id.org/fep/3b86/Create

template: An RFC 6570 URI Template with parameter placeholders (e.g., {object}, {content}). The template property (as opposed to href) is standardized in RFC 6415 (Web Host Metadata), not merely an oStatus invention — though early Fediverse usage inherited it from the oStatus era.

Template Parameter Rules

Remote servers MUST:

  • Replace all recognized parameter placeholders with appropriate values
  • Replace unrecognized placeholders with empty strings
  • Percent-encode all substituted values per RFC 3986

All parameter values represent IDs (URLs) of JSON-LD resources, except for the Create intent's content parameters.

The 28 Standard Activity Intents

FEP-3b86 defines intents for every W3C Activity Vocabulary type. Most follow a common pattern with an {object} parameter and optional workflow callbacks:

IntentRel suffixPrimary parametersPurpose
Accept/Accept{object}Accept an offer, invitation, etc.
Add/Add{object}, {target}Add object to a collection
Announce/Announce{object}Boost/reshare a document
Arrive/Arrive{location}Mark arrival at a location
Block/Block{object}Block a user or document
Create/Create(see below)Create new content
Delete/Delete{object}, {origin}Delete an object
Dislike/Dislike{object}Dislike a document
Flag/Flag{object}Report inappropriate content
Follow/Follow{object}Follow an actor
Ignore/Ignore{object}Ignore/mute an actor or object
Invite/Invite{target}, {object}Invite an actor to an event/group
Join/Join{object}Join a group or event
Leave/Leave{object}Leave a group or event
Like/Like{object}Like a document
Listen/Listen{object}Listen to audio content
Move/Move{object}, {target}, {origin}Move object between collections
Offer/Offer{object}, {target}Offer an object to an actor
Question/Question{name}Start a question/poll
Read/Read{object}Mark as read
Reject/Reject{object}Reject an offer or invitation
Remove/Remove{object}, {target}Remove object from collection
TentativeAccept/TentativeAccept{object}Tentatively accept
TentativeReject/TentativeReject{object}Tentatively reject
Travel/Travel{target}, {origin}Travel between locations
Undo/Undo{object}Undo a previous activity
Update/Update{object}Update an existing object
View/View{object}Mark as viewed

All activity intents also accept optional {on-success} and {on-cancel} workflow callback parameters.

The Create Intent (Special Case)

The Create intent is fundamentally different from other intents. Instead of acting on an existing object via {object}, it pre-populates a new document for the user to compose:

ParameterDescription
{type}Object type (Note, Article, etc.)
{name}Name/title to pre-populate
{summary}Summary to pre-populate
{content}Text content to pre-populate
{inReplyTo}ID of object being replied to
{attachment}ID of object to attach
{tag}ID of tag to reference
{startTime}Start time (RFC 3339)
{endTime}End time (RFC 3339)
{describes}ID of object to describe (for Profile)

Example — a "Share on Mastodon" button:

{
  "rel": "https://w3id.org/fep/3b86/Create",
  "template": "https://mastodon.social/share?text={content}"
}

Example — a "Reply" button on a remote post:

https://example.social/share?text={content}&inReplyTo={inReplyTo}

The Object Intent (Non-Activity)

A special intent at https://w3id.org/fep/3b86/Object enables users to open remote objects in their home server — analogous to pasting a URL into Mastodon's search bar.

This intent does not generate any ActivityPub activities and does not support on-success/on-cancel callbacks.

{
  "rel": "https://w3id.org/fep/3b86/Object",
  "template": "https://server.org/intents/object?objectId={object}"
}

The Object intent was added after discussion where silverpill argued that using the View activity verb would incorrectly imply that a View activity would be generated and sent. The custom URI makes it explicit that the server is just retrieving the object, not creating an activity.

Workflow Callbacks

Activity Intents support optional callback parameters for post-interaction flow control:

{on-success} — action after the user completes the workflow:

  • (close) — instructs the popup window to close
  • A valid URL — redirects the user (with interstitial page)

{on-cancel} — action if the user cancels:

  • Same options as on-success

Critical requirement: Home servers MUST display an interstitial page before any URL redirect, showing the destination and requiring user confirmation. Automatic redirects create open-redirect vulnerabilities.

Remote Server Interaction Flow

The complete user flow for a remote interaction:

  1. User visits a remote server and sees social interaction buttons (Follow, Like, Share, etc.)
  2. User clicks a button
  3. Remote server checks if the user is already recognized (e.g., via cookie)
  4. If unrecognized, user enters their Fediverse ID (@user@server)
  5. Remote server performs a WebFinger query for the user's home server
  6. Remote server finds the appropriate Activity Intent link in the response
  7. Remote server substitutes parameter values into the URI Template
  8. User is redirected to their home server's Activity Intent endpoint
  9. Home server shows a confirmation page (CSRF-protected POST form)
  10. User confirms; home server executes the activity
  11. Home server uses on-success/on-cancel to redirect back (with interstitial) or close the popup

Fallback Strategy

Remote servers SHOULD implement a fallback chain for servers that don't publish Activity Intents:

  1. Activity Intents — use if present in WebFinger response
  2. oStatus subscribe — fall back to the http://ostatus.org/schema/1.0/subscribe template (Mastodon's /authorize_interaction endpoint)
  3. Hard-coded URLs — fall back to known implementation-specific paths (Mastodon's /share, Hubzilla's /rpost)

Security Considerations

CSRF Prevention

  • Remote servers MUST only send GET requests to home servers
  • Home servers MUST NOT change data based on GET requests
  • Home servers SHOULD protect intent endpoints with CSRF tokens on POST operations
  • The GET request loads a confirmation page; the actual mutation happens via a CSRF-protected POST form submission

Open Redirect Mitigation

The on-success and on-cancel parameters accept arbitrary URLs, creating a potential open-redirect vulnerability. Required mitigation (per OWASP):

"Force all redirects to first go through a page notifying users that they are going off of your site, with the destination clearly displayed, and have them click a link to confirm."

The FEP also references OAuth 2.0 Security Best Current Practice § 4.11 (Open Redirection) as additional guidance. During SocialHub discussion, thisismissem recommended preregistered redirect URIs (OAuth-style) as a stronger defense, but this was not adopted into the spec.

History: From oStatus to Activity Intents

oStatus Remote Follow (Pre-2017)

The oStatus protocol suite included a subscribe mechanism using WebFinger. A server published a link with rel="http://ostatus.org/schema/1.0/subscribe" containing a template URL. GNU social used this for remote follows.

Mastodon's authorize_interaction (2017+)

Mastodon adopted the oStatus subscribe template, exposing its own /authorize_interaction?uri={uri} endpoint. Early versions used a different format (/authorize_follow?acct=acct:user@instance) that didn't comply with GNU social's expectations (Mastodon issue #2177). This was eventually standardized within Mastodon but remained Mastodon-specific — other implementations had to reverse-engineer the behavior.

Twitter Web Intents (2011)

Twitter released Web Intents in March 2011, providing URL-based flows:

  • https://twitter.com/intent/tweet?text=...
  • https://twitter.com/intent/retweet?tweet_id=...
  • https://twitter.com/intent/like?tweet_id=...
  • https://twitter.com/intent/follow?screen_name=...

These allowed websites to embed Twitter interaction buttons without requiring users to leave the site or authorize a new app. FEP-3b86 explicitly cites Twitter Web Intents as a reference and applies the same pattern to the decentralized Fediverse.

Earlier Proposal: ActivityPub Extension for Intent (2017)

Akihiko Odaki proposed an Intent class for Activity Streams 2.0 in 2017, enabling delivery of "intents declared at locations different from those where the activity to be performed." This took a different approach — defining a new vocabulary type rather than using WebFinger link templates. It did not gain traction or implementations.

FEP-3b86 (2024)

Ben Pate synthesized the lessons from oStatus, Twitter Web Intents, and the Mastodon approach into a formal specification. Key improvements:

  • Works for any activity type, not just Follow
  • Uses standardized RFC 6570 URI Templates and RFC 6415 template property
  • Publishes via WebFinger — the existing discovery mechanism
  • Includes workflow callbacks for post-interaction flow
  • Has security guidance (CSRF, open redirects)
  • Is formally documented as a Fediverse Enhancement Proposal

Comparison: Activity Intents vs Fedilinks (FEP-07d7)

AspectActivity Intents (FEP-3b86)Fedilinks (FEP-07d7)
ApproachServer-sideClient-side (browser)
DiscoveryWebFinger lookupweb+ap:// URI scheme
Browser changesNone requiredRequires protocol handler registration
Adoption barrierServer implements WebFinger linksNeeds browser vendor support
Works todayYes, with any browserNo — no AP implementations parse web+ap:// URIs
ScopeAll activity types + ObjectObject navigation

Ben Pate's key argument: Activity Intents are "handled by websites themselves instead of relying on enhancements to browsers," enabling incremental implementation without waiting for browser vendor adoption.

Implementation Status

Home Servers (Publishing Activity Intents)

ImplementationIntents Published
EmissaryCreate, Follow, Like
ForteCreate
LoopsFollow
PieFedCreate
streamsCreate
WordPress (ActivityPub plugin v7.6.0+)Create, Follow

Client Implementations (Consuming Activity Intents)

ImplementationFeatures
EmissaryShare/like buttons on remote content
ForteWall-to-wall post/reply buttons
streamsWall-to-wall functionality
Web Intents libraryIn development

Mastodon has not implemented FEP-3b86. An open feature request exists (issue #33984) but no developers are assigned.

Implementation Guidance

Publishing Activity Intents (Home Server)

  1. Add Activity Intent links to your WebFinger JRD response
  2. Use the https://w3id.org/fep/3b86/* namespace for rel values
  3. Use RFC 6570 URI Templates in the template property
  4. At minimum, publish Follow and Create intents (most useful)
  5. Consider also publishing Like, Announce, and Object intents
  6. Keep the existing oStatus subscribe link for backward compatibility

Example minimal WebFinger addition:

{
  "links": [
    {
      "rel": "https://w3id.org/fep/3b86/Follow",
      "template": "https://yourserver.example/intents/follow?actor={object}"
    },
    {
      "rel": "https://w3id.org/fep/3b86/Create",
      "template": "https://yourserver.example/compose?text={content}&reply={inReplyTo}"
    }
  ]
}

Implementing Intent Endpoints (Home Server)

  1. Intent URLs are loaded via GET — display a confirmation page
  2. Include a CSRF token in the confirmation form
  3. The actual mutation happens via POST form submission
  4. After completion, handle on-success:
    • If (close), close the window (JavaScript window.close())
    • If a URL, show an interstitial page with the destination
  5. If the user cancels, handle on-cancel the same way
  6. If the object is not found, show a 404 page — do NOT auto-redirect to on-cancel (open-redirect risk)

Consuming Activity Intents (Remote Server)

  1. When a user wants to interact with content, prompt for their Fediverse ID
  2. Perform a WebFinger query for their ID
  3. Look for the appropriate Activity Intent link in the response
  4. If not found, fall back to oStatus subscribe, then hard-coded URLs
  5. Substitute parameter values into the URI Template (percent-encode per RFC 3986)
  6. Redirect the user to the constructed URL
  7. Optionally include on-success and/or on-cancel callback URLs

Known Issues and Open Questions

  1. DRAFT status — FEP-3b86 has not reached FINAL; the spec may change
  2. Mastodon adoption unclear — the largest Fediverse implementation has not committed to support
  3. Open redirect debate unresolved — thisismissem proposed OAuth-style preregistered redirect URIs, which would be more secure but add complexity
  4. Limited client adoption — only 3 implementations consume intents; most Fediverse software only displays intents for its own users
  5. No Undo/inverse UI pattern — the spec defines Undo intent but doesn't address how to discover whether a user has already performed an action (e.g., already following, already liked)
  6. 28 intents may be excessive — most implementations only publish 1-3 intents; many defined intents (Arrive, Travel, TentativeAccept) have no known implementations

Fediverse Actor Statuses (FEP-82f6) — Complete Reference

Overview

FEP-82f6 (authored by Gregory Klyushnikov / grishka, received 2025-05-12, status DRAFT — finalization expected ~2026-03-18) describes an ActivityPub extension that allows actors to publish a short status text on their profile, with optional expiration, structured metadata attachment, and history.

The feature replicates a well-known UX pattern from centralized platforms: early Facebook "is..." statuses (2006–2009), VKontakte taglines, Discord custom statuses, and GitHub profile statuses. These are distinct from regular posts — they cannot be interacted with (no likes, replies, boosts), cannot contain media attachments, and have a short character limit.

The proposal originates from Smithereen, a federated social network modeled after VKontakte, which already implements this feature. The JSON-LD namespace http://smithereen.software/ns# (prefix sm:) reflects this origin.


1. The ActorStatus Object

ActorStatus extends the ActivityPub Object type. It represents a single status update.

Required Fields

FieldDescription
idUnique identifier for this status update
attributedToID of the actor whose status this is
contentPlain text content of the status
publishedTimestamp when the status was created

Optional Fields

FieldDescription
endTimeTimestamp when the status expires. If present and in the past, implementations MUST NOT display this status
attachmentStructured metadata about what the actor is doing (e.g., a song, a video game). If present, content MUST contain a fallback human-readable plain text representation

Example

{
  "type": "ActorStatus",
  "id": "https://example.social/users/1/statuses/1747286633",
  "attributedTo": "https://example.social/users/1",
  "content": "is desperately trying to bring the old internet back",
  "published": "2025-05-15T05:23:53.539Z",
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    {
      "sm": "http://smithereen.software/ns#",
      "ActorStatus": "sm:ActorStatus"
    }
  ]
}

Example with Expiration

{
  "type": "ActorStatus",
  "id": "https://example.social/users/1/statuses/1747300000",
  "attributedTo": "https://example.social/users/1",
  "content": "at a conference until Friday",
  "published": "2025-05-15T09:00:00.000Z",
  "endTime": "2025-05-16T18:00:00.000Z"
}

Example with Attachment (Now-Playing)

{
  "type": "ActorStatus",
  "id": "https://example.social/users/1/statuses/1747350000",
  "attributedTo": "https://example.social/users/1",
  "content": "Radiohead — Everything In Its Right Place",
  "published": "2025-05-15T12:00:00.000Z",
  "attachment": {
    "type": "Audio",
    "name": "Everything In Its Right Place",
    "attributedTo": "Radiohead"
  }
}

The content field MUST contain a human-readable fallback so servers that don't understand the structured attachment can still display meaningful text.


2. Actor Fields

Two OPTIONAL fields are added to actor objects:

status

The current status update. Rules:

  • MUST NOT be present if the last status has expired or been cleared
  • MUST contain an inlined ActorStatus object (not a reference/link)
  • When present, it is always current and non-expired — consumers can rely on this
{
  "type": "Person",
  "id": "https://example.social/users/1",
  "name": "Alice",
  "status": {
    "type": "ActorStatus",
    "id": "https://example.social/users/1/statuses/1747286633",
    "attributedTo": "https://example.social/users/1",
    "content": "is desperately trying to bring the old internet back",
    "published": "2025-05-15T05:23:53.539Z"
  }
}

statusHistory

A collection of all past status updates. Behavior:

  • If present, implementations MAY provide a UI to view the actor's status history (similar to early Facebook's status timeline)
  • If absent, implementations SHOULD NOT store past status updates and MUST NOT expose them in the UI
  • The presence or absence of this collection signals to remote servers whether the actor supports status history

3. Activities

Create — Set a New Status

Send Create{ActorStatus} to followers.

{
  "type": "Create",
  "actor": "https://example.social/users/1",
  "object": {
    "type": "ActorStatus",
    "id": "https://example.social/users/1/statuses/1747286633",
    "attributedTo": "https://example.social/users/1",
    "content": "is desperately trying to bring the old internet back",
    "published": "2025-05-15T05:23:53.539Z"
  },
  "to": "https://example.social/users/1/followers"
}

Upon receiving:

  • Update the actor's current status
  • If the actor has statusHistory, add the new status to it
  • If the actor does NOT have statusHistory, the previous status is considered deleted (as if Deleted)

After sending, the status field on the actor object MUST be updated. An Update{Actor} MUST NOT be sent — the Create already implicitly updates the status field on remote servers.

Remove — Clear Status from Profile

Send Remove{ActorStatus} to followers.

{
  "type": "Remove",
  "actor": "https://example.social/users/1",
  "object": "https://example.social/users/1/statuses/1747286633",
  "to": "https://example.social/users/1/followers"
}

Upon receiving:

  • If the object ID matches the actor's current status, clear it
  • If the actor has statusHistory, the status stays in history
  • The actor's status field becomes absent

Delete — Completely Remove a Status

Send Delete{ActorStatus} to followers.

{
  "type": "Delete",
  "actor": "https://example.social/users/1",
  "object": "https://example.social/users/1/statuses/1747286633",
  "to": "https://example.social/users/1/followers"
}

Upon receiving:

  • Remove the status from statusHistory as well as clearing from profile
  • If the actor has no statusHistory, this is identical to Remove

No Update Allowed

Once published, a status object cannot be Updated. This is a deliberate design decision — if the user wants a different status, they create a new one.

No Interactions

Statuses cannot be interacted with. Implementations:

  • SHOULD NOT send any activities (Like, Announce, etc.) referring to statuses as their object from non-owner actors
  • MUST either ignore such activities (return 2xx) or reject them (return 4xx)

4. Remove vs Delete Semantics

The spec makes a deliberate distinction:

ActivityProfileHistoryUse case
RemoveClearedKept (if statusHistory exists)"I'm done with this status, but it's part of my history"
DeleteClearedRemoved"I want this status to no longer exist anywhere"
Remove (no history)ClearedN/AIdentical to Delete when statusHistory is absent

This mirrors the Facebook/VK pattern where statuses accumulate in a timeline. Users can either move past them (they become history) or delete them entirely.


5. JSON-LD Context

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    {
      "sm": "http://smithereen.software/ns#",
      "ActorStatus": "sm:ActorStatus",
      "status": {
        "@type": "@id",
        "@id": "sm:status"
      },
      "statusHistory": {
        "@type": "@id",
        "@id": "sm:statusHistory"
      }
    }
  ]
}

The namespace http://smithereen.software/ns# originates from the Smithereen project. ActorStatus is equivalent to http://smithereen.software/ns#ActorStatus — they are the same type expressed with and without the namespace prefix.


6. Character Limit

  • Implementations MUST support statuses of up to 100 characters or emoji
  • Implementations MAY allow longer statuses, but they MAY be truncated on the receiving side depending on display and storage constraints
  • RECOMMENDED: apply a 100-character limit in the user-facing text input, but be more permissive when processing status updates from other servers

7. Comparison with Centralized Platform Statuses

PlatformFeatureInteractable?Media?LimitHistory?
Early Facebook (2006–2009)"is..." statusNoNoVery shortYes
VKontakteStatus/taglineNoNoShortYes
DiscordCustom statusNoEmoji only128 charsNo
GitHubCustom statusNoEmoji onlyShortNo
SlackCustom statusNoEmoji only100 charsNo
FEP-82f6ActorStatusNoAttachment metadata100+ charsOptional

No existing Fediverse platform has a standardized actor status feature. Smithereen is the only known implementation.


8. Design Philosophy

The author's design philosophy is distinctive and worth understanding for implementers:

One FEP = One UX Pattern

"This FEP serves one particular UX use case and only that. Nothing less, nothing more." The proposal does not try to be a general-purpose mechanism. It captures a specific, well-understood UI pattern.

Clean Compatibility Break

"A clean compatibility break with all preexisting software is an explicit goal." Rather than reusing existing mechanisms (like the featured collection) for partial backward compatibility, the proposal introduces a new type that servers either understand or don't. This avoids ambiguous degradation where a status might misleadingly appear as a pinned post.

UI-to-Protocol Mapping

"I simply translated the actions that the user can take in the UI to AP activities, one-to-one." Each user action maps directly to one Activity type:

User actionActivity
Set statusCreate{ActorStatus}
Clear statusRemove{ActorStatus}
Delete statusDelete{ActorStatus}

No side effects, no indirect mechanisms (like using Update with endTime changes to clear a status).


9. Why Certain Alternatives Were Rejected

Why Not Use the featured Collection?

silverpill suggested placing ActorStatus in featured for partial compatibility. Rejected because:

  • Mixing different object types in one collection causes database and UI complexity
  • A clean break is preferred over a status misleadingly appearing as a pinned post
  • featured has different semantics (showcase content vs. current state)

Why No Update Activity?

silverpill proposed Update{ActorStatus} setting endTime to a past date to clear statuses. Rejected because:

  • It replaces an obvious action (Remove) with a non-obvious one (Update with a side effect)
  • It opens the door to restoring expired statuses by resetting endTime to a future date
  • The Remove activity directly and transparently maps to the user action of clearing a status

Why No Interactions?

SorteKanin asked why statuses can't have likes, replies, images, or long text. Rejected because adding these features would make statuses overlap with regular posts (Note objects) and lose the distinct UX identity that makes them useful.


10. Implementation Guidance

Sending a Status Update

  1. Create an ActorStatus object with id, attributedTo, content, published, and optionally endTime and/or attachment
  2. Send Create{ActorStatus} to the actor's followers
  3. Update the actor's status field with the new status
  4. Do NOT send Update{Actor} — the Create implicitly updates remote copies

Receiving a Status Update

  1. On Create{ActorStatus}: update the actor's displayed status. If you track history and the actor has statusHistory, add to it. If no statusHistory, discard the previous status.
  2. On Remove{ActorStatus}: if the object ID matches the current status, clear it. Keep in history if applicable.
  3. On Delete{ActorStatus}: clear from profile AND remove from history.
  4. Ignore any other activities (Like, Announce, etc.) targeting statuses.

Displaying Statuses

  • Show on the actor's profile page
  • Optionally show next to the actor's name in feeds, comments, etc.
  • If endTime is present and in the past, do NOT display
  • If statusHistory is available, optionally provide a UI to browse it

Handling the Attachment Field

The attachment field carries structured metadata (e.g., a song, a game). If you can render it richly (album art, game icon), do so. If not, the content field already contains a plain text fallback — just display that.


11. Known Issues and Considerations

  • Single implementation: Smithereen is the only known implementation. The sm: namespace reflects this single-origin status. Adoption by other platforms would validate the design.
  • No standard attachment types: The spec does not define specific attachment schemas for now-playing, gaming, etc. Implementers must define their own structured formats or wait for community conventions.
  • Expiration timing: Implementations must actively check endTime and stop displaying expired statuses. There is no push notification for expiration — it's poll-based on the endTime value.
  • No Update: If a user makes a typo in their status, they must create a new one rather than editing. This is intentional but may surprise users accustomed to editing posts.
  • History privacy: The statusHistory collection is visible to "anyone who can see the actor itself." There is no mechanism for private or followers-only status history.

FEDERATION.md (FEP-67ff) — Complete Reference

Overview

FEDERATION.md is a convention for documenting how a project implements federation protocols. Formalized as FEP-67ff (authored by silverpill, status FINAL, finalized 2024-09-22), it provides a standardized location and format for interoperability documentation — analogous to README.md for project description or CONTRIBUTING.md for contributor guidelines.

The convention originated in January 2020 when Darius Kazemi (creator of gath.io) proposed a standard documentation file after struggling to understand how other servers handled federation. It grew organically to 12+ implementations before silverpill formalized it as a FEP in April 2023. Over 40 projects have now adopted it, including Mastodon, Pixelfed, Lemmy, WordPress ActivityPub, GoToSocial, and PeerTube.


1. Specification Requirements (RFC 2119)

Only two hard requirements:

  1. It MUST be a valid Markdown document
  2. It MUST be located in the root of a project's code repository (or, if documentation is located elsewhere, contain a link to that location)

Soft requirements (SHOULD):

  • It SHOULD enumerate implemented federation protocols and standards
  • It SHOULD list supported Fediverse Enhancement Proposals (FEPs)

The file "can have arbitrary structure and content" — the spec deliberately avoids mandating a rigid format, allowing each project to document what matters most for its federation behavior.


2. Suggested Template

The specification provides a reference template with these sections:

Supported Federation Protocols and Standards

List the protocols the project implements:

## Supported federation protocols and standards

- [ActivityPub](https://www.w3.org/TR/activitypub/) (Server-to-Server)
- [WebFinger](https://webfinger.net/)
- [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
- [NodeInfo](https://nodeinfo.diaspora.software/)

Supported FEPs

List adopted Fediverse Enhancement Proposals:

## Supported FEPs

- [FEP-67ff: FEDERATION.md](https://codeberg.org/fediverse/fep/src/branch/main/fep/67ff/fep-67ff.md)
- [FEP-f1d5: NodeInfo in Fediverse Software](https://codeberg.org/fediverse/fep/src/branch/main/fep/f1d5/fep-f1d5.md)

ActivityPub-Specific Documentation

Detailed sections covering:

  • Profiles / actors
  • Posts / objects
  • Addressing and delivery
  • Content limits
  • Non-standard extensions
  • Known interoperability quirks

3. The Problem FEDERATION.md Solves

ActivityPub is a protocol specification that leaves many implementation details up to individual servers. Different implementations make different choices about:

  • Which Activity types they handle (some ignore Like, some ignore Announce)
  • How they represent custom content (BookWyrm reviews, Lemmy votes, Pixelfed photos)
  • What non-standard extensions they require (Mastodon's HTTP Signature requirements)
  • How they handle edge cases (username changes, content limits, private posts)

Before FEDERATION.md, the only way to understand another implementation's behavior was to read their source code, reverse-engineer through testing, or ask on forums. This was particularly painful because the Fediverse has dozens of implementations in different programming languages.

FEDERATION.md provides a single, predictable file location where developers can find all federation-relevant documentation. By placing it at the repository root as a Markdown file, it follows established open-source conventions (like README.md, CONTRIBUTING.md, LICENSE) and is immediately accessible via any code hosting platform.


4. Real-World Examples

Mastodon's FEDERATION.md

Mastodon's file documents:

  • Protocols: ActivityPub (S2S), WebFinger, HTTP Signatures, NodeInfo
  • FEPs: FEP-67ff, FEP-f1d5, FEP-8fcf, FEP-5feb, FEP-044f, and others
  • Detailed sections: profiles/actors, posts, addressing, content limits, non-standard extensions
  • Notes that Mastodon "largely follows the ActivityPub server-to-server specification but makes use of some non-standard extensions, some of which are required for interacting with Mastodon at all"

WordPress ActivityPub Plugin's FEDERATION.md

Documents support for:

  • ActivityPub S2S, WebFinger, HTTP Signatures, NodeInfo
  • Various FEPs including FEP-67ff itself and FEP-3b86 (Activity Intents)
  • Notes that it "largely follows ActivityPub's server-to-server specification, but makes use of some non-standard extensions"

Both files follow a similar structure — protocols section, FEPs section, then detailed ActivityPub documentation — but neither uses a rigid template. They adapted the convention to their needs.


5. Machine-Readable Discovery

Via NodeInfo 2.1

FEDERATION.md files can potentially be discovered automatically via NodeInfo 2.1's software.repository field, which points to the project's source code repository. A crawler could follow this link and look for FEDERATION.md at the repository root.

{
  "software": {
    "name": "mastodon",
    "version": "4.3.0",
    "repository": "https://github.com/mastodon/mastodon"
  }
}

From this, a tool can construct: https://github.com/mastodon/mastodon/blob/main/FEDERATION.md

Limitation

This approach requires the software.repository field (added in NodeInfo 2.1) and depends on the repository being publicly accessible. Many instances run forks or customized versions where the repository URL may not point to the right FEDERATION.md.


6. The DOAP Companion: FEP-c893

FEP-c893 (by AvidSeeker, status DRAFT, received July 2024) proposes a doap.jsonld file as a machine-readable companion to FEDERATION.md.

What DOAP Provides

A JSON-LD file using the DOAP (Description of a Project) vocabulary:

{
  "@context": {
    "doap": "http://usefulinc.com/ns/doap#",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@type": "doap:Project",
  "doap:name": "Example Server",
  "doap:homepage": "https://example.com",
  "doap:description": {
    "@language": "en",
    "@value": "A federated social media server"
  },
  "doap:implements": [
    "https://www.w3.org/TR/activitypub/",
    "https://webfinger.net/"
  ],
  "doap:supportedFEPs": [
    "https://codeberg.org/fediverse/fep/src/branch/main/fep/67ff/fep-67ff.md"
  ],
  "doap:maintainer": {
    "@type": "foaf:Person",
    "foaf:name": "Alice Developer"
  }
}

Key Fields

FieldPurpose
doap:nameProject name
doap:homepageProject website
doap:descriptionMultilingual description
doap:repositoryRepository URLs
doap:releaseVersion and date information
doap:implementsFederation protocols supported
doap:supportedFEPsAdopted FEPs
doap:maintainerProject maintainers

Relationship to FEP-67ff

FEP-c893 is the machine-readable counterpart to FEP-67ff's human-readable FEDERATION.md. Together they provide both developer documentation and automated capability discovery. This pairing was inspired by XMPP's XEP-0453, which uses the same DOAP vocabulary for capability reporting.


7. Writing a FEDERATION.md

Step-by-Step Guide

  1. Create the file at the root of your project repository

  2. List supported protocols:

    • ActivityPub (specify Server-to-Server, Client-to-Server, or both)
    • WebFinger
    • HTTP Signatures (specify draft version)
    • NodeInfo (specify schema version)
    • Any other protocols (Diaspora, Zot, OStatus, etc.)
  3. List supported FEPs with links to the FEP specifications

  4. Document ActivityPub behavior — this is the most valuable section:

    • What Activity types your server sends and accepts
    • What Object types your server creates and understands
    • How inbox processing works for each Activity type
    • Non-standard extensions or properties your server uses
    • Known interoperability issues with specific implementations
  5. Document addressing and delivery:

    • How public/followers-only/direct addressing works
    • Shared inbox support
    • Relay support
  6. Note known limitations:

    • Activity types that are silently ignored
    • Content types that receive degraded display
    • Extension requirements for full interoperability

Best Practices

  • Keep it updated — outdated documentation is worse than no documentation, because it misleads implementers
  • Be specific about non-standard behavior — if your server requires something not in the ActivityPub spec (like Mastodon's HTTP Signature requirements), document it prominently
  • Include wire-format examples — JSON examples of actual activities your server sends and expects are more useful than prose descriptions
  • Document what you ignore — knowing that a server silently drops Like activities (like Lemmy does with standard Likes) saves implementers debugging time

8. Origin and History

Darius Kazemi's 2020 Proposal

In January 2020, Darius Kazemi (creator of gath.io, a federated event organizing service, and Fellow at the Berkman Klein Center for Internet & Society) proposed FEDERATION.md on SocialHub. He had been implementing federation for gath.io and felt implementers needed better documentation on server behavior.

His original FEDERATION.md had three sections:

  1. Federation philosophy
  2. Inbox behavior (what the server does when receiving various activities)
  3. Web application-triggered activities (what the server sends in response to user actions)

Early Adoption Timeline

DateEvent
January 5, 2020Darius Kazemi proposes FEDERATION.md on SocialHub
January 9, 2020WriteFreely becomes first adopter
February 4, 2020Zot (Hubzilla family) adopts
February 8, 2020Discussed at W3C Social CG meeting
March–October 2020tavern, Smithereen, Lemmy adopt
April 2023silverpill proposes FEP-67ff (~12 implementations)
September 5, 2023FEP-67ff received as DRAFT
September 22, 2024FEP-67ff achieves FINAL status
Present40+ implementations

Key Observation

The convention grew organically for over 3 years before being formalized as a FEP. This "convention first, spec second" approach means FEP-67ff codified existing practice rather than inventing new requirements — a pattern that contributed to its successful adoption and FINAL status.


9. Implementations

Over 40 projects have adopted FEDERATION.md, including:

ProjectCategory
MastodonMicroblogging
Pleroma / AkkomaMicroblogging
GoToSocialMicroblogging
PixelfedPhoto sharing
PeerTubeVideo sharing
LemmyLink aggregation
BookWyrmBook reviews
WriteFreelyLong-form writing
FriendicaSocial networking
HubzillaSocial networking
FunkwhaleMusic sharing
WordPress ActivityPubBlogging plugin
MitraMicroblogging
SmithereenSocial networking
BonfireSocial networking

10. Capability Discovery Landscape

FEDERATION.md addresses documentation but not machine-readable discovery. Several other FEPs tackle the machine-readable side:

FEPApproachMachine-readable?Status
FEP-67ffFEDERATION.md documentationNo (human only)FINAL
FEP-c893DOAP JSON-LD companion fileYesDRAFT
FEP-6481IRI list in NodeInfo metadataYesWITHDRAWN
FEP-9fdeReverse-FQDN operations in NodeInfoYesDRAFT
FEP-eb22Type lists in NodeInfoYesDRAFT
FEP-844eCapability URIs on AP actorsYesDRAFT

FEP-67ff is the only capability-related FEP to reach FINAL status. Its success is partly because it focused on the simplest possible requirement (a Markdown file) rather than trying to solve machine-readable discovery.


11. Known Issues

  • No standard structure — every project formats their FEDERATION.md differently, making automated parsing impossible. This is by design (the spec explicitly allows arbitrary structure) but limits tooling.
  • Freshness problem — there is no mechanism to verify whether a FEDERATION.md is up-to-date. Some files document features from years ago that may have changed.
  • Discovery gap — finding a project's FEDERATION.md requires knowing the repository URL. NodeInfo 2.1's software.repository field helps but is not universally implemented.
  • No machine-readable companion at scale — FEP-c893 (DOAP) exists as a DRAFT but has limited adoption. The Murmurations protocol was proposed as an alternative in 2021 but was not adopted.
  • Fork divergence — many Fediverse instances run forks or customized versions. The upstream FEDERATION.md may not accurately describe a particular instance's behavior.

Fediverse Following — Complete Reference

Overview

Following on the Fediverse is a formal ActivityPub handshake, not a simple database write. It involves activity delivery between servers, an explicit approval step, and ongoing delivery of content. Understanding all the steps — and what can go wrong — is essential for correct implementation.


1. The Actor Object

Before any following can happen, each user is represented as an actor — a JSON-LD object served at a stable URL. The actor contains the endpoints and collections needed for the follow flow:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Person",
  "id": "https://example.com/users/alice",
  "preferredUsername": "alice",
  "inbox": "https://example.com/users/alice/inbox",
  "outbox": "https://example.com/users/alice/outbox",
  "followers": "https://example.com/users/alice/followers",
  "following": "https://example.com/users/alice/following",
  "manuallyApprovesFollowers": false
}

Key properties for following:

  • inbox — the URL where activities are POSTed to reach this actor
  • followers — an OrderedCollection of actors who follow this actor
  • following — an OrderedCollection of actors this actor follows
  • manuallyApprovesFollowers — false = open/unlocked account (auto-accepts); true = locked account (requires manual approval). Defined in the ActivityPub Miscellaneous Terms as as:manuallyApprovesFollowers.

2. The Follow Handshake — Step by Step

Following is a four-message exchange in the general case. For unlocked accounts it collapses to three (the Accept is sent automatically).

Step 1: Alice sends a Follow activity

Alice's server POSTs a Follow activity to Bob's inbox:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://alice.example/activities/follow-1",
  "type": "Follow",
  "actor": "https://alice.example/users/alice",
  "object": "https://bob.example/users/bob"
}
  • The object is the actor being followed (Bob)
  • The actor is the one initiating the follow (Alice)
  • The id should be a unique, dereferenceable URI on Alice's server (though in practice many implementations use non-dereferenceable UUIDs)
  • At this point, Alice's server may add Bob to Alice's following collection tentatively, or wait until the Accept arrives — implementations differ

Step 2: Bob's server receives the Follow

On receiving the Follow in Bob's inbox, Bob's server:

  1. Validates the HTTP Signature on the request (to confirm it came from Alice's server)
  2. Checks whether Bob has manuallyApprovesFollowers: true or false
  3. Either queues a follow request for Bob to approve (locked account), or automatically proceeds to send an Accept

At this stage the follow is pending — Alice is not yet in Bob's followers collection.

Step 3: Bob's server sends an Accept (or Reject)

For unlocked accounts — Accept is sent automatically:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://bob.example/activities/accept-1",
  "type": "Accept",
  "actor": "https://bob.example/users/bob",
  "object": {
    "type": "Follow",
    "actor": "https://alice.example/users/alice",
    "object": "https://bob.example/users/bob"
  }
}

The object of the Accept is the original Follow activity (or just its id URI — either form is acceptable).

For locked accounts — Bob manually approves or denies. If denied, a Reject is sent with the same structure:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://bob.example/activities/reject-1",
  "type": "Reject",
  "actor": "https://bob.example/users/bob",
  "object": "https://alice.example/activities/follow-1"
}

Important spec note: Servers MAY choose to not send a Reject at all (e.g. to protect a user's privacy — not rejecting leaks the fact that the account exists). This means the follow request may be silently ignored, leaving Alice's server in an indefinite pending state. Implementations should handle this gracefully.

Step 4: Alice's server receives the Accept

On receiving the Accept:

  • Alice's server adds Bob to Alice's following collection
  • Bob's server adds Alice to Bob's followers collection
  • The follow relationship is now active

From this point on, when Bob creates a post addressed to his followers, his server will deliver it to Alice's inbox.


3. Unfollowing — The Undo Follow

To unfollow, Alice sends an Undo activity wrapping the original Follow:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://alice.example/activities/undo-follow-1",
  "type": "Undo",
  "actor": "https://alice.example/users/alice",
  "object": {
    "type": "Follow",
    "actor": "https://alice.example/users/alice",
    "object": "https://bob.example/users/bob"
  }
}

This is POSTed to Bob's inbox. On receipt, Bob's server removes Alice from Bob's followers collection. Alice's server removes Bob from Alice's following collection.

The spec requires that the Undo and the activity being undone have the same actor. You cannot undo another actor's Follow.


4. The followers and following Collections

Both are OrderedCollection objects. They may be paginated with OrderedCollectionPage. The actor object contains their URLs; fetching those URLs with Accept: application/activity+json returns the collection.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://bob.example/users/bob/followers",
  "type": "OrderedCollection",
  "totalItems": 412,
  "first": "https://bob.example/users/bob/followers?page=1"
}

Implementations may choose to hide the actual members of these collections for privacy (returning totalItems but an empty items array, or omitting first/next page links). This is valid and common.


5. How Content is Delivered to Followers

When Bob creates a public post, his server must deliver it to all his followers. This is where the follow relationship does its work.

Addressing

A public post addressed to followers is typically addressed as:

{
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://bob.example/users/bob/followers"]
}

A followers-only post omits the public audience:

{
  "to": ["https://bob.example/users/bob/followers"],
  "cc": []
}

Delivery mechanics

Bob's server must POST the Create activity to the inbox of every actor in Bob's followers collection. For followers on many different servers, this can mean hundreds of HTTP POST requests.

Shared inbox optimisation

To avoid sending N requests to the same server (when multiple followers are on the same instance), the actor object may declare a sharedInbox:

{
  "endpoints": {
    "sharedInbox": "https://alice.example/inbox"
  }
}

When a sharedInbox is available, the sending server can POST once to that shared inbox instead of once per follower on that instance. The receiving server then fans out internally to all relevant local followers. Mastodon always provides a shared inbox. Using it is optional but strongly recommended for performance.


6. Visibility Levels and the to/cc Fields

The follow relationship determines what appears in a follower's Home timeline. The to and cc fields on activities determine visibility:

Visibilitytocc
Publicas:Publicfollowers collection
Unlistedfollowers collectionas:Public
Followers-onlyfollowers collection(empty)
Direct (mention-only)mentioned actors(empty)

The special URI https://www.w3.org/ns/activitystreams#Public (often written as as:Public) signals that the post is publicly accessible.

Posts addressed to followers-only are only delivered to followers' inboxes, not crawlable publicly. A server receiving such a post should only show it to users who follow the author.


7. Locked Accounts and Pending Requests

When manuallyApprovesFollowers is true:

  • Incoming Follow activities are queued, not immediately accepted
  • The follower sees a "pending" state in the UI
  • The followed user sees a follow request notification
  • They can Accept (sending an Accept activity) or Reject (sending a Reject activity, or silently ignoring it)
  • Until accepted, the follower does NOT receive the account's posts

There is no standard way for a server to query whether a pending follow request has been accepted or rejected — implementations typically rely on eventually receiving an Accept or Reject, or timing out.


8. Account Migration — The Move Activity

ActivityPub does not natively support moving an account between servers, but a convention has emerged (led by Mastodon) using the Move activity and the alsoKnownAs / movedTo properties.

The process

  1. New account declares alsoKnownAs pointing to the old account:

    {
      "type": "Person",
      "id": "https://new.example/users/alice",
      "alsoKnownAs": ["https://old.example/users/alice"]
    }
    
  2. Old account sends a Move activity to all its followers:

    {
      "@context": "https://www.w3.org/ns/activitystreams",
      "type": "Move",
      "actor": "https://old.example/users/alice",
      "object": "https://old.example/users/alice",
      "target": "https://new.example/users/alice"
    }
    
  3. Receiving servers (i.e. servers that have followers of the old account) automatically re-issue a Follow from each of those followers to the new account, effectively migrating the follower list.

Important limitations

  • Only followers are migrated — not posts, likes, bookmarks, or lists
  • The old account's posts remain on the old server (or disappear if the server is shut down)
  • Not all implementations support Move — GotoSocial notably lacked support for a time
  • The alsoKnownAs must be set on the new account before the Move is sent from the old account, or receiving servers may reject it

9. Common Implementation Mistakes

  • Not waiting for Accept before adding to following: Adding the followee to following before the Accept arrives means the collection is inaccurate for locked accounts
  • Not handling silent Reject: If a locked account never sends a Reject, the pending state must time out gracefully
  • Not validating HTTP Signatures on incoming Follow activities: anyone could POST a fake Follow to your inbox
  • Sending Accept to the wrong URL: The Accept must be delivered to the inbox of the Follow's actor, not the object
  • Not using sharedInbox: Sending one request per follower per instance instead of using sharedInbox causes serious performance problems at scale
  • Forgetting to handle Undo Follow: When Alice unfollows Bob, Bob's server must remove Alice from the followers collection, or Alice will keep receiving Bob's posts
  • Exposing full followers list without privacy consideration: Some users expect their followers/following lists to be private; implementations should support hiding collection members while still providing totalItems

10. Summary: The Minimum a Correct Implementation Must Do

DirectionActivityRequired action
Outgoing followSend Follow to target's inboxAdd to local pending state
Incoming AcceptReceive in own inboxMove from pending → active; add to following
Incoming Reject (or silence)Receive in own inbox (or timeout)Remove from pending
Incoming FollowReceive in own inboxQueue or auto-accept; send Accept/Reject
Outgoing AcceptSend to follower's inboxAdd follower to followers collection
Outgoing unfollowSend Undo{Follow} to target's inboxRemove from following
Incoming Undo FollowReceive in own inboxRemove actor from followers collection
Delivering postsPOST Create to each follower's inbox (or sharedInbox)—

Fediverse Group Federation (FEP-1b12) — Complete Reference

Overview

Internet forums — communities where users submit posts and discuss topics — are implemented in ActivityPub using Group actors. FEP-1b12 (authored by Felix Ableitner / nutomic, received 2022-11-12, status FINAL since 2023-02-09) codifies the common patterns already used in production by Lemmy, Friendica, Hubzilla, Lotide, and PeerTube.

The core mechanism: a Group actor receives activities from users, validates them, wraps them in Announce activities, and distributes them to all followers. The audience property on objects identifies which group they belong to.


1. The Group Actor

Each forum/community is represented by a Group actor with standard ActivityPub endpoints:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Group",
  "id": "https://lemmy.example/c/technology",
  "preferredUsername": "technology",
  "name": "Technology",
  "inbox": "https://lemmy.example/c/technology/inbox",
  "outbox": "https://lemmy.example/c/technology/outbox",
  "followers": "https://lemmy.example/c/technology/followers",
  "attributedTo": "https://lemmy.example/c/technology/moderators"
}

The Group actor operates as an automated actor:

  • It accepts Follow requests automatically (for public groups)
  • It validates incoming activities and redistributes them
  • It is discovered via WebFinger like any other actor

Following a Group

Users follow a Group using the standard Follow/Accept handshake:

  1. User sends Follow to the group's inbox
  2. Group auto-accepts with an Accept{Follow} (public groups SHOULD do this)
  3. User is added to the group's followers collection
  4. From now on, the group distributes content to that user's inbox

Unfollowing uses Undo{Follow}, same as unfollowing a person.


2. The audience Property

The audience property (defined in ActivityStreams 2.0 but previously unused in the wild) identifies which group an object belongs to:

{
  "type": "Page",
  "id": "https://lemmy.example/post/123",
  "attributedTo": "https://alice.example/users/alice",
  "name": "Check out this new technology",
  "audience": "https://lemmy.example/c/technology"
}

Why audience instead of to or attributedTo

Before FEP-1b12, implementations placed the group identifier in various fields:

  • to/cc — requires URL resolution to determine if a recipient is a Group actor; mixed with other addressees
  • attributedTo — conflicts with the actual author of the post

audience solves this cleanly:

  • No extension needed (it's already in the ActivityStreams vocabulary)
  • Recipients can instantly identify the group without resolving URLs
  • Existing implementations that don't understand groups simply ignore it
  • Doesn't conflict with delivery addressing (to/cc) or authorship (attributedTo)

All objects and activities related to a group SHOULD include audience pointing to the group's id.


3. Threads and Comments

Top-level posts

Top-level posts (threads) are typically Page objects with a name property serving as the title:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Page",
  "id": "https://lemmy.example/post/123",
  "attributedTo": "https://alice.example/users/alice",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://lemmy.example/c/technology/followers"],
  "name": "Check out this new technology",
  "content": "<p>I found something interesting...</p>",
  "audience": "https://lemmy.example/c/technology"
}

The Page type is exemplary — implementations may use other types. The key distinction is that top-level posts have a name (title) while replies typically do not.

Replies (comments)

Replies are Note objects with inReplyTo linking to the parent:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Note",
  "id": "https://bob.example/comment/456",
  "attributedTo": "https://bob.example/users/bob",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://lemmy.example/c/technology/followers"],
  "inReplyTo": "https://lemmy.example/post/123",
  "content": "<p>Great find! Here is what I think...</p>",
  "audience": "https://lemmy.example/c/technology"
}

inReplyTo can point to the top-level post (for direct replies) or to another comment (for nested replies). Lemmy displays comments in a tree structure.

replies collection

Groups MAY maintain a replies collection on the group or on individual posts, enabling navigation of the thread hierarchy.


4. The Announce Wrapping Mechanism

This is the core of FEP-1b12 group federation. When a user submits content to a group, the group wraps it in an Announce and distributes it to all followers.

Flow

  1. Alice creates a post and sends Create{Page} to the group's inbox
  2. The group validates the activity (checks blocks, permissions)
  3. The group wraps it: Announce{Create{Page}}
  4. The group sends the Announce to all follower inboxes

What the Announce looks like

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Announce",
  "id": "https://lemmy.example/activities/announce/789",
  "actor": "https://lemmy.example/c/technology",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://lemmy.example/c/technology/followers"],
  "object": {
    "type": "Create",
    "id": "https://alice.example/activities/create/123",
    "actor": "https://alice.example/users/alice",
    "object": {
      "type": "Page",
      "id": "https://lemmy.example/post/123",
      "attributedTo": "https://alice.example/users/alice",
      "name": "Check out this new technology",
      "audience": "https://lemmy.example/c/technology"
    }
  }
}

What the Announce means

The Announce serves as proof that the group approved the content. Recipients can trust that the group validated the activity. After processing, recipients may optionally discard the Announce wrapper and work with the inner activity directly.

This mechanism supports any activity type — not just Create. Comments, updates, and moderation actions all flow through the same Announce wrapping.

Validation before Announcing

Groups SHOULD validate incoming activities before wrapping and distributing:

  • Check the sending actor/domain is not blocked
  • Optionally require the sender to be a follower
  • Optionally require moderator approval
  • Check the audience property matches this group
  • Groups MUST NOT forward activities that don't include the group in audience

5. Announce(Activity) vs Announce(Object)

FEP-1b12 specifies Announce(Activity) — wrapping the full Create activity inside the Announce. However, several major implementations send Announce(Object) — wrapping just the object directly.

ImplementationSendsAccepts
LemmyAnnounce(Activity) + Announce(Object) for Mastodon compatBoth
FriendicaAnnounce(Object)Both
HubzillaAnnounce(Object)Both
NodeBBAnnounce(Object)Both
Discourse—Both (added Object support for NodeBB compat)

The FEP author (nutomic) acknowledged not knowing about Announce(Object) usage when writing the spec. Community consensus is that Announce(Object) should be treated as shorthand for Announce(Create(Object)).

Recommendation for implementors: When sending, Announce(Activity) is spec-compliant. When receiving, accept both forms — treat Announce(Object) as equivalent to Announce(Create(Object)). The FEP's FINAL status makes formal amendment difficult, but real-world interoperability requires handling both.


6. Group Moderation

Group moderation is an optional feature defined in FEP-1b12, initially implemented only in Lemmy.

Moderator list

Moderators are listed in the group's attributedTo property, which resolves to a collection of actor URLs:

{
  "type": "Group",
  "id": "https://lemmy.example/c/technology",
  "attributedTo": "https://lemmy.example/c/technology/moderators"
}

The moderators collection:

{
  "type": "OrderedCollection",
  "id": "https://lemmy.example/c/technology/moderators",
  "orderedItems": [
    "https://alice.example/users/alice",
    "https://bob.example/users/bob"
  ]
}

Adding and removing moderators

Moderator changes use Add and Remove activities:

{
  "type": "Add",
  "actor": "https://alice.example/users/alice",
  "object": "https://charlie.example/users/charlie",
  "target": "https://lemmy.example/c/technology/moderators"
}

The actor performing the Add/Remove MUST already appear in the attributedTo collection (i.e., must already be a moderator).

Content moderation

Moderators remove content using Remove activities (not Delete — the ActivityPub spec implies Delete should only come from the object's author):

{
  "type": "Remove",
  "actor": "https://alice.example/users/alice",
  "object": "https://lemmy.example/post/123",
  "target": "https://lemmy.example/c/technology"
}

Distribution of moderation actions

Moderation activities MUST also be wrapped in Announce by the group and distributed to all followers, so moderation takes effect across all federated instances.

Server administrators can also send moderation activities. The group must wrap these in Announce for distribution.


7. Interoperability with Non-Group-Aware Software

A key design goal of FEP-1b12 is backward compatibility with software that doesn't understand groups (e.g., Mastodon).

How it works

When a group sends Announce{Create{Note}} to a Mastodon user who follows the group, Mastodon sees it as a regular boost/reblog. The user sees the content in their timeline attributed to the original author, with the group shown as the booster. This is imperfect but functional.

Known issues

  • Mastodon reply routing: Mastodon sends replies only to mentioned actors, not to the group. The group never receives the reply and cannot redistribute it to other followers. This breaks cross-instance comment threading.
  • Vote/Like counts: Likes sent to the post author's inbox are processed locally but not announced by the group to followers, causing count discrepancies across instances.
  • Hubzilla workaround: Hubzilla historically made the forum owner appear as the post author since "Mastodon will reject or ignore any messages from people you don't follow."
  • Mastodon's own groups: Mastodon's pending groups PR (#19059) uses FEP-400e instead, which is incompatible with FEP-1b12. A Mastodon developer (Claire) argued that FEP-1b12's compatibility with non-group-aware software is actually a problem because it prevents enforcing group-specific interaction semantics (like preventing reblogging of group posts).

8. FEP-1b12 vs FEP-400e (Publicly Appendable Collections)

Two incompatible approaches to groups exist in the fediverse:

FEP-1b12FEP-400e
MechanismGroup wraps activities in AnnounceActors send Add to group's wall collection
Group identificationaudience propertywall property on Group actor
Content distributionGroup sends Announce to followersGroup sends Add to followers
DetectionCheck for Group type + audience usageCheck for wall property on actor
StatusFINAL—
AdoptionLemmy, Friendica, Hubzilla, Lotide, PeerTube, Kbin, NodeBBSmithereen (~25 MAU), Mastodon (pending PR)

FEP-1b12 is the de-facto standard used by the vast majority of group implementations. FEP-400e is currently only implemented by Smithereen and proposed for Mastodon.

There is no way to detect which approach a Group actor uses from the actor document alone without checking for the presence of a wall property. trwnh noted there is "nothing actually special about the Group type" in ActivityStreams 2.0 — the behavior must be inferred.


9. Implementation Matrix

PlatformGroup TypeaudienceAnnounce wrappingModerationNotes
LemmyCommunity = GroupYes (since 0.17.0)Announce(Activity) + Announce(Object)Full (attributedTo)Reference implementation
FriendicaForum = GroupYesAnnounce(Object)YesFederated forums since 2019.03
HubzillaForum = GroupYesAnnounce(Object)YesWorkaround for Mastodon compat
LotideCommunity = GroupYesYes——
PeerTubeChannel = GroupYesYes—Video-oriented
Kbin/MbinMagazine = GroupYesYesYesLemmy-compatible
NodeBBCategory = GroupYes (deviation)Announce(Object)—Categories only; audience at 2nd-order parent
GuppeAuto-group = GroupNoAnnounce(Object)No~200 lines; simplest possible group (boost bot)
MastodonPendingNoNo (uses FEP-400e)—PR #19059; incompatible with FEP-1b12

10. Creating a Post in a Group — Complete Flow

This section traces the full lifecycle of a group post.

Step 1: User creates a post

Alice writes a post for the Technology community and sends it to the group's inbox:

{
  "type": "Create",
  "actor": "https://alice.example/users/alice",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://lemmy.example/c/technology"],
  "object": {
    "type": "Page",
    "attributedTo": "https://alice.example/users/alice",
    "name": "Check out this new technology",
    "content": "<p>I found something interesting...</p>",
    "audience": "https://lemmy.example/c/technology"
  }
}

Step 2: Group validates

The group checks:

  • Alice is not blocked
  • The domain is not blocked
  • audience matches this group
  • (Optional) Alice is a follower
  • (Optional) Moderator approval required

Step 3: Group announces

The group wraps and distributes:

{
  "type": "Announce",
  "actor": "https://lemmy.example/c/technology",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://lemmy.example/c/technology/followers"],
  "object": {
    "type": "Create",
    "actor": "https://alice.example/users/alice",
    "object": { ... }
  }
}

Step 4: Followers receive

Bob (on a different server) receives the Announce in his inbox. His server:

  1. Verifies the Announce came from the group (HTTP Signature check)
  2. Extracts the inner Create{Page}
  3. Displays the post in the Technology community feed
  4. The Announce wrapper serves as proof the group approved this content

Step 5: Bob replies

Bob sends a reply (Create{Note} with inReplyTo) to the group's inbox. The group validates and announces it to all followers.


11. Discovery

Groups are discoverable via WebFinger. Lemmy uses the ! prefix convention for communities:

GET /.well-known/webfinger?resource=acct:technology@lemmy.example

The response includes a self link with type: Group in properties:

{
  "rel": "self",
  "type": "application/activity+json",
  "href": "https://lemmy.example/c/technology",
  "properties": {
    "https://www.w3.org/ns/activitystreams#type": "Group"
  }
}

The ! prefix is a Lemmy UI convention, not a protocol requirement. NodeBB uses @ prefix like regular actors. The WebFinger response's type: Group property is the canonical way to detect a group.


12. Known Issues and Pitfalls

  • Mastodon reply routing: Mastodon doesn't include the group in replies, so the group can't redistribute them. This is the biggest cross-platform interop issue.
  • Announce(Object) non-compliance: Hubzilla, Friendica, and NodeBB send Announce(Object) which is technically non-compliant. Consumers must accept both forms.
  • Vote count discrepancies: Likes/dislikes sent to post author instead of group are not redistributed, causing different counts on different instances.
  • No <h1> in Page titles: The title goes in name, not in HTML content.
  • Delete vs Remove: Use Remove for moderation actions, not Delete. Delete implies the actor is the author of the object.
  • Private groups: FEP-1b12 explicitly removed private groups from scope. Lemmy and Friendica implement them independently by restricting activity visibility to followers only and verifying member lists.
  • Group detection: There is no reliable way to distinguish a FEP-1b12 group from a FEP-400e group from the actor document alone without checking for a wall property.

Fediverse Hashtags — Complete Reference

Overview

Hashtags on the Fediverse work differently from centralised platforms. Because there is no global index, what a user sees under a hashtag is determined by what their particular server has observed — not a complete picture of the whole network.


1. The ActivityPub Wire Format

The Hashtag type

Hashtag is not a standard ActivityStreams 2.0 type. It was introduced by Mastodon and placed in the as: namespace (https://www.w3.org/ns/activitystreams#Hashtag), even though it was never formally added to the ActivityStreams context document. It has since been formalised in the ActivityPub Miscellaneous Terms extension (https://purl.archive.org/miscellany), but most implementations still declare it via the as: namespace for compatibility.

The Hashtag type is a subtype of Link, not of Object. This matters: it should not have an id property in strict JSON-LD terms, though some implementations add one anyway.

Declaring Hashtag in @context

There are two common patterns in the wild:

Pattern A — inline in @context (Mastodon, Pixelfed style):

"@context": [
  "https://www.w3.org/ns/activitystreams",
  {
    "Hashtag": "as:Hashtag"
  }
]

Pattern B — via the Miscellany extension:

"@context": [
  "https://www.w3.org/ns/activitystreams",
  "https://purl.archive.org/miscellany"
]

Both resolve to the same URI. Pattern A is more common in existing implementations. Pattern B is the more formally correct approach.

Attaching a hashtag to a Note

Hashtags are expressed in the tag array of an object (usually a Note). Each entry is a Hashtag object with:

  • type: "Hashtag" (required)
  • href: URL of a page listing content with this tag (required — this is what makes it a Link subtype)
  • name: the hashtag string, conventionally including the # prefix
{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    { "Hashtag": "as:Hashtag" }
  ],
  "id": "https://example.com/notes/1",
  "type": "Note",
  "attributedTo": "https://example.com/users/alice",
  "content": "<p>Watching the eclipse! <a href='https://example.com/tags/eclipse2024' class='mention hashtag' rel='tag'>#<span>eclipse2024</span></a></p>",
  "tag": [
    {
      "type": "Hashtag",
      "href": "https://example.com/tags/eclipse2024",
      "name": "#eclipse2024"
    }
  ]
}

The tag array can hold multiple types

The tag array is shared by Hashtag, Mention, and Emoji entries. Implementations must check type to differentiate them:

"tag": [
  { "type": "Mention",  "href": "https://other.example/users/bob", "name": "@bob@other.example" },
  { "type": "Hashtag",  "href": "https://example.com/tags/cats",   "name": "#cats" },
  { "type": "Emoji",    "id":   "https://example.com/emoji/42",    "name": ":blobcat:" }
]

The dual representation problem

Hashtags appear in two places in an ActivityPub object, and both must be consistent:

  1. tag array — the structured metadata, used by receiving servers to index the post under that tag
  2. content field — the HTML body, where hashtags appear as <a> links with rel="tag" and class="mention hashtag"

If the tag array entry is missing, receiving servers may not index the post under that hashtag at all, even if the #word appears visibly in the content. If the content link is missing or malformed, the hashtag may not be clickable or display correctly.


2. Case Sensitivity

Case handling is one of the most inconsistent areas of Fediverse hashtag implementation.

The name field vs. the href field:

  • The href (and the path used in URLs like /tags/eclipse2024) is typically lowercased
  • The name field may preserve the original capitalisation the author typed ("#Eclipse2024") or may be lowercased

Mastodon's behaviour:

  • Stores tags lowercased internally
  • The name field in the outgoing ActivityPub object reflects the database canonical form, not necessarily what the author typed
  • href is always lowercase

CamelCase for accessibility: Users are encouraged to write hashtags in CamelCase (#DogsAtPollingStations rather than #dogsatpollingstations) because screen readers can parse individual words from CamelCase. This is a widely-promoted Fediverse convention, not a technical requirement.

Interoperability implication: When processing incoming Hashtag objects, implementations should normalise the tag name to lowercase before indexing or comparing, since #Cats, #cats, and #CATS all refer to the same tag.


3. Featured Hashtags

Mastodon allows users to pin hashtags to their profile. This is implemented as an extra featuredTags property on the actor object pointing to a Collection of Hashtag objects:

{
  "id": "https://mastodon.example/@alice",
  "type": "Person",
  "featuredTags": "https://mastodon.example/@alice/collections/tags"
}

The featuredTags term is defined in the Mastodon namespace: http://joinmastodon.org/ns#featuredTags.


4. How Hashtag Federation Works (and Why It's Incomplete)

This is the most important and most misunderstood aspect of Fediverse hashtags.

There is no global hashtag index

Unlike centralised platforms, no server has a complete view of all posts under a hashtag across the entire network. A server only indexes posts it has received.

A server receives a post if:

  • A local user follows the author
  • A local user has boosted/replied to the post (pulling it into a thread)
  • The server subscribes to a relay that delivered the post
  • The post was explicitly fetched (e.g., by pasting a URL into the search bar)

Following a hashtag is a local filter

When a user on Mastodon "follows" a hashtag, it is not a network-level subscription. It is a client-side filter on the server's federated timeline. The server does not send any ActivityPub messages to announce this follow. Posts under that hashtag only appear in the user's timeline if the server would have received them anyway.

Following hashtags does not cause the server to go out and fetch posts from other servers that use that hashtag. This is a common point of confusion.

Relays expand the picture

Relays are ActivityPub actors that re-broadcast public posts from many servers to subscribers. A server admin can subscribe to a relay to increase the volume of posts the server receives. Some relays (like FediBuzz) allow filtering by hashtag, so a server can subscribe to receive only posts tagged with specific hashtags. This is an admin-level operation, not something individual users can do.

The RSS workaround

Most Fediverse servers expose a public RSS feed for each hashtag timeline:

https://{server}/tags/{tagname}.rss

This can be used to subscribe to a hashtag's timeline on a specific server via any feed reader.

Some Fediverse servers instead expose a public Atom feed for each hashtag timeline:

https://{server}/tags/{tagname}.atom

5. Hashtag URLs and Tag Pages

The href in a Hashtag object points to a human-readable page showing posts with that tag. The URL convention varies by platform:

PlatformTag page URL pattern
Mastodon/tags/{tagname}
Pixelfed/discover/tags/{tagname}
Misskey / Calckey/tags/{tagname}
PeerTube/search/videos?tagsOneOf={tagname}
Pleroma / Akkoma/tag/{tagname}

The href should always link to the originating server's tag page, not to any other server's.


6. Hashtag as an Actor (Experimental)

The W3C ActivityPub Primer describes an experimental approach where a Hashtag object is given inbox and outbox properties, making it a followable actor. This would allow true network-level hashtag subscription via ActivityPub's follow mechanism:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://purl.archive.org/miscellany"
  ],
  "type": "Hashtag",
  "id": "https://example.org/hashtag/cats",
  "href": "https://example.org/tags/cats",
  "name": "#cats",
  "inbox": "https://example.org/hashtag/cats/inbox",
  "outbox": "https://example.org/hashtag/cats/outbox"
}

This is not widely implemented and has known problems: Hashtag is a Link subtype, making id and inbox/outbox properties unusual; and many implementations only allow standard AS2 actor types (Person, Organization, Service, etc.) to be followed.


7. Common Implementation Mistakes

  • Missing tag array entry: including #hashtag in content HTML but omitting the structured Hashtag entry in tag — receiving servers may not index it
  • Wrong href host: pointing href at a different server's tag page rather than the originating server's
  • Including # in href: the href URL path should not contain #, which is a URL fragment character — use /tags/cats not /tags/#cats
  • Omitting name prefix: some implementations send "name": "cats" without the # — conventions vary, but including # is more common and matches Mastodon's behaviour
  • Case mismatch: href is lowercase but name has mixed case — this is acceptable but can cause confusion; be consistent
  • Not including Hashtag in @context: sending "type": "Hashtag" without declaring it in @context means strict JSON-LD parsers will reject or ignore it

8. Summary: What a Correct Implementation Looks Like

A server that correctly implements hashtags should:

  1. Parse incoming tag arrays, identify entries with type: "Hashtag", and index the post under the normalised (lowercased) tag name
  2. When creating a post with hashtags, populate both the tag array (structured metadata) and the content HTML (linked #tag anchors)
  3. Declare Hashtag in the @context of outgoing objects
  4. Expose a tag timeline page at a stable URL (typically /tags/{name})
  5. Set the href of each Hashtag entry to point to that tag timeline page
  6. Optionally expose an RSS feed at /tags/{name}.rss
  7. Optionally expose an Atom feed at /tags/{name}.atom
  8. Accept incoming posts and index them under their hashtags so local users can search and follow those tags

Fediverse HTTP Signatures — Complete Reference

Overview

ActivityPub does not specify an authentication mechanism in its core spec. In practice, the Fediverse has converged on HTTP Signatures (draft-cavage-12, formally draft-cavage-http-signatures) for server-to-server authentication. When one server POSTs an activity to another server's inbox, it signs the request so the receiving server can verify the sender's identity.

The spec being used is draft-cavage-http-signatures-12 — an expired IETF Internet Draft, not an RFC. It has been superseded by RFC 9421, but the Fediverse has not yet migrated to RFC 9421 at any meaningful scale. Treat cavage-12 as the working standard for all current implementations.


1. The Public Key Model

Each actor (user) has an asymmetric keypair. The private key stays on the server; the public key is published in the actor document under the publicKey property, using the LD Security Vocabulary v1:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1"
  ],
  "type": "Person",
  "id": "https://example.com/users/alice",
  "inbox": "https://example.com/users/alice/inbox",
  "publicKey": {
    "id": "https://example.com/users/alice#main-key",
    "owner": "https://example.com/users/alice",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIB...\n-----END PUBLIC KEY-----"
  }
}

Key points:

  • publicKey may be a single object, a single id string, or an array
  • The key object's id is the keyId used in the Signature header
  • owner (or controller) links back to the actor for verification
  • The key is RSA by default; Ed25519 is more modern but not yet widely supported across the Fediverse
  • Generate 2048-bit RSA minimum; 4096-bit is common
  • The PEM encoding may be PKCS-1 (-----BEGIN RSA PUBLIC KEY-----) or PKCS-8/SPKI (-----BEGIN PUBLIC KEY-----); crypto libraries generally auto-detect the format

2. How to Sign a Request

The standard set of headers to sign for a POST (inbox delivery):

(request-target)
host
date
digest
content-type

For a GET request, omit digest and content-type.

Step-by-step signing

1. Generate the Digest header (POST only)

SHA-256=<base64(sha256(request_body))>

For an empty body, the SHA-256 of an empty string is always:

SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

Use standard base64 with padding. Do NOT use URL-safe base64. Do NOT use the variant that inserts newlines every 60 characters (e.g. Ruby's Base64.encode64 — use Base64.strict_encode64 instead).

2. Construct the signing string

Each header becomes one line: headername: value. Header names must be lowercased. Lines are joined with \n (ASCII newline, 0x0A). There must be NO trailing newline after the last line.

The (request-target) pseudo-header is constructed as:

(request-target): post /users/alice/inbox

i.e. method_lowercase + " " + path_and_query.

Example signing string for a POST:

(request-target): post /users/alice/inbox
host: example.com
date: Mon, 01 Jan 2024 12:00:00 GMT
digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
content-type: application/activity+json

3. Sign the string

Sign the signing string with the actor's RSA private key using RSASSA-PKCS1-v1_5 with SHA-256 (i.e. rsa-sha256). Base64-encode the resulting bytes (standard base64 with padding).

4. Set the Signature header

Signature: keyId="https://example.com/users/alice#main-key",
           algorithm="hs2019",
           headers="(request-target) host date digest content-type",
           signature="<base64-encoded-signature>"

Use hs2019 as the algorithm value — it is a placeholder meaning "determine the algorithm from the key metadata." Do not use rsa-sha256 as the algorithm string in new implementations (see quirks).

Use the Signature header, not Authorization: Signature ....


3. How to Verify a Signature

1. Extract the Signature header

Parse the keyId, headers, algorithm, and signature parameters.

2. Resolve the public key (see Section 4 below)

3. Reconstruct the signing string

Using the same headers list from the signature and the actual request values, rebuild the signing string using the same rules as signing: lowercased header names, \n-separated, no trailing newline.

4. Verify the Digest (if present and it was in the signed headers)

Compute SHA-256 of the request body and compare to the Digest header. If they don't match, reject — the body was tampered with.

5. Check the Date header

Compare to current time. Reject if the skew is too large. A window of approximately ±1 hour is the community consensus (see quirks for implementation-specific values).

6. Verify the cryptographic signature

Use the public key and the reconstructed signing string to verify the base64-decoded signature value. If verification fails with a cached key, re-fetch the key from the origin (the actor may have rotated their key) and try once more before rejecting.

7. Return 401 if verification fails (when a signature is required).


4. Resolving a keyId to a Public Key

The keyId is a URL. Resolving it to an actual public key requires care because two patterns exist in the wild:

Pattern A — Fragment URI (Mastodon style)

keyId = "https://example.com/users/alice#main-key"

  • Strip the fragment: fetch https://example.com/users/alice
  • The response is the actor document
  • Find publicKey in the actor; if it's an array, find the entry whose id matches the full keyId including the fragment
  • Verify the key's id matches the original keyId exactly

Pattern B — Path URI (GoToSocial style)

keyId = "https://example.com/users/alice/main-key"

  • Fetch the URL directly
  • The response is a raw Key object (not a full actor), containing publicKeyPem and an owner (or controller) property
  • Follow owner to fetch the full actor and verify the key is authorized

In both cases: always verify that the key's id matches the keyId from the Signature header, and that the key's owner/controller matches the expected actor. Never trust a key that doesn't pass this check.


5. Authorized Fetch (Secure Mode)

Some servers require HTTP Signatures on GET requests as well as POST requests. This is called "authorized fetch" or "secure mode" (Mastodon's term). In this mode:

  • Fetching an actor, object, or collection requires a signed GET
  • The signing actor is typically the instance actor (see Section 6)
  • Servers use this to block data access from defederated instances
  • GoToSocial requires signed GETs in all modes
  • Mastodon only requires them when secure mode is explicitly enabled

If you're building an implementation and encounter 401 responses to unsigned GETs, the remote server has authorized fetch enabled.


6. Instance Actors

Most servers maintain a special instance-level actor (separate from any user) used to sign GET requests on behalf of the server itself. This is used for fetching remote objects without attributing the fetch to a specific user.

The instance actor typically has a well-known URL such as:

  • https://example.com/actor
  • https://example.com/users/instanceactor

When fetching a remote object to verify it (e.g. during signature verification of an incoming activity), you should use the instance actor's key to sign the outbound GET. Remote servers generally do not attempt to verify the signature on requests made to resolve a keyId for the first time.


7. Key Rotation

If an actor rotates their keypair, the old public key is no longer valid. Implementations must handle this:

  1. Verification fails with the cached key
  2. Re-fetch the actor document from the source (bypass cache)
  3. Retry verification with the new key
  4. If it succeeds, update your local cache

Without this retry logic, federation will break every time a user's key is rotated.


8. Interoperability Quirks

This section documents known bugs, deviations, and incompatibilities across Fediverse implementations. These are real-world issues that have caused federation failures.

8.1 Query String in (request-target)

Mastodon historically omitted query strings from (request-target), signing only the path. GoToSocial included query parameters, which broke paged Collection fetches.

Both now use a double-attempt strategy:

  • Signing: sign with query params; if remote returns 401, retry without
  • Verification: verify with query params; if it fails, retry without

If implementing signature verification for paged collections, support both.

8.2 hs2019 Algorithm Interpretation

hs2019 is a placeholder meaning "determine algorithm from key metadata." Different implementations interpret it inconsistently:

ImplementationInterpretation of hs2019
MastodonRSA-SHA256
PeerTubeRSA-SHA512
GoToSocialSigns as RSA-SHA256; verifies RSA-SHA256, RSA-SHA512, Ed25519 in order
LemmySends hs2019 string

Recommendation: When verifying hs2019, try RSA-SHA256 first, then RSA-SHA512, then Ed25519. When signing, use RSA-SHA256.

8.3 (created) and (expires) Pseudo-Headers

Mastodon rejects (created) and (expires) unless the algorithm is hs2019. Sending algorithm="rsa-sha256" with (created) in the headers list produces:

"Invalid pseudo-header (created) for rsa-sha256"

Older Pleroma versions do not support (created) at all. GoToSocial v0.16.0-rc1 temporarily switched to (created) instead of Date, breaking federation with Akkoma/Pleroma and Bookwyrm — it was reverted.

Recommendation: Use Date rather than (created) for maximum compatibility.

8.4 URL Encoding in (request-target)

Pleroma does not URL-decode the request-target path before constructing the signing string. Mastodon does URL-decode it. If an inbox path contains percent-encoded characters (e.g. %40), one side signs the encoded form and the other verifies against the decoded form — silent failure.

Security note: Percent-encoded newlines (%0A) in a path could inject fake header lines into the signing string if the path is decoded before signing string construction.

Recommendation: Use the path as-is on the wire without decoding. Be aware that web frameworks (Rails, ASP.NET) may auto-decode before your application sees the path.

8.5 Signature Header vs Authorization Header

Both are defined in cavage. In practice, virtually all Fediverse implementations use only the Signature header. Mastodon does not fall back to Authorization: Signature ....

Recommendation: Always use the Signature header.

8.6 Clock Skew Tolerance

Tolerance windows vary widely across implementations:

ImplementationTolerance window
Mastodon±1 hour (CLOCK_SKEW_MARGIN), max 12 hours (EXPIRATION_WINDOW_LIMIT)
Pleroma/AkkomaUp to 2 hours old, max 40 minutes in the future
SWICG recommendation~1 hour plus a few minutes buffer
Some implementationsAs tight as 30 seconds

If your server's clock is significantly wrong, or a remote server's clock is wrong, signatures will fail. NTP synchronisation is essential.

8.7 keyId Format Divergence

ImplementationkeyId formatDereferencing
MastodonFragment URI: …/users/alice#main-keyReturns full actor; key identified by fragment
GoToSocialPath URI: …/users/alice/main-keyReturns key stub with owner back-link

Receivers must handle both. When the keyId contains a fragment, strip it before fetching. When the fetched document is a raw Key (not an actor), follow owner/controller to the actor.

If publicKey is an array in the actor, match keyId against each key's id to find the right one.

8.8 Digest Header

Mastodon only accepts SHA-256. Sending SHA-512=... alone will be rejected. Mastodon validates that the decoded digest is exactly 32 bytes.

Case sensitivity: Mastodon lowercases the algorithm name when parsing and checks for sha-256. The canonical format in the wild is uppercase SHA-256=. Mixed case is accepted by Mastodon but may not be by others.

Empty body: A POST with an empty body MUST include a Digest of the empty string: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

RFC 9530 rename: RFC 9530 renames Digest to Content-Digest. Mastodon 4.5+ accepts both. Most implementations still send the old Digest header. Send Digest for compatibility; accept both.

8.9 Base64 Encoding

Use standard base64 with padding — not URL-safe base64.

In Ruby, use Base64.strict_encode64, NOT Base64.encode64 — the latter inserts newlines every 60 characters per RFC 2045, which breaks verification on the receiving side.

8.10 Multi-Value Header Concatenation

The spec requires multiple values for the same header to be concatenated with , (comma-space). Pixelfed historically did not comma-separate values, causing verification failures against GoToSocial and Mastodon in secure mode. Fixed in Pixelfed PR #4504.

8.11 Trailing Newline in Signing String

The signing string must not include a trailing \n after the last line. This is a common silent failure — the signature is generated with a trailing newline, which doesn't match the signature generated without one during verification. Multiple SocialHub discussions document this as one of the most frequent implementation bugs.

8.12 Unsigned GET Requests

Pixelfed did not sign GET requests until 2021, breaking federation with any server running authorized fetch / secure mode. GoToSocial requires signed GETs in all modes.

Recommendation: Sign GET requests. Use the instance actor for GET requests not attributable to a specific user.

8.13 PeerTube Signature Header Prefix Bug (Fixed)

PeerTube v2.1.1 prefixed the Signature header value with the literal string "Signature ", producing Signature: Signature keyId=.... This was caused by an older version of the http-signature npm library. Fixed in PeerTube v2.2. Mentioned here because old PeerTube instances may still be in the wild.

8.14 Misskey Digest/Host Validation Bug (Fixed — CVE-2023-49079)

Misskey prior to v2023.11.1 did not validate the Digest or Host headers — only the cryptographic signature was checked. This allowed attackers to craft requests with valid signatures but spoofed bodies, impersonating any remote user. CVSS 9.3 Critical.

Implication for implementors: Always validate Digest and Host as part of signature verification, not just the cryptographic signature itself.

8.15 Reverse Proxy / Host Header Issues

When a reverse proxy rewrites the Host header, the signed host value won't match what the application sees. In nginx, use proxy_set_header Host $host.

A documented case: Ghost on AWS behind CloudFront had federation break because CloudFront sends CloudFront-Forwarded-Proto instead of the standard X-Forwarded-Proto, causing the app to generate HTTP URLs instead of HTTPS, breaking actor ID matching and signature verification.

8.16 IDN / Punycode in Host Headers

Instances with non-ASCII domain names (e.g., Cyrillic) store the punycode version internally but may receive the Unicode version in incoming requests. If the local server compares against punycode and the incoming host header is Unicode (or vice versa), signature verification of the host header fails.

Recommendation: Use ASCII/punycode in all URLs and Host headers.

8.17 HTTP/1.1 Line Folding

The cavage-12 canonicalization algorithm does not account for HTTP/1.1 obs-fold (continuation lines starting with whitespace). While line folding is deprecated, it could still appear from legacy clients or proxies. Most implementations do not handle it.

8.18 Shared Library Landscape

Very few implementations share HTTP signature code:

LibraryUsed by
@peertube/http-signature (npm)PeerTube, Misskey
pleroma/http_signatures (Elixir)Pleroma, Mobilizon
Everyone elseCustom implementations

This is why the same spec ambiguity can be interpreted differently by 10+ independent codebases — there is no shared reference implementation to enforce consistency.


9. Debugging Checklist

When signatures fail, check in this order:

  1. Clock skew — is the Date header within tolerance? Check NTP on both servers.
  2. Trailing newline — is the signing string missing a trailing \n, or does it have one it shouldn't?
  3. Header name case — are all header names lowercased in the signing string?
  4. (request-target) construction — is it method_lowercase + " " + path? Does path include or exclude query string? (Try both.)
  5. Digest mismatch — does the Digest header match the actual body? Empty body is not the same as no body.
  6. Base64 encoding — is the signature standard base64 with padding and no embedded newlines?
  7. keyId resolution — does the fetched key's id match the keyId exactly (including fragment)?
  8. Key rotation — is the cached key stale? Try re-fetching the actor.
  9. Reverse proxy — is the Host header being rewritten before the application sees it?
  10. Algorithm mismatch — if remote is PeerTube, try RSA-SHA512 in addition to RSA-SHA256.

10. Minimum Required Headers (Consensus)

Request typeRequired in signed headers
POST (inbox delivery)(request-target), host, date, digest, content-type
GET (authorized fetch)(request-target), host, date

Most Fediverse software will reject POST requests without a signed Digest, and GET requests without a signed (request-target), in order to prevent replay attacks.

Fediverse JSON-LD — Complete Reference

Overview

ActivityPub and ActivityStreams 2.0 use JSON-LD as their data format. JSON-LD (JSON for Linking Data) is a W3C standard that extends JSON with semantic meaning by mapping property names to IRIs via a @context.

In practice, most Fediverse implementations do not perform full JSON-LD processing. They treat ActivityPub messages as plain JSON, looking up properties by their short names and ignoring the @context. This mostly works but creates real interoperability problems around value form variability, extensions, and namespace collisions.

Understanding both what JSON-LD specifies and what implementations actually do is essential for building software that federates correctly.


1. @id vs id, @type vs type — Keyword Aliasing

The ActivityStreams aliases

The ActivityStreams 2.0 context (https://www.w3.org/ns/activitystreams) defines these aliases:

{
  "id": "@id",
  "type": "@type"
}

This means "id" and "@id" are semantically identical in any document using the ActivityStreams context, as are "type" and "@type". Both of these are valid and mean the same thing:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "@id": "https://example.com/users/alice",
  "@type": "Person"
}
{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://example.com/users/alice",
  "type": "Person"
}

The Fediverse overwhelmingly uses the aliased forms (id, type). The @-prefixed forms are rarely seen in practice but are semantically equivalent.

Rules of keyword aliasing

  • Any JSON-LD keyword can be aliased except @context itself
  • An alias is defined in @context as "myAlias": "@keyword"
  • The alias and the keyword are interchangeable in the document
  • After JSON-LD expansion, aliases revert to their @-prefixed forms

When implementing

Accept both forms. When producing documents, use the aliased forms (id, type) for maximum compatibility with Fediverse software.


2. The @context — What It Does and When It's Optional

Purpose

The @context maps short property names (terms) to full IRIs. It tells a JSON-LD processor what each property means semantically:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Note",
  "content": "Hello, world!"
}

Here, @context maps "content" to https://www.w3.org/ns/activitystreams#content and "Note" to https://www.w3.org/ns/activitystreams#Note.

Three forms @context can take

A single URL string:

"@context": "https://www.w3.org/ns/activitystreams"

An inline object with term definitions:

"@context": {
  "@vocab": "https://www.w3.org/ns/activitystreams#",
  "toot": "http://joinmastodon.org/ns#"
}

An array mixing URLs and objects:

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

When @context is optional

From a strict JSON-LD perspective, @context is required for any JSON-LD processing — without it, expansion cannot occur.

However, ActivityStreams 2.0 was deliberately designed so that it "conforms to a subset of JSON-LD syntax constraints but does not require JSON-LD processing." Implementations that treat messages as plain JSON can ignore @context and access properties by their short names.

In practice: the @context MUST be present in outgoing documents (other implementations may need it), but your own code may not need to process it if you only handle standard ActivityPub vocabulary.


3. The Many Forms a Value Can Take

This is the most practically important aspect of JSON-LD for Fediverse implementers. Due to JSON-LD's data model, a single property value can appear in many different forms — all semantically equivalent.

Literal values

A plain string:

"content": "Hello, world!"

A value object (explicit):

"content": {"@value": "Hello, world!"}

A language-tagged value:

"content": {"@value": "Hello, world!", "@language": "en"}

A typed value:

"content": {"@value": "42", "@type": "http://www.w3.org/2001/XMLSchema#integer"}

IRI references

As a string:

"attributedTo": "https://example.com/users/alice"

As a node object:

"attributedTo": {"id": "https://example.com/users/alice"}

Or with the @ prefix:

"attributedTo": {"@id": "https://example.com/users/alice"}

Embedded objects

"attributedTo": {
  "type": "Person",
  "id": "https://example.com/users/alice",
  "name": "Alice"
}

Arrays

Any of the above can also appear inside an array:

"tag": [
  {"type": "Hashtag", "name": "#cats"},
  {"type": "Mention", "href": "https://example.com/users/bob"}
]

Or as a single-element array:

"inReplyTo": ["https://example.com/notes/1"]

Mixed arrays

An array can contain a mix of strings and objects:

"attributedTo": [
  "https://example.com/users/alice",
  {"@id": "https://example.com/users/bob"}
]

Why this happens

JSON-LD compaction collapses single-element arrays to scalars. JSON-LD expansion wraps all values in arrays and all strings in @value objects. Different implementations may send data in different stages of this pipeline, producing different surface representations of the same data.


4. Functional vs Non-Functional Properties

In the ActivityStreams vocabulary, some properties are marked as functional — they can only have a single value. Non-functional properties can have multiple values, meaning they may legally appear as arrays.

After JSON-LD compaction, a non-functional property with one value is collapsed to a scalar. But the array form is equally valid. This is the root cause of bugs like Mastodon's inReplyTo crash (#25588) — the code assumed inReplyTo would always be a string, but it arrived as an array.

Rule: Any property not explicitly marked functional in the ActivityStreams vocabulary can appear as either a single value or an array. Handle both.


5. Expansion and Compaction

These are the two key JSON-LD transformations. Understanding them explains why the same data looks different from different servers.

Expansion

Transforms a compacted document into a canonical, unambiguous form:

  1. All property names become full IRIs
  2. All values are wrapped in arrays
  3. String/number values become {"@value": ...} objects
  4. IRI references become {"@id": ...} objects
  5. @type values become full IRIs inside an array
  6. @id stays as a string (the only property that does NOT become an array)
  7. The @context is removed — its information has been applied

Compacted:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://example.com/notes/1",
  "type": "Note",
  "content": "Hello",
  "attributedTo": "https://example.com/users/alice"
}

Expanded:

[
  {
    "@id": "https://example.com/notes/1",
    "@type": ["https://www.w3.org/ns/activitystreams#Note"],
    "https://www.w3.org/ns/activitystreams#content": [
      {"@value": "Hello"}
    ],
    "https://www.w3.org/ns/activitystreams#attributedTo": [
      {"@id": "https://example.com/users/alice"}
    ]
  }
]

Compaction

The reverse of expansion — applies a @context to:

  • Shorten full IRIs back to short terms
  • Collapse single-element arrays to scalar values
  • Simplify {"@value": "Hello"} back to "Hello"

Recommended processing workflow

  1. Expand incoming documents to normalize them
  2. Process the expanded data — all values are in predictable arrays
  3. Compact before sending responses — make output human-readable

This approach dramatically simplifies parsing code because after expansion, every property has a consistent structure.


6. The Four Document Forms

JSON-LD documents can appear in four forms:

Compacted

Human-readable. Short property names from @context. Single-element arrays collapsed to scalars. This is what ActivityPub implementations typically produce and consume.

Expanded

Canonical. Full IRI property names. All values in arrays. No @context. Unambiguous but verbose. Used internally for processing.

Flattened

All nodes collected into a single array under @graph. Nested objects replaced with @id references. Blank nodes get generated identifiers. Useful when you need a flat list of all nodes in the document.

Framed

Data reshaped to match a developer-provided template ("frame"). Extracts specific structures from a graph. Rarely used in the Fediverse.


7. Language Maps — content vs contentMap

ActivityStreams defines paired properties for multilingual content:

PlainLanguage mapPurpose
contentcontentMapPost body (HTML)
namenameMapDisplay name / title
summarysummaryMapContent warning text

Plain form

"content": "Hello, world!"

Language map form

"contentMap": {
  "en": "Hello, world!",
  "es": "¡Hola, mundo!"
}

The merging problem

In the ActivityStreams context, content and contentMap map to the same IRI (https://www.w3.org/ns/activitystreams#content). The contentMap version has "@container": "@language". When a JSON-LD processor encounters both content and contentMap on the same object, it merges them because they resolve to the same IRI — which can produce unexpected results.

Mastodon's behavior

Mastodon sends both content and contentMap, but contentMap always contains only a single language entry duplicating content. This is redundant but harmless.

When consuming, prefer contentMap if available (it includes language information). Fall back to content if contentMap is absent.


8. How Fediverse Implementations Handle JSON-LD

The spectrum

ApproachImplementationsHow it works
Full JSON-LD processingGoToSocialParses JSON-LD properly; maps IRIs to struct fields
Partial JSON-LDMastodon, Pleroma/AkkomaUses JSON-LD library for LD Signatures / canonicalization; otherwise treats as plain JSON
Plain JSONMost othersIgnores @context; looks up properties by short name

Why most skip JSON-LD processing

  1. Complexity — full JSON-LD processing is hard to implement correctly. The expansion algorithm alone can take weeks.
  2. Remote context fetching — JSON-LD may reference remote context documents, introducing latency and security risks.
  3. Unnecessary for core vocabulary — standard ActivityPub property names are stable and well-known. JSON-LD processing adds overhead without practical benefit for the base vocabulary.
  4. Mastodon compatibility — most implementations just match Mastodon's output format rather than handling arbitrary JSON-LD.

What breaks when you skip JSON-LD

  1. Extensions — custom properties from other implementations' own @context entries may not be understood, or worse, may collide if two extensions use the same short name for different things.
  2. Value form variability — an implementation expecting a string will crash on an array (Mastodon inReplyTo bug #25588).
  3. Namespace differences — different implementations may use different short names for the same concept.

9. The @context in the Wild

Mastodon's @context

Mastodon sends a multi-entry context array:

"@context": [
  "https://www.w3.org/ns/activitystreams",
  "https://w3id.org/security/v1",
  {
    "toot": "http://joinmastodon.org/ns#",
    "Emoji": "toot:Emoji",
    "featured": "toot:featured",
    "featuredTags": "toot:featuredTags",
    "discoverable": "toot:discoverable",
    "manuallyApprovesFollowers": "as:manuallyApprovesFollowers",
    "schema": "http://schema.org#",
    "PropertyValue": "schema:PropertyValue",
    "value": "schema:value"
  }
]

Known @context bugs

Mastodon's schema mapping: Mastodon maps "schema" to "http://schema.org#" (note: HTTP, not HTTPS, and # instead of /). The correct URI for schema.org is "https://schema.org/". This means JSON-LD processors using the correct schema.org context will fail to process Mastodon profile fields (PropertyValue, value).

ActivityStreams cyclical alias: The ActivityStreams context defines "as": "https://www.w3.org/ns/activitystreams#", which creates a cyclical reference (the context is itself at that namespace URL). Strict JSON-LD processors may reject this.

Adding extensions via @context

To add custom properties, add entries to the inline @context object:

"@context": [
  "https://www.w3.org/ns/activitystreams",
  {
    "myExtension": "https://myserver.example/ns#",
    "customField": "myExtension:customField"
  }
]

Implementations that perform JSON-LD processing will resolve "customField" to the full IRI "https://myserver.example/ns#customField". Implementations that ignore @context will just look for "customField" by name.


10. Content Types

Three MIME types are associated with ActivityPub / JSON-LD:

MIME TypePurpose
application/ld+json; profile="https://www.w3.org/ns/activitystreams"Full JSON-LD with ActivityStreams profile (MUST accept per spec)
application/activity+jsonActivityStreams-specific (SHOULD accept per spec)
application/jsonGeneric JSON (JSON-LD is valid JSON)

When sending

Use Content-Type: application/activity+json for outgoing activities and responses.

When fetching

Include both ActivityPub types in the Accept header:

Accept: application/activity+json, application/ld+json; profile="https://www.w3.org/ns/activitystreams"

11. JSON-LD and LD Signatures

JSON-LD processing is required for Linked Data Signatures, even in implementations that otherwise ignore JSON-LD. The process:

  1. Convert the JSON-LD document to canonical form using the URDNA2015 (or similar) canonicalization algorithm
  2. Hash the canonical form with SHA-256
  3. Sign the hash with the actor's private key

This is used for activity forwarding (proving the original author) and by some relays for message verification.

Security: remote context loading

JSON-LD libraries may make HTTP requests to arbitrary domains when loading remote @context documents. Implementations must use a custom document loader that restricts context fetching to a known set of URLs. At minimum, allow:

  • https://www.w3.org/ns/activitystreams
  • https://w3id.org/security/v1
  • https://w3id.org/identity/v1

Block all other remote context loads to prevent SSRF and information leakage.

Signature type mismatch

Mastodon's LD Signature implementation uses RsaSignature2017. The specification finalized as RsaSignature2018. HTTP Message Signatures (RFC 9421) are gradually replacing LD Signatures for most use cases.


12. Defensive Parsing — What Correct Implementations Must Do

For any property value, handle all forms

value := parseProperty(obj, "attributedTo")

// value could be:
//   "https://example.com/users/alice"              (string)
//   {"@id": "https://example.com/users/alice"}     (node ref)
//   {"id": "https://example.com/users/alice", ...} (embedded object)
//   ["https://example.com/users/alice"]             (array)
//   [{"@id": "..."}, "https://..."]                 (mixed array)
//   null / missing                                  (absent)

Normalization strategy

  1. If the value is a string, treat as-is (plain value or IRI depending on the property definition)
  2. If the value is an object with @id or id, extract the IRI
  3. If the value is an object with @value, extract the literal value
  4. If the value is an array, apply the above rules to each element
  5. If the value is null or missing, treat as absent
  6. Never assume a property will always be a specific form

Properties that commonly vary in form

PropertyMay appear as
inReplyTostring, array, object, null
to / ccstring, array
tagobject, array of objects
attachmentobject, array of objects
attributedTostring, object, array
icon / imagestring, object, array
urlstring, object, array

13. Common Implementation Mistakes

  • Assuming id and @id are different properties: they are aliases in the ActivityStreams context — identical semantically. Accept both, produce id
  • Assuming a property is always a string: any non-functional property can arrive as an array. Any IRI-valued property can arrive as {"@id": "..."} instead of a plain string
  • Not including @context in outgoing documents: even if your implementation ignores it, others may need it. Always include at least "@context": "https://www.w3.org/ns/activitystreams"
  • Fetching remote contexts without restrictions: JSON-LD libraries will load arbitrary URLs unless constrained by a custom document loader — this is both a performance and security risk
  • Using @id and @type in outgoing documents: use the aliased forms (id, type) for compatibility with implementations that match on property name without JSON-LD processing
  • Ignoring contentMap: if present, it carries language information that content alone does not. Prefer contentMap when available
  • Not handling the @context array form: @context can be a string, object, or array — don't assume a specific shape if you need to inspect it
  • Hardcoding Mastodon's @context: other implementations send different contexts. If you must inspect @context, handle variation
  • Treating content and contentMap as independent: in JSON-LD they map to the same IRI and will merge during expansion — be aware of this if you perform JSON-LD processing

Fediverse Liking — Complete Reference

Overview

"Liking" a post is modelled by the ActivityPub Like activity, defined in the ActivityStreams 2.0 vocabulary and given server-side effects in the ActivityPub specification. It is a binary state — either an actor has liked an object or they haven't. There is no built-in rating scale.

Platforms surface likes under different names: Mastodon calls them favourites (shown with a star ★), other platforms use hearts ♥ or thumbs up 👍. The underlying ActivityPub type is always Like regardless of the UI label.


1. The Like Activity

Minimal structure

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://alice.example/likes/abc123",
  "type": "Like",
  "actor": "https://alice.example/users/alice",
  "object": "https://bob.example/users/bob/statuses/456",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://bob.example/users/bob"]
}

Key fields:

  • id — required; a stable, dereferenceable URL on the actor's server. Needed so the activity can later be referenced inside an Undo.
  • actor — the actor who is liking.
  • object — the object being liked (a URL is sufficient; the full object need not be embedded).
  • to/cc — addressing. Conventions vary; common practice is to address the Public collection and cc the author of the object.

The Like activity SHOULD have an id because it will need to be referenced as the object of a future Undo{Like}. Omitting it makes undoing the like ambiguous.


2. The Two Collections

likes — on the object

An object (Note, Article, Video, etc.) MAY expose a likes property linking to an OrderedCollection of Like activities received for that object:

{
  "id": "https://bob.example/users/bob/statuses/456",
  "type": "Note",
  "likes": "https://bob.example/users/bob/statuses/456/likes",
  ...
}

This collection is maintained by the author's server. It contains one Like activity per liking actor (unique by actor id). The count of items in this collection is what platforms display as the "like count."

The collection MAY be hidden (its items not publicly enumerated) while still exposing a totalItems count. This is common practice — servers often expose the count but not the list of who liked the post.

liked — on the actor

An actor MAY expose a liked property linking to an OrderedCollection of objects that actor has liked:

{
  "id": "https://alice.example/users/alice",
  "type": "Person",
  "liked": "https://alice.example/users/alice/liked",
  ...
}

This collection is maintained by the actor's server and contains the objects (by id), not the Like activities themselves. It is unique by object id — an actor cannot like the same object twice. It is often private or semi-private.


3. Client-to-Server Flow (C2S)

When a client (app) submits a Like to the actor's outbox:

  1. Server checks the object exists.
  2. Server checks the object is not already in the actor's liked collection.
  3. Server checks the actor has permission to view the object (is an addressee of the object or its Create activity).
  4. Server checks the actor is not blocked by the object's responsible actor.
  5. If all checks pass:
    • Add the object to the actor's liked collection.
    • If the object is local: add the Like activity to the object's likes collection directly.
    • If the object is remote: deliver the Like activity to the inbox of the actor responsible for the object (typically attributedTo or actor on the object).

4. Server-to-Server Flow (S2S)

When a remote server delivers a Like to your inbox:

  1. Check the object exists on the local server. If it doesn't (e.g. it's on a third server), the Like can be treated as having no side effects and quietly ignored.
  2. Check no Like from this actor already exists in the object's likes collection (deduplicate by actor id).
  3. Check the responsible actor for the object has not blocked the liking actor.
  4. Check the liking actor has permission to view the object.
  5. If all checks pass: add the Like activity to the object's likes collection and update the displayed count.

5. Undoing a Like — Undo{Like}

Unlinking a like is done with an Undo activity wrapping the original Like:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://alice.example/likes/abc123/undo",
  "type": "Undo",
  "actor": "https://alice.example/users/alice",
  "object": {
    "id": "https://alice.example/likes/abc123",
    "type": "Like",
    "actor": "https://alice.example/users/alice",
    "object": "https://bob.example/users/bob/statuses/456"
  }
}

The object of the Undo is the original Like activity, identified by its id. This is why the original Like must have had a stable id.

The object may be embedded (as above) or referenced by id alone — implementations should accept both.

Validation on receiving an Undo{Like}:

  • The Like activity must exist (in the likes collection).
  • The actor of the Undo must be the same as the actor of the Like.
  • The object of the Like must be local.

If valid: remove the Like from the object's likes collection and decrement the displayed count.


6. Delivery Target

The Like is delivered to the inbox of the actor responsible for the object, not to the liking actor's followers and not to the public. The "responsible actor" is typically the attributedTo field on the object.

This means:

  • Likes are not broadcast to followers (unlike boosts/announces).
  • Like counts on remote posts are only known by the post's origin server.
  • A server only knows about a Like on a remote post if it happened to receive the notification through some other path (e.g. a local user is the author, or the remote server proactively forwarded it).

7. The Dislike Type

ActivityStreams 2.0 defines a Dislike activity type. It is not used in standard ActivityPub. The W3C ActivityPub primer explicitly states this.

Exception: PeerTube supports both Like and Dislike for videos, federating them to update video likes and dislikes counts. PeerTube exposes both as named collections on the video object. This is a PeerTube extension and not interoperable with Mastodon-lineage software.

Do not implement or depend on Dislike unless you are specifically building PeerTube-compatible software.


8. Multiple Likes for the Same Object

The ActivityPub spec does not address what happens if an actor sends multiple Like activities for the same object. In practice:

  • Both liked (actor side) and likes (object side) are treated as unique by the relevant id (object id and actor id respectively).
  • Originating servers should avoid sending duplicate Like activities.
  • Receiving servers should silently ignore all but the first Like from the same actor for the same object.

9. Emoji Reactions

Emoji reactions are a popular extension to the basic Like model. They allow reacting with a specific emoji instead of (or in addition to) a plain like. There is no single standard — two incompatible approaches exist in the wild.

9.1 EmojiReact — Pleroma/Akkoma style (FEP-c0e0)

Pleroma introduced EmojiReact as a new activity type in the LitePub namespace. This has since been formalised in FEP-c0e0, which is the emerging community standard.

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    {
      "toot": "http://joinmastodon.org/ns#",
      "EmojiReact": "http://litepub.social/ns#EmojiReact"
    }
  ],
  "id": "https://alice.example/reactions/xyz",
  "type": "EmojiReact",
  "actor": "https://alice.example/users/alice",
  "object": "https://bob.example/users/bob/statuses/456",
  "content": "👍"
}

For a custom emoji (not a Unicode emoji), the tag property is added:

{
  "type": "EmojiReact",
  "actor": "https://alice.example/users/alice",
  "object": "https://bob.example/...",
  "content": ":blobcat:",
  "tag": [{
    "type": "Emoji",
    "name": ":blobcat:",
    "icon": {
      "type": "Image",
      "url": "https://alice.example/emoji/blobcat.png"
    }
  }]
}

Akkoma/Pleroma behaviour:

  • A user MAY react multiple times with different emoji to the same post.
  • A user MAY NOT react more than once with the same emoji.
  • EmojiReact is distinct from Like — a user can both Like and EmojiReact to the same post; they are separate.
  • Duplicate reactions (same actor, same emoji) MUST be silently ignored.
  • Unicode emoji: tag MAY be omitted.
  • Custom emoji: content contains the shortcode with colons (:blobcat:); tag contains the Emoji object with the image URL.

Undo: wrapped in Undo{EmojiReact} the same way as Undo{Like}.

9.2 Misskey-style reactions (overloaded Like)

Misskey (and its forks: Calckey, Firefish, Catodon) does NOT use a separate activity type. Instead it sends a standard Like activity with an additional non-standard _misskey_reaction property carrying the emoji string:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Like",
  "actor": "https://misskey.example/users/alice",
  "object": "https://bob.example/users/bob/statuses/456",
  "_misskey_reaction": "👍"
}

Misskey behaviour:

  • Likes and reactions are equated — reacting replaces any previous reaction.
  • Only one reaction per post per user is allowed (unlike Pleroma which allows multiple different emoji).
  • Custom emoji: _misskey_reaction contains the shortcode (:blobcat:@. for local or :blobcat:@misskey.example for remote); the emoji image is resolved separately.

9.3 Interoperability between the two approaches

Pleroma/Akkoma (EmojiReact)Misskey-lineage (Like + _misskey_reaction)
Activity typeEmojiReact (new type)Like (standard type, extended)
Multiple reactions per postYes (different emoji)No (one per user)
Distinct from plain LikeYesNo
Custom emoji in tagYesShortcode in _misskey_reaction
StandardFEP-c0e0 (draft)Proprietary

Servers that don't understand EmojiReact will ignore it (unrecognised activity types should be treated as unknown and discarded). Servers that don't understand _misskey_reaction will process it as a plain Like — which means Misskey reactions do federate as likes to Mastodon and similar platforms, they just lose the emoji identity.

Mastodon currently does not implement either emoji reaction system on the sending side. It displays incoming Misskey reactions as plain likes. A PR for Pleroma-style reactions was opened (#13275) but has not been merged.

FEP-c0e0 is the recommended approach for new implementations that want to add emoji reactions, as it uses a distinct activity type, allowing servers that don't support reactions to simply ignore them without inflating like counts.


10. Stale Like Counts on Remote Posts

A persistent and well-known limitation: like counts displayed on remote posts are frequently stale or incomplete. This happens because:

  1. Likes are delivered only to the post's author's server. They are not broadcast to every server that has seen the post.
  2. A server that learns about a remote post (e.g. because a local user boosted it) receives the post object at that moment in time, including its totalItems count in the likes collection — but that count is a snapshot, not a live feed.
  3. The receiving server typically does not subscribe to updates of the remote likes collection. Counts only update if the server re-fetches the object.
  4. Some implementations never re-fetch remote objects at all after initial discovery.

This is not a bug in the protocol — it is a consequence of decentralisation combined with the delivery model. Wikipedia's ActivityPub article notes this explicitly as a known criticism.

Implications for implementors:

  • Do not claim that like counts shown for remote posts are authoritative.
  • If freshness matters, re-fetch the remote object before displaying its count.
  • Do not use a remote likes collection count as a trust or ranking signal.

11. The liked Collection and Privacy

The liked collection on an actor is often kept private or unexposed. The ActivityPub spec does not require it to be publicly readable. Implementations vary:

  • Mastodon: exposes a liked URL on the actor but requires authentication to read; effectively private.
  • Many others: expose the collection URL but return an empty collection or a 403/404 without auth.

Do not rely on being able to read another server's liked collection to reconstruct what a user has liked. The only reliable signal is receiving a Like activity in your inbox.


12. Summary of Activity Types

ActivitySent toEffect
LikeAuthor's inboxAdds to object's likes collection; notification to author
Undo{Like}Author's inboxRemoves from likes collection
EmojiReact (FEP-c0e0)Author's inboxAdds emoji reaction; ignored by non-supporting servers
Undo{EmojiReact}Author's inboxRemoves emoji reaction
Like + _misskey_reactionAuthor's inboxMisskey reaction; treated as plain Like by others
DislikeAuthor's inboxPeerTube only; not used elsewhere

Fediverse Long-form Text (FEP-b2b8) — Complete Reference

Overview

Long-form text — blog posts, magazine articles, forum posts — is represented in ActivityPub using the Article type, defined in the Activity Streams 2.0 vocabulary. FEP-b2b8 (authored by Evan Prodromou, received 2024-11-07, status DRAFT) collects and extends guidance for publishers and consumers of multi-paragraph text objects.

The core problem FEP-b2b8 addresses: the fediverse grew around microblogging where Note dominates. Mastodon and similar clients either display Article objects as just a title + link or strip their HTML, providing a degraded experience. Many publishers worked around this by sending Note instead, causing overly-long posts in microblog feeds. FEP-b2b8 defines how to structure Article objects properly and introduces the preview property as a fallback for microblogging clients.


1. Article vs. Note — When to Use Which

The Activity Vocabulary defines:

  • Note — a short written work, typically less than a single paragraph
  • Article — any kind of multi-paragraph written work

Publishers SHOULD use Article for multi-paragraph content. The common workaround of stuffing long content into a Note causes problems for consumers that expect Notes to be short. FEP-b2b8 explicitly discourages it:

Publishers should avoid this workaround, and instead give consumers the full information they need to display the content correctly in their own interfaces.

The IndieWeb community uses a pragmatic heuristic: articles have titles (a name property), notes don't. The post-type-discovery algorithm checks whether name exists and is not simply a prefix of content.


2. The Article Object — Properties

id

A unique HTTPS URL that resolves to the object. Equivalent to RSS 2.0 guid.

name

The title. Should be plain text (no HTML entities like &amp;), 75–150 characters. Equivalent to RSS 2.0 title.

"name": "Long-form text with included content"

url

Location of the full HTML representation. Can be:

  • A single string URL
  • A Link object with mediaType: "text/html" and href
  • An array of strings/Link objects for multiple representations

At least one entry should have mediaType of text/html and protocol https. Equivalent to RSS 2.0 link.

"url": "https://example.com/2024/11/07/long-form-text.html"

Or as a Link:

"url": {
  "type": "Link",
  "mediaType": "text/html",
  "href": "https://example.com/2024/11/07/long-form-text.html"
}

summary

A brief description, teaser, abstract, or "lede." Guidelines:

  • Maximum about 500 characters
  • A few sentences or a short paragraph
  • Can include HTML markup
  • MUST NOT include embedded media (images, video, audio)
  • MUST NOT include navigation elements or affordances (favourite, like, bookmark buttons)
  • MUST NOT include "Read more..." links

Equivalent to RSS 2.0 description.

Summary generation hierarchy (recommended by Evan Prodromou):

  1. Manual user-defined summary (preferred)
  2. Use full text if it is ~500 chars and a single paragraph
  3. Use first paragraph if it meets the rough guidelines
  4. Truncate with ellipsis (…) as fallback

Implementation note (NodeBB): NodeBB allows a "magic string" (HTML comment) that power users can place in their content to manually select where the summary should end. The limit and marker are configurable per instance. After consulting with Matt Baer (WriteFreely), this approach was adopted alongside ellipsis on truncation.

Interop quirk (GoToSocial): GoToSocial treats summary as a content warning, not as a teaser/abstract. This means Articles with a summary may display with a content warning gate on GoToSocial, which is not the publisher's intent.

attributedTo

The author(s). Can be:

A string (just the actor id):

"attributedTo": "https://example.com/evan"

An object with full author info:

"attributedTo": {
  "type": "Person",
  "id": "https://example.com/evan",
  "name": "Evan Prodromou",
  "summary": "<p>Founder of Social Web Foundation</p>",
  "url": "https://example.com/evan",
  "icon": {
    "type": "Image",
    "mediaType": "image/png",
    "url": "https://example.com/evan.png"
  }
}

A Link (for authors without an AS2 representation):

"attributedTo": {
  "type": "Link",
  "href": "https://example.com/evan",
  "name": "Evan Prodromou"
}

An array for multiple authors (strings, objects, or Links mixed).

published

Publication date as YYYY-MM-DDTHH:MM:SSZ. Equivalent to RSS 2.0 pubDate.

updated

Date of last update, same format. If absent, consumers can assume the object has not been modified since published.

image

A notable or representative image. Can be an id string or Image object. Multiple values are allowed (array), ordered by importance (most important first). Consumers use as many or as few as needed.

content

The full text of the article in HTML. The HTML MUST be a sanitized subset — no CSS, no JavaScript. Allowed elements:

ElementAllowed Attributes
<p>—
<span>class
<h2> through <h6>—
<br>—
<a>href, rel, class
<del>—
<pre>—
<code>—
<em>—
<strong>—
<b>—
<i>—
<u>—
<ul>—
<ol>start, reversed
<li>value
<blockquote>—
<img>src, alt, title, width, height, class
<video>src, controls, loop, poster, width, height, class
<audio>src, controls, loop, class
<source>src, type
<ruby>—
<rt>—
<rp>—

Notable omissions: <h1> (the title goes in name), <table>, <div>, <figure>, <figcaption>, <details>, <summary>.

The content MUST NOT include navigation links (home page, category pages), affordance buttons (favourite, like, bookmark), or "Read more" links. Any embedded media (<img>, <video>, <audio>) in content SHOULD also be listed in attachment for pre-fetching.

source

If the text was originally created in a different format (e.g., Markdown), the original source for editing:

"source": {
  "mediaType": "text/markdown",
  "content": "# My Article\n\nFirst paragraph..."
}

replies

A URL resolving to a collection of reply objects. Replies are usually Note objects but can be Article or Question. Equivalent to RSS 2.0 comments.

inReplyTo

If the article is a reply to another ActivityPub object, a string URL or JSON object. If it is commentary on a web resource (not an AP object), a Link object with href pointing to that resource.

attachment

Additional media for pre-fetching without parsing content:

"attachment": [
  {
    "type": "Image",
    "id": "https://example.com/image1.jpg",
    "mediaType": "image/jpeg"
  }
]

tag

Two important tag types:

  • Hashtag: { "type": "Hashtag", "name": "example", "href": "https://..." }
  • Mention: { "type": "Mention", "href": "https://..." }

context

Link to a larger collection — an article series, newspaper column, blog category, magazine section. Can be an array. (For topic tagging, tag with Hashtag may be more appropriate.)

generator

Information about the publishing software. Usually an Application or Service object with id and name.

to, cc, bcc, bto, audience

Addressing properties. Determine delivery targets in ActivityPub and provide access control. Publishers and consumers MUST NOT disclose Article properties to anyone except addressees and creator(s).

sensitive

Marks content as potentially sensitive (nudity, violence, spoilers, etc.). When set, consumers should obscure the article until the user opts in.

To help users decide whether to read, display these properties (in order):

  1. dcterms:subject — Dublin Core subject string(s). Most informative and least likely to leak sensitive content.
  2. tag — Hashtag names. Less human-readable than subject.
  3. name — Title. Authors may leak sensitive material here.
  4. summary — Last resort. A well-written summary likely includes significant excerpts of the sensitive content.

Using dcterms:subject requires extending the context:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://purl.archive.org/miscellany",
    {"dcterms": "http://purl.org/dc/terms/"}
  ],
  "type": "Article",
  "sensitive": true,
  "dcterms:subject": ["Citizen Kane"]
}

3. The preview Property — Microblogging Fallback

The preview property is a key innovation in FEP-b2b8 for bridging the Article/microblogging gap. It provides a Note that gives a well-formatted preview of the article:

{
  "type": "Article",
  "id": "https://example.com/article.jsonld",
  "name": "Long-form text with preview",
  "url": "https://example.com/article.html",
  "attributedTo": "https://example.com/evan",
  "summary": "<p>This is the summary.</p>",
  "content": "<p>Full article content here...</p>",
  "published": "2024-11-07T12:00:00Z",
  "image": {
    "type": "Link",
    "href": "https://example.com/image.jpg",
    "mediaType": "image/jpeg"
  },
  "preview": {
    "type": "Note",
    "attributedTo": "https://example.com/evan",
    "content": "<p><strong>Long-form text with preview</strong></p><p>This is the summary.</p>",
    "published": "2024-11-07T12:00:00Z",
    "attachment": {
      "type": "Link",
      "href": "https://example.com/image.jpg",
      "mediaType": "image/jpeg"
    }
  }
}

Rules for preview:

  • Type SHOULD be Note
  • Content should combine the name (as bold text) and summary
  • MUST NOT include a link to the HTML representation
  • MUST NOT include navigation or affordance elements
  • Metadata from the Article (attributedTo, published, updated, tag) can be repeated; consumers fall back to the Article's properties if absent
  • The Article's image may be included as attachment in the preview
  • The preview MAY have its own id
  • The consumer (not the preview) is responsible for displaying a link to the full article content

Community debate: trwnh raised concerns that preview "muddies the waters" by treating separate objects as unified. The mechanism remains in the FEP but its long-term acceptance is not certain.


4. Complete Example — Minimal Article

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Article",
  "id": "https://example.com/2024/11/07/my-post.jsonld",
  "name": "My Blog Post Title",
  "url": "https://example.com/2024/11/07/my-post.html",
  "attributedTo": "https://example.com/users/alice",
  "summary": "<p>A brief teaser about the post content.</p>",
  "content": "<p>First paragraph of the full article.</p><p>Second paragraph with more detail.</p>",
  "published": "2024-11-07T12:00:00Z"
}

5. Complete Example — Article with External Content Only

An Article can omit content and link to external HTML instead:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Article",
  "id": "https://example.com/2024/11/07/external.jsonld",
  "name": "My External Article",
  "url": "https://example.com/2024/11/07/external.html",
  "attributedTo": "https://example.com/users/alice",
  "summary": "<p>A brief description of the article available at the URL.</p>",
  "published": "2024-11-07T12:00:00Z"
}

6. RSS 2.0 Property Mapping

FEP-b2b8 explicitly draws parallels to RSS 2.0 for publishers familiar with syndication:

Article PropertyRSS 2.0 Equivalent
idguid
nametitle
urllink
summarydescription
attributedToauthor
publishedpubDate
repliescomments

7. How Consumers Should Display Articles

FEP-b2b8 includes UI guidance for stream-oriented interfaces:

Standard display (with image)

Show: author avatar + name, name as headline, image as hero/thumbnail, summary as teaser text, published date, link to url for full reading.

Without image

Same as above, minus the image. The summary gets more visual prominence.

Without title

If name is absent, show the summary or beginning of content directly, similar to how a Note would appear but with a link to the full content.

Sensitive content

If sensitive is true, obscure the article behind a content warning. Show dcterms:subject or tag names or name to help the user decide whether to proceed.

With preview

If the consumer does not natively support Article, display the preview Note instead. The consumer is responsible for adding a link to the full article.

Fallback for consumers that only display short text

Show name, summary, and a link to url so users can read the full content in a browser.


8. Interoperability Matrix

Publishing platforms (send Article type)

PlatformSends ArticleUses summaryUses previewNotes
WordPress (AP plugin)YesYes—Historically sent Note as workaround; now sends Article
GhostYesYes—Active SWF participant; Ghost 6 has full AP integration
WriteFreely / Write.asYesYes—PR for FEP-b2b8 support discussed May 2025
PlumeYesYes—Early Article adopter
NodeBBYesYes—Switches between Note/Article by length; magic string for summary breaks
BonfireYesYes—Adopted FEP-b2b8 as technical foundation

Consuming platforms (display Article type)

PlatformArticle displayNotes
MastodonTitle + link onlyFirst-class types are Note and Question only; Article gets degraded display
ThreadsFull displayAnnounced support for long-form Ghost content (2025)
Pleroma/AkkomaInline displaySupports rich text in both Note and Article
GoToSocialInline displayTreats summary as content warning (not teaser)
BonfireFull displayDedicated "Articles" feed, in-app reading

9. The Note vs. Article History

Understanding why FEP-b2b8 exists requires knowing the history:

2017: Mastodon treated Note and Article identically, stripping most HTML from both. When this was raised, Mastodon changed Article to display only as a title + link. This created a fundamental disincentive to use Article.

2019–2023 (SocialHub discussions): Years of debate over what distinguishes Note from Article. Proposals included:

  • Length-based (short vs. multi-paragraph)
  • Formality-based (informal message vs. publication)
  • Title-based (articles have name, notes don't — IndieWeb approach)
  • Formatting-based (notes have minimal markup, articles have rich layout)

No spec-level resolution was reached.

2024: The Social Web Foundation identified long-form text as a priority. Evan Prodromou convened implementer workshops with WordPress, WriteFreely, Ghost, and others. FEP-b2b8 was submitted November 7, 2024.

2025: Threads announced Article support. Bonfire adopted FEP-b2b8. WriteFreely worked on implementation. Community debates continued around the preview mechanism and whether types should be semantic or length-based.


10. Known Issues and Pitfalls

  • Mastodon's degraded display is the #1 practical problem. Articles appear as just a title and link in Mastodon's UI, losing boosts, replies, and in-app engagement. This is why many publishers historically sent Note.
  • GoToSocial summary-as-CW: GoToSocial interprets summary as a content warning, not a teaser. Articles with summaries will display behind a CW gate, which is not what the publisher intended.
  • NodeBB engagement drop: When NodeBB switched from Note to Article for longer posts, engagement dropped because the truncated summary was less compelling than the full Note.
  • No <h1> in content: The allowed HTML subset starts at <h2>. The article title belongs in name, not in the HTML content.
  • No <table> in content: Tables are not in the allowed element set. Content with tabular data must use alternative markup or be simplified.
  • preview debate: trwnh and others question whether preview is the right mechanism, arguing it creates ambiguity about which object properties are authoritative.
  • summary length is guidance, not a hard limit: "about 500 characters" is a recommendation. NodeBB made it configurable per instance. Some implementations may use longer summaries.

11. Scope Limitations

FEP-b2b8 explicitly does NOT cover:

  • Book-length or longer text
  • Specific media types beyond text with embedded media
  • Client-to-server (C2S) article creation workflows
  • Full-text search or discovery mechanisms

Fediverse Extension Discovery via NodeInfo — Complete Reference

Overview

One of the unsolved problems in the Fediverse is capability discovery: how does a server know what extensions, custom types, or features a remote server supports? If Manyfold sends a 3D model activity to Mastodon, Mastodon discards it silently. If Lemmy receives a Like from Mastodon, it creates unnecessary traffic because Lemmy uses voting, not Like.

Several Fediverse Enhancement Proposals have attempted to solve this by extending NodeInfo — the existing server metadata protocol — with extension and capability declarations. The most notable was FEP-6481 (authored by James Smith / "Floppy," received 2024-03-12, WITHDRAWN 2024-10-31), which proposed a simple IRI list in NodeInfo metadata. It was withdrawn in favor of FEP-9fde, which takes a broader approach.

This is an active area of development with no FINAL-status solution.

NodeInfo: The Foundation

NodeInfo is a protocol for servers to publish metadata about themselves. It originated in the Diaspora project (predating ActivityPub) and is formalized in the Fediverse by FEP-f1d5 (status FINAL, revised as FEP-0151 in 2025).

Discovery

Servers expose /.well-known/nodeinfo containing a JRD document:

{
  "links": [
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.1",
      "href": "https://example.social/nodeinfo/2.1"
    }
  ]
}

Schema Versions

  • 1.0 / 1.1 — initial versions
  • 2.0 — significant revision
  • 2.1 — current most widely deployed version

Key Properties

PropertyDescription
softwareName, version, homepage, repository
protocolsSupported protocols (e.g., ["activitypub"])
servicesInbound and outbound service integrations
openRegistrationsWhether new accounts can be created
usageUser counts, local post count
metadataFree-form key-value pairs — the extension point

The metadata field is deliberately unstructured. The spec says: "Clients should not rely on any specific key present." This is where extension discovery proposals place their data.

FEP-6481: Extension IRI List (WITHDRAWN)

FEP-6481 proposed the simplest approach: an array of IRIs in NodeInfo metadata declaring which ActivityPub extensions a server supports.

Wire Format

{
  "version": "2.1",
  "protocols": ["activitypub"],
  "metadata": {
    "activitypub": {
      "extensions": [
        "https://w3id.org/manyfold/3dModel#v1",
        "https://joinbookwyrm.org/ns/activitypub#Review"
      ]
    }
  }
}

Requirements

  • Extension identifiers MUST be valid IRIs
  • IRIs SHOULD include version information via fragment identifiers (#v1)
  • Once defined, IRIs cannot change while maintaining compatibility
  • Long-term persistent URI services (like w3id.org) are recommended

Why It Was Created

James Smith ("Floppy") created Manyfold, a federated 3D model manager that extends ActivityPub with the f3di namespace (http://purl.org/f3di/ns#). When Manyfold sends activities with custom 3D model types, servers like Mastodon silently discard them. There was no way to discover in advance whether a remote server would understand the custom types.

Why It Was Withdrawn

Floppy withdrew FEP-6481 on 2024-10-31 in favor of FEP-9fde (by nikclayton), which covers the same use case with broader scope. FEP-9fde can express everything FEP-6481 proposed while also addressing client APIs, federation features, and arbitrary server operations.

Community Objections

nightpool's strong objection: "I strongly, strongly object to this FEP." The argument:

  • ActivityStreams 2.0 is designed to be extensible via JSON-LD — add extra properties to standard types (Note, Article, etc.) and servers that don't understand them simply ignore the extra fields
  • Custom types (BookWyrm's Review, Manyfold's 3D model types) break graceful degradation because standard servers discard unrecognized types entirely
  • Capability-based routing (sending different formats to different servers) fragments the ecosystem, increases complexity, and multiplies the testing surface

stevebate's concerns: the definition of "extension" was too vague; fragment-based URI versioning (#v1) doesn't work with HTTP (fragments aren't sent to servers); dereferenceable URIs should use path or query parameter versioning instead.

nutomic's reinterpretation: saw it as a traffic filtering mechanism — Lemmy could use it to tell servers "don't send me Like activities, I use voting."

FEP-9fde: Operations Map (Successor)

FEP-9fde (by nikclayton, DRAFT) extends NodeInfo with a standardized operations property using reverse-FQDN identifiers and semantic versioning.

Wire Format

{
  "operations": {
    "org.joinmastodon.api.statuses.post": ["1.0.0", "1.1.0", "2.0.0"],
    "app.manyfold.activitypub.accept.3dmodel": ["1.0.0"],
    "io.github.glitch-soc.api.statuses.bookmark": ["1.0.0"]
  }
}

Key Differences from FEP-6481

AspectFEP-6481FEP-9fde
ScopeActivityPub extensions onlyAny server operation
IdentifiersIRIs with fragment versioningReverse-FQDN strings
VersioningFragment identifiers (#v1)Semver arrays (["1.0.0"])
Locationmetadata.activitypub.extensionsoperations property
GranularityPer-extensionPer-operation
StatusWITHDRAWNDRAFT

Design Rationale

FEP-9fde explicitly rejects several alternatives:

  • OpenAPI definitions — too complex for clients
  • Hardcoded version mappings — maintenance burden and version-locking
  • Capabilities flags — combinatorial explosion as features interact
  • IRI identifiers — case-sensitivity issues; reverse-FQDN avoids this

The Broader Capability Discovery Landscape

Multiple proposals address the same fundamental problem:

FEP-eb22: Supported ActivityStreams Types

Lists which Activity and Object types a server handles:

{
  "activities": ["Create", "Update", "Delete", "Like", "Announce"],
  "objects": ["Note", "Article"],
  "properties": {}
}

Focuses on describing the standard ActivityStreams vocabulary a server supports, rather than arbitrary extensions or operations.

FEP-844e: Capability Discovery via Actors

Instead of using NodeInfo, attaches capability information to the ActivityPub application actor itself. Based on FEP-aaa3 (listing implemented specifications on the application actor). This keeps capability data within the ActivityPub protocol rather than relying on the external NodeInfo protocol.

FEP-67ff: FEDERATION.md

A human-readable approach: servers include a FEDERATION.md file documenting their federation behavior. Status FINAL. This solves the documentation problem but not machine-readable discovery.

Comparison

FEPApproachMachine-readable?Status
FEP-6481IRI list in NodeInfo metadataYesWITHDRAWN
FEP-9fdeReverse-FQDN operations in NodeInfoYesDRAFT
FEP-eb22Type lists in NodeInfoYesDRAFT
FEP-844eCapability URIs on AP actorsYesDRAFT
FEP-67ffFEDERATION.md documentationNo (human only)FINAL

The Custom Types Debate

A fundamental philosophical question underlies all extension discovery proposals: should implementations create custom ActivityStreams types at all?

The Case Against Custom Types (nightpool)

ActivityStreams 2.0 supports graceful degradation through JSON-LD:

  • Add custom properties to standard types (Note, Article, etc.)
  • Servers that understand the extensions use the extra data
  • Servers that don't understand simply ignore unknown properties
  • No capability discovery needed — everything is a standard type

Example: instead of a custom Review type, a BookWyrm review could be a Note with additional rating and reviewSubject properties. Mastodon would display it as a regular Note; BookWyrm would display it as a rich review.

The Case For Custom Types (Manyfold, BookWyrm)

Some extensions are fundamentally different from standard content:

  • A 3D model is not meaningfully a "Note" — displaying it as plain text loses all value
  • Domain-specific actions (accepting a 3D model upload) have no standard ActivityPub equivalent
  • The receiving server needs to know it's getting specialized content to provide any useful experience

The Practical Compromise

Manyfold's approach combines both:

  1. Send standard activities with custom types to servers that declare support
  2. Post "Compatibility Notes" (standard Note objects with f3di:compatibilityNote: true) describing the activity in text for servers that don't understand the custom types

This ensures content appears in all feeds while providing rich experiences where supported.

XMPP Precedent

The capability discovery problem is not new. XMPP solved it over two decades ago with:

  • XEP-0115 (Entity Capabilities): servers and clients advertise supported features using a hash of their capability set. Efficient discovery without enumerating every feature on every connection.
  • XEP-0453 (DOAP): uses structured project descriptions (Description of a Project) to communicate capabilities.

These mature solutions demonstrate that capability discovery is solvable but requires community consensus — something the Fediverse has not yet achieved.

Implementation Guidance

If You Need Extension Discovery Today

  1. Use FEDERATION.md (FEP-67ff, FINAL) to document your extensions in human-readable form
  2. Add NodeInfo metadata for machine-readable discovery — use the FEP-9fde operations format if your framework supports it, or add custom metadata keys as a stopgap
  3. Always provide fallback content — post standard Note/Article types alongside or instead of custom types for maximum compatibility
  4. Don't rely on capability routing for critical functionality — the receiving server may not implement discovery

If You Are Extending ActivityPub

Consider nightpool's argument carefully:

  1. Prefer extending standard types with additional properties over creating entirely new types
  2. If you must create custom types, also send compatibility objects (standard types with a text description) for servers that don't understand your extensions
  3. Define a JSON-LD context for your extensions so they are properly namespaced
  4. Register your extensions with a persistent IRI (w3id.org recommended)

Checking Remote Server Capabilities

GET /.well-known/nodeinfo → follow link → check metadata/operations

But remember: most servers don't declare extension support yet. Absence of a declaration does not necessarily mean absence of support.

Known Issues and Open Questions

  1. No FINAL solution — all machine-readable capability discovery proposals remain DRAFT or WITHDRAWN
  2. NodeInfo vs actor-based — unresolved debate about whether capability data belongs in NodeInfo (server-level, protocol-agnostic) or on ActivityPub actors (protocol-native)
  3. Granularity tension — FEP-9fde's per-operation approach can be verbose (Claire noted bookmarks alone require four operations); FEP-6481's per-extension approach may be too coarse
  4. Custom types vs extended standard types — the community hasn't reached consensus on the right extensibility pattern
  5. Mastodon's alternative — Mastodon introduced api_versions as a lighter-weight capability signal, potentially diverging from FEP-based approaches
  6. No implementations at scale — FEP-9fde and FEP-eb22 lack widespread adoption; only Manyfold actively uses NodeInfo for extension declaration

Fediverse OpenWebAuth (FEP-61cf) — Complete Reference

Overview

OpenWebAuth (OWA) is a federated remote authentication protocol that enables browser-based single sign-on across Fediverse services. A user logged in at their home instance can be automatically recognized by other compatible servers without creating local accounts, without third-party cookies, and often without any explicit user interaction.

FEP-61cf (authored by FenTiger, received 2024-02-06, status DRAFT) formally documents the protocol, which was written based on reverse-engineering existing implementations in Hubzilla and (streams).

OpenWebAuth is also known as Magic Auth, Magic Sign On, Remote Authentication, or rMagic. The name "Magic Auth" persists informally because "of how seamless the experience is."

The Problem: No Identity Across Servers

In the current Fediverse, when you browse to a different server, that server has no idea who you are. This causes several painful problems:

  1. Private content is inaccessible — if someone on podunk.edu shares a private video only with bob@example.com, Bob cannot view it by visiting podunk.edu. The server doesn't know he's Bob.

  2. Remote profiles are limited — when jumping from instance to instance, users lose their identity. They can't interact natively with content.

  3. No cross-server permissions — fine-grained access controls (e.g., "only Alice and Bob can see this photo") only work when the server can identify the viewer.

  4. No wall-to-wall posting — users can't post directly on someone else's wall or profile on a remote server.

OpenWebAuth solves this: "You can jump from one part of the Fediverse to another, and your permissions will be granted automatically. Anything you were given permission to access unlocks and becomes visible on the page."

Authentication vs Authorization

OpenWebAuth is strictly an authentication protocol — it proves who you are. It is NOT an authorization protocol.

"OpenWebAuth allows someone@example.social to log into example.com as someone@example.social, and example.com determines what someone@example.social can do on example.com. But example.com cannot impersonate someone@example.social."

The target instance decides locally what an authenticated remote user can do. OpenWebAuth provides the identity; the target provides the permissions.

This is the fundamental distinction from OAuth 2.0, which is an authorization framework — it grants permissions for a client to act on behalf of a user.

Architecture

The protocol has two participants:

  • Home instance — hosts the user's identity. Equivalent to the Identity Provider (IdP) in SAML and OpenID Connect. Only the home instance has access to the user's private key.
  • Target instance — allows remote users to log in. Equivalent to the Relying Party (RP) in SAML and OpenID Connect. Only uses public keys.

Each user is identified by a public/private key pair. The protocol relies on ActivityPub actor documents for public key discovery.

Login Flow Initiation

Two mechanisms trigger the authentication:

  1. Login form — user visits the target instance and submits their Fediverse ID (e.g., alice@example.social) via a login form
  2. zid= parameter — user follows a link containing ?zid=alice@example.social, which auto-triggers authentication

The zid= mechanism can be used in links embedded in content, enabling seamless authentication when clicking through from a home timeline to remote content.

Security note: the zid= parameter can facilitate attacks if adversaries craft malicious links with manipulated identity values.

The 5-Step Protocol Handshake

Step 1: Target Redirects to Home Instance

The target instance discovers the home instance's redirect endpoint via WebFinger:

GET /.well-known/webfinger?resource=acct:alice@home.example

Look for a link with rel="http://purl.org/openwebauth/v1#redirect". If not found, fall back to the hardcoded /magic endpoint on the home instance.

Construct the redirect URL:

https://home.example/magic?owa=1&bdest=<hex-encoded-destination-URL>

The bdest parameter contains the target URL (where the user wants to end up) converted from UTF-8 to hexadecimal encoding.

Origin validation: the target MUST validate that the redirect hostname matches the claimed identity's domain to prevent open redirector abuse.

Step 2: Home Instance Requests a Token

The home instance's /magic endpoint:

  1. Verifies the user has a valid session cookie (i.e., is logged in)
  2. Decodes the bdest URL from hex
  3. Performs a WebFinger lookup for the target's token endpoint, seeking rel="http://purl.org/openwebauth/v1"
  4. Sends an HTTP-Signature-signed request to the token endpoint
  5. Includes an X-Open-Web-Auth header with a random string for additional entropy
  6. If WebFinger discovery fails, returns an HTTP error (preventing open redirection — never redirects on failure)

The signed request uses an Authorization header starting with the word Signature followed by the encoded HTTP signature, per ActivityPub conventions.

Step 3: Target Instance Provides Encrypted Token

The target instance's token endpoint:

  1. Extracts the keyId from the signed request's Authorization header
  2. Fetches the actor record and public key via the keyId URL
  3. Verifies the HTTP signature
  4. Generates a URL-safe random token string
  5. Stores the token locally (with a short expiry, typically minutes)
  6. Encrypts the token using the actor's public key with RSA PKCS #1 v1.5
  7. Encodes the encrypted result as URL-safe Base64 without padding
  8. Returns JSON:
{
  "success": true,
  "encrypted_token": "<base64-encoded-encrypted-token>"
}

The token endpoint accepts both GET and POST requests. Some implementations send POST with random bodies.

Step 4: Home Instance Decrypts and Redirects

The home instance:

  1. Decodes the JSON response
  2. Verifies "success": true
  3. Decrypts the Base64-encoded token using the actor's private key
  4. Redirects the user's browser to:
<bdest>?owt=<decrypted-token>

Step 5: Target Instance Validates Token and Logs In

The target instance:

  1. Extracts the owt query parameter
  2. Matches it against the token stored in Step 3
  3. If valid, logs the user in as the remote identity
  4. Immediately deletes the token — single-use enforcement

After this step, the target instance sets a session cookie for the authenticated remote user. Subsequent page loads on the target don't require repeating the handshake.

WebFinger Link Relations

The protocol defines two custom WebFinger link relations:

RelationPurposePublished by
http://purl.org/openwebauth/v1#redirectRedirect endpoint (Step 1)Home instance
http://purl.org/openwebauth/v1Token endpoint (Step 2-3)Target instance

If the redirect endpoint is not discoverable via WebFinger, implementations fall back to the hardcoded /magic path on the home instance.

Key Usage Summary

OperationKey usedBy whom
Sign token request (Step 2)Private keyHome instance
Verify signature (Step 3)Public keyTarget instance
Encrypt token (Step 3)Public keyTarget instance
Decrypt token (Step 4)Private keyHome instance

Only the home instance ever touches the private key. The target instance operates exclusively with public keys.

Security Considerations

Information Leakage

The home instance learns which target instances the user visits (because it performs the redirect and token exchange on the user's behalf). Implementations should consider consent screens or privacy policies restricting automatic authentication.

Token Security

  • Tokens are single-use — deleted immediately after validation
  • Tokens expire within minutes — prevents storage exhaustion (DoS) from unused tokens
  • Tokens are encrypted with the actor's public key — only the home instance (with the private key) can decrypt them

Impersonation Prevention

The target instance MUST trust the owt= token over the original zid= parameter. The identity proven by the cryptographic handshake takes precedence over the unverified zid claim.

Additionally, the target validates that the token endpoint's origin matches the bdest origin, preventing attackers from redirecting users to malicious token endpoints.

Open Redirection Mitigations

Three layers of defense:

  1. First redirect (target → home): validates that the hostname matches the claimed identity
  2. Second redirect (home → target): validates that the token endpoint origin matches the bdest origin
  3. Failed discovery: returns HTTP errors rather than redirecting — never silently redirects on failure

The zid= Attack Surface

Links containing zid= parameters can be crafted by adversaries. When generalized beyond OpenWebAuth, this parameter could enable mix-up attacks. OpenWebAuth mitigates this through strict origin validation at each step.

History: From Magic Auth to OpenWebAuth

Magic Auth in Mistpark (2010)

Mike Macgirvin created Magic Auth as part of Mistpark in 2010 — the project that would later become Friendica. Magic Auth enabled federated single sign-on across decentralized nodes but was tightly coupled to the Zot protocol and "somewhat limited" in Friendica.

Integration into Hubzilla via Zot

As Mistpark evolved through Friendika → Friendica → Red Matrix → Hubzilla, Magic Auth remained embedded in the Zot protocol. In Hubzilla, it became central to features like fine-grained access control, private content sharing, and wall-to-wall posting — all of which depend on knowing who is visiting the server.

Standalone OpenWebAuth (October 2017)

Magic Auth was "separated from Zot and made into its own protocol called OpenWebAuth to facilitate adoption by other platforms." Released in Hubzilla 2.8. The key insight: authentication and communication are orthogonal problems. By extracting auth into a standalone spec, non-Zot projects could adopt it without the full Zot stack.

Zotlabs Era (2018-2022)

Mike Macgirvin launched Zotlabs to advance Zot6 and integrate OpenWebAuth. Multiple experimental projects (Osada, Zap, Roadhouse) eventually converged into the (streams) repository (October 2021).

Broader Adoption (2023+)

  • Friendica became the first non-Zot-family project to implement OpenWebAuth (~2023)
  • Forte (by benpate) implemented OWA as an alternative to Activity Intents for wall-to-wall posting
  • FedIAM implemented the protocol
  • FEP-61cf submitted February 2024, formally documenting the protocol

OpenWebAuth vs OAuth 2.0 / OIDC

AspectOpenWebAuth (FEP-61cf)OAuth 2.0 / OIDC (FEP-d8c2)
PurposeAuthentication (identity)Authorization (permissions)
ScopeBrowser-based SSO onlyMulti-platform (browser, mobile, API)
ComplexitySimple — WebFinger + HTTP Sig + tokenComplex — client registration, scopes, refresh tokens
Client registrationNone requiredRequired (RFC 7591)
Fediverse implementations5+ serversMastodon's partial OAuth (non-compliant RFC 7591)
Private key usageHome instance onlyClient + server
Target can act as user?No — authentication onlyYes — authorized actions via access tokens

The "not invented here" criticism (erlend_sh on SocialHub) argued existing OAuth/OIDC standards should be used instead. FenTiger's response: OWA and OAuth solve different problems; OWA is simpler, already deployed, and OIDC Discovery + Dynamic Client Registration have no existing Fediverse implementations.

Implementation Status

Identity Providers (Publishing OWA)

ImplementationStatusSince
HubzillaImplemented2017 (v2.8)
(streams)Implemented2021
ForteImplemented2024
FriendicaPartial~2023
FedIAMImplemented2024
MastodonProposed (issue #7643)—
PixelfedProof-of-concept—

Relying Parties (Accepting OWA)

ImplementationStatus
HubzillaImplemented
(streams)Implemented
ForteImplemented
FedIAMImplemented
Bridgy FedProposed
Great ApeProposed

The Mastodon Barrier

Mastodon issue #7643 (opened May 2018, still open) requests OpenWebAuth support. The fundamental barrier: implementing server-side OWA requires "the Mastodon service to have the concept of authorization of users without an account on the Mastodon server." This is an architectural change, not just a protocol implementation. A partial PR (#25012) was created for client-side functionality only.

Implementation Guidance

Publishing as an Identity Provider (Home Instance)

  1. Advertise your redirect endpoint via WebFinger with rel="http://purl.org/openwebauth/v1#redirect"
  2. Implement the redirect endpoint (traditionally /magic):
    • Check the user's session cookie
    • Decode the bdest parameter from hex
    • Discover the target's token endpoint via WebFinger
    • Send an HTTP-Signature-signed request with X-Open-Web-Auth header
    • Decrypt the returned token with the actor's private key
    • Redirect the browser to bdest?owt=<token>
  3. On failure at any step, return an HTTP error — never redirect

Accepting as a Relying Party (Target Instance)

  1. Advertise your token endpoint via WebFinger with rel="http://purl.org/openwebauth/v1"
  2. Implement the token endpoint:
    • Extract keyId from the Authorization: Signature ... header
    • Fetch the actor's public key
    • Verify the HTTP signature
    • Generate a random token, store it locally with a short TTL
    • Encrypt with the actor's public key (RSA PKCS #1 v1.5)
    • Return {"success": true, "encrypted_token": "<base64>"}
  3. On pages that accept owt= parameter:
    • Match the token against stored tokens
    • Log the user in as the remote identity
    • Delete the token immediately
  4. Implement a login form or zid= parameter handling to trigger the flow
  5. Decide what permissions authenticated remote users receive

Handling the zid= Parameter

Check for zid= on page loads. If present and the user is not already authenticated, initiate the OpenWebAuth flow. The zid value is the user's Fediverse address (e.g., alice@home.example).

Hardcoded Path Concerns

The /magic fallback path may conflict with CMS content. Best practice:

  1. Always check WebFinger first for the redirect/token endpoints
  2. Only fall back to /magic for backward compatibility with older Hubzilla/Streams instances
  3. Consider using /.well-known/open-web-auth for new implementations (proposed by benpate but not yet standardized)

Known Issues and Open Questions

  1. DRAFT status — FEP-61cf has not reached FINAL; the spec may change
  2. Browser-only — no support for mobile apps, API clients, or desktop applications (unlike OAuth/OIDC)
  3. Privacy concern — home instance learns every target the user visits; most implementations don't show consent screens
  4. Mastodon architectural gap — supporting accountless remote users requires fundamental changes to Mastodon's data model
  5. Hardcoded /magic path — conflicts with CMS installations; WebFinger-first discovery should become primary
  6. Missing spec details — cookie-based login verification and activity attribution to home instance actors are implementation requirements not fully documented in the FEP
  7. RSA-only encryption — the token encryption uses RSA PKCS #1 v1.5; no support for Ed25519 or other key types commonly used in newer ActivityPub implementations
  8. Redundancy debate — silverpill argued that self-controlled keys (FEP-ae97) could make OWA redundant; the community has not resolved this

Fediverse Portable Objects (FEP-ef61) — Complete Reference

Overview

Standard ActivityPub ties every object's identity to a specific server URL (e.g., https://mastodon.social/users/alice/statuses/12345). If that server shuts down, all its objects — posts, profiles, media — become permanently unreachable. The existing Move activity only migrates followers, not posts, likes, bookmarks, or other data.

FEP-ef61 (authored by silverpill, received 2023-12-06, status DRAFT) solves this by introducing server-independent identifiers for ActivityPub objects. Instead of HTTPS URLs, objects are identified by ap:// URIs where the authority component is a Decentralized Identifier (DID). Objects can be served by any gateway server, and migration is just a matter of changing which gateway serves them — the identity stays the same.

The concept descends from nomadic identity, pioneered over a decade ago by Mike Macgirvin in the Zot protocol (Hubzilla) and Nomad protocol (Streams). FEP-ef61 brings this capability to ActivityPub using W3C standards: Decentralized Identifiers (DIDs) and Verifiable Credential Data Integrity.


1. The ap URI Scheme

Portable objects use ap:// URIs instead of https:// URLs. The URI follows RFC 3986 with a DID as the authority:

ap://did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2/actor

Components:

  • Scheme: ap
  • Authority: A valid DID (percent-encoding permitted)
  • Path: Required, treated as opaque
  • Query/Fragment: Optional

A single DID subject can control multiple actors or objects, differentiated by the path component. The DID represents the identity; the path represents a resource owned by that identity (e.g., /actor, /posts/123).


2. Decentralized Identifiers (DIDs)

DIDs are a W3C standard (2022) providing globally unique identifiers that do not depend on any central registry or server. Format:

did:<method>:<method-specific-id>

did:key

The simplest DID method — encodes the public key directly in the identifier:

did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2
  • The z prefix indicates base58-btc Multibase encoding
  • No resolution infrastructure needed — the public key IS the identifier
  • Implementations MUST support did:key with base58-btc

did:ap:key

FEP-ef61 evolved from did:apkey to did:ap:key, positioning did:ap as a namespace that can support multiple constructions:

  • did:ap:key — wraps did:key
  • did:ap:web — wraps did:web
  • did:ap:pkh — wraps did:pkh

The did:ap resolution algorithm: remove the :ap segment and resolve the remaining DID using its native method.

Community debate: bumblefudge argued that nesting DIDs within DIDs "breaks the spirit" of the DID specification. silverpill defended it as a legitimate resolution algorithm that the spec doesn't prohibit.


3. Gateways — How Portable Objects Are Served

Since ap:// URIs cannot be fetched directly via HTTP, portable objects are served through gateway servers.

The gateways property

Portable actors MUST include a gateways property listing HTTP(S) URLs where the current version of the actor can be fetched:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/data-integrity/v1"
  ],
  "type": "Person",
  "id": "ap://did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2/actor",
  "gateways": [
    "https://server-a.example",
    "https://server-b.example"
  ]
}

Migration: To move to a new server, update the gateways list. The ap:// identity stays the same. Old gateways can be removed once migration is complete.

Dereferencing via /.well-known/apgateway

Clients fetch portable objects through the gateway's well-known endpoint:

GET https://server-a.example/.well-known/apgateway/did:key:z6Mk.../actor

The URL is constructed by:

  1. Taking the ap:// URI
  2. Removing the ap:// prefix
  3. Appending the remainder to the gateway's /.well-known/apgateway/ path

Multiple gateways

Multiple gateways provide redundancy — if one server goes down, the object is still reachable through another. This is the core of how FEP-ef61 prevents data loss from server shutdowns.


4. Integrity Proofs (FEP-8b32) — Required Dependency

All portable objects MUST include cryptographic integrity proofs so consumers can verify they weren't tampered with, regardless of which gateway served them. FEP-8b32 defines how this works:

Signing process

  1. Canonicalize the ActivityPub object using JSON Canonicalization Scheme (JCS, RFC 8785) for deterministic serialization
  2. Hash the canonicalized output with SHA-256
  3. Construct a DataIntegrityProof specifying eddsa-jcs-2022 (EdDSA signing with SHA-256 hashing and JCS canonicalization)
  4. Concatenate the proof hash and document hash
  5. Sign with EdDSA and encode the 64-byte signature as Multibase

Verification

  1. Extract the proof from the object
  2. Reconstruct the document hash (without the proof)
  3. Reconstruct the proof hash
  4. Verify the signature against the public key derived from the DID

Example proof structure

{
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "verificationMethod": "did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
    "proofPurpose": "assertionMethod",
    "created": "2024-01-15T12:00:00Z",
    "proofValue": "z..."
  }
}

This is what makes objects truly portable — anyone can verify the object came from the claimed identity, regardless of which server delivered it.


5. Authentication — Origin-Based Security (FEP-fe34)

FEP-ef61 uses an origin-based security model from FEP-fe34. The cryptographic origin (the DID in the ap:// URI) must match the signing key. This replaces the traditional model where the HTTPS domain of the URL is the trust anchor.

For traditional ActivityPub, authentication works like:

  • Object ID is https://server.example/post/123
  • Trust anchor is server.example (the domain)
  • HTTP Signatures prove the request came from that domain

For portable objects:

  • Object ID is ap://did:key:z6Mk.../post/123
  • Trust anchor is did:key:z6Mk... (the cryptographic key)
  • Integrity proofs (FEP-8b32) prove the object was created by the key holder
  • Any gateway can serve it — the gateway is not the trust anchor

6. Identity Proofs (FEP-c390)

FEP-c390 links ActivityPub actor profiles to their canonical DID identities. Actors embed VerifiableIdentityStatement objects in their attachment array, cryptographically proving the relationship between the HTTPS actor URL and the DID:

{
  "type": "Person",
  "id": "https://server.example/users/alice",
  "attachment": [
    {
      "type": "VerifiableIdentityStatement",
      "subject": "did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
      "proof": {
        "type": "DataIntegrityProof",
        "cryptosuite": "eddsa-jcs-2022",
        "verificationMethod": "did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
        "proofPurpose": "assertionMethod",
        "proofValue": "z..."
      }
    }
  ]
}

This enables a bridge between the traditional HTTPS-based ActivityPub world and the portable ap:// world.


7. Public Key Representation (FEP-521a)

FEP-521a modernises how public keys are represented on actors. Instead of the legacy publicKey + PEM encoding pattern, it uses:

  • assertionMethod property (from Verifiable Credential Data Integrity)
  • Multibase encoding with publicKeyMultibase
  • Single-character prefix: z = base58-btc (recommended), u = base64-url

This replaces verbose PEM encoding and eliminates the need for ASN.1 DER parsing libraries.


8. Media Integrity

External resources (images, video, audio) attached to portable objects MUST include digestMultibase properties containing SHA-256 hashes:

{
  "type": "Image",
  "url": "https://server.example/media/photo.jpg",
  "digestMultibase": "zQm..."
}

This allows:

  • Verification that media hasn't been tampered with
  • Content-addressed retrieval through any gateway
  • Hashlinks as resource URIs for integrity verification

9. Backward Compatibility

FEP-ef61 addresses the practical challenge that most existing ActivityPub software only understands HTTPS URLs.

Gateway-based HTTP(S) URLs

Publishers construct backward-compatible URLs using the first gateway in the gateways list:

https://server-a.example/.well-known/apgateway/did:key:z6Mk.../actor

Existing software can fetch this URL normally. Software that understands ap:// URIs strips the gateway prefix and reconstructs the canonical ap:// form.

The aliases property

Portable objects may include an aliases property listing alternative identifiers (including HTTPS URLs) for the same resource.

Note: silverpill chose aliases instead of alsoKnownAs because of a semantic conflict. In the DID specification, alsoKnownAs means "different identifiers for the same resource." In Mastodon's usage, it means "different subjects with the same controller" (for account migration). trwnh documented that while DID WG and SWICG agreed in 2021 to use as:alsoKnownAs, Mastodon's pre-existing usage created incompatible semantics. The aliases property may be extracted into a separate FEP (FEP-d2da, pre-draft).


10. The Full Decentralized Identity Stack

These FEPs work together to enable portable objects:

FEPNameRole
FEP-521aPublic Key RepresentationMultibase key encoding on actors
FEP-8b32Object Integrity ProofsCryptographic signing of objects (eddsa-jcs-2022)
FEP-c390Identity ProofsLinking HTTPS actors to DIDs via VerifiableIdentityStatement
FEP-fe34(unnamed)Origin-based security model
FEP-ef61Portable ObjectsServer-independent ap:// identifiers with gateway resolution

The dependency chain: FEP-ef61 requires FEP-8b32 (integrity proofs) and FEP-fe34 (origin-based auth). FEP-8b32 requires FEP-521a (key representation). FEP-c390 bridges traditional and portable identity.


11. Relationship to Nomadic Identity (Zot/Nomad)

FEP-ef61 is the ActivityPub equivalent of nomadic identity, which was pioneered over a decade ago:

Zot/Nomad (Hubzilla/Streams)FEP-ef61 (ActivityPub)
Identity modelChannel-based, server-independentDID-based, server-independent
Object IDsServer-independentap:// URIs with DID authority
Multi-homingNative (clone channels across servers)Via gateways property
IntegrityProtocol-levelFEP-8b32 Data Integrity proofs
MigrationSeamless (nomadic)Update gateways list
AdoptionHubzilla, Streams onlyGrowing (Streams, Mitra, Forte, tootik)

Mike Macgirvin (creator of Zot/Nomad/Hubzilla/Streams) implemented FEP-ef61 in Streams, making it the first platform to support nomadic identity over ActivityPub. Streams and Mitra are collaborating on the first cross-platform implementation.

silverpill prefers the terms "cryptographic identity" or "key-based identity" over "nomadic identity" — the key insight being that "the combination of cryptographic identity and cryptographic integrity proofs makes objects portable."


12. Implementation Matrix

PlatformFEP-ef61 SupportDetails
StreamsFullFirst to implement; built by Mike Macgirvin (Zot/Nomad creator)
MitraGatewayGateway config (disabled by default), resolver endpoint, portable inboxes/outboxes with DID signatures, portable Like activities
ForteNotedListed as implementation
tootikNotedListed as implementation
fep-ae97-clientClientClient-side implementation
FedifyRequestedFeature request (issue #288); FEP-8b32 dependency already available
HolloRequestedFeature request (issue #211)
MastodonNoneNo current support or announced plans

13. Comparison with Other Portability Approaches

Move activity (current Mastodon approach)

The Move activity only migrates followers. Posts, likes, bookmarks, lists, and media remain on the old server. If the old server shuts down, all that data is lost. There is no standard for cross-implementation migration.

LOLA (Linked Open Local Authority)

LOLA is a separate specification from the W3C Social Web Incubator Community Group focused on data export/import for migration. It addresses the practical need to move accounts in response to moderation decisions, server shutdowns, or policy changes. LOLA and FEP-ef61 are complementary: LOLA focuses on data portability (moving data between servers), while FEP-ef61 focuses on identity portability (objects that don't need to move because they were never tied to a server).

Domain-based resolution

An alternative approach where users control a domain that maps to their actual host (similar to DNS). Simpler than DIDs but still ties identity to domain ownership, which has its own costs and failure modes.


14. Known Issues and Open Questions

  • Retrofitting existing objects: Existing ActivityPub objects already have HTTPS URLs as identifiers. There is no practical way to convert them to ap:// URIs retroactively across the entire network.
  • did:ap method registry: The did:ap:key syntax (nesting DID methods) is controversial. Whether did:ap can be registered as a formal DID method is debated.
  • aliases vs alsoKnownAs: The property naming conflict between DID and Mastodon semantics is unresolved. FEP-d2da (pre-draft) proposes extracting aliases into its own FEP.
  • Mastodon adoption: Mastodon has not signalled plans to support portable objects, and its dominant market position means most fediverse users cannot benefit from FEP-ef61 yet.
  • Complexity: The full stack (FEP-521a + FEP-8b32 + FEP-c390 + FEP-fe34 + FEP-ef61) is substantially more complex to implement than traditional HTTP Signatures + HTTPS URLs.
  • Gateway trust: While integrity proofs ensure objects aren't tampered with, gateway availability and censorship resistance are separate concerns not fully addressed by the FEP.

Fediverse Relays — Complete Reference

Overview

A relay is a service-type ActivityPub actor that re-broadcasts public content between subscribed servers. It solves a core discovery problem: without relays, a new or small instance only sees content from accounts its users explicitly follow, leaving the federated timeline empty and hashtag search incomplete.

Relays function as "a commons of public content" — participating servers send their public posts to the relay, and the relay distributes them to all other subscribers. This is an admin-level operation, not something individual users control.

There is no separate relay specification. Relay behaviour is an application of the core ActivityPub spec, primarily using the Announce activity type and the standard Follow/Accept subscription flow.


1. The Relay Actor

A relay is represented as an ActivityPub actor, typically with "type": "Application" or "type": "Service". It exposes the standard endpoints needed for federation:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1"
  ],
  "type": "Application",
  "id": "https://relay.example.com/actor",
  "inbox": "https://relay.example.com/inbox",
  "publicKey": {
    "id": "https://relay.example.com/actor#main-key",
    "owner": "https://relay.example.com/actor",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIB...\n-----END PUBLIC KEY-----"
  },
  "url": "https://relay.example.com/actor",
  "endpoints": {
    "sharedInbox": "https://relay.example.com/inbox"
  }
}

Key points:

  • The relay actor's inbox is where subscribing servers send activities
  • The publicKey is used for HTTP Signature verification
  • Most relay implementations also expose /.well-known/webfinger, /.well-known/nodeinfo, and /nodeinfo/2.0 for discovery

2. The Subscription Handshake

Subscribing — Follow the Public collection

A server subscribes to a relay by sending a Follow activity where the object is the special public collection URI:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://instance.example/activities/relay-follow-1",
  "type": "Follow",
  "actor": "https://instance.example/actor",
  "object": "https://www.w3.org/ns/activitystreams#Public"
}

Requirements:

  • The object field must be exactly "https://www.w3.org/ns/activitystreams#Public" — this is what distinguishes a relay subscription from a normal user follow
  • The actor must resolve to an object with both inbox and endpoints.sharedInbox properties
  • The request must be signed with a valid HTTP Signature

Acceptance

On successful subscription, the relay responds with an Accept:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://relay.example.com/activities/accept-1",
  "type": "Accept",
  "actor": "https://relay.example.com/actor",
  "object": {
    "type": "Follow",
    "actor": "https://instance.example/actor",
    "object": "https://www.w3.org/ns/activitystreams#Public"
  }
}

Some relays require manual approval before sending the Accept. The subscribing server should handle an indefinite pending state gracefully.

Unsubscribing — Undo Follow

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://instance.example/activities/undo-relay-follow-1",
  "type": "Undo",
  "actor": "https://instance.example/actor",
  "object": {
    "type": "Follow",
    "actor": "https://instance.example/actor",
    "object": "https://www.w3.org/ns/activitystreams#Public"
  }
}

3. The Two Relay Protocols

Two protocols exist in the wild. They differ in how a server addresses the relay when subscribing, but the underlying ActivityPub mechanics are the same.

Mastodon Relay Protocol

  • The subscribing server uses the relay's inbox endpoint IRI — e.g. https://relay.example.com/inbox
  • Uses HTTP Signatures for verification
  • Uses the standard Follow/Accept flow described above
  • Subscription is performed at the server admin level only

LitePub / Pleroma Relay Protocol

  • The subscribing server uses the relay's actor document IRI — e.g. https://relay.example.com/actor
  • The inbox is derived automatically from the actor document
  • Allows any actor to communicate with relays, not just admin-controlled instance actors
  • LitePub is a set of conventions extending ActivityPub

Which endpoint to use

PlatformSubscription Endpoint
Mastodon/inbox
Misskey and forks/inbox
Pleroma / Akkoma/actor
snac/actor

Both endpoints are typically served by the same relay software. A relay that supports both protocols will accept subscriptions at either endpoint.


4. How Relays Process Activities

Once a server is subscribed, it sends all its public activities to the relay's inbox. The relay then distributes them to all other subscribers using one of two mechanisms:

Message relaying (Announce wrapping)

For Create and Announce activities, the relay wraps the object in a new Announce activity attributed to the relay actor:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://relay.example.com/announces/789",
  "type": "Announce",
  "actor": "https://relay.example.com/actor",
  "object": "https://instance.example/users/alice/statuses/123",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": []
}

This is the primary distribution mechanism. The receiving server sees an Announce from the relay and fetches the original object if needed.

Message forwarding (direct re-delivery)

For Update, Delete, Like, Undo, Move, Add, and Remove activities, the relay POSTs the activity directly to all subscribers unmodified — it does not wrap it in an Announce.

This is necessary because wrapping these activity types in Announce would change their semantics (e.g. an Announce{Delete} does not mean the same thing as a Delete).

LD-Signatures and forwarding

Activities that carry valid linked-data signatures can be forwarded directly (the recipient can verify the original author's signature). Activities that lack LD-signatures must be wrapped in Announce instead, because the relay cannot prove the activity's origin otherwise.

Filtering rules

Most relay implementations apply these filters:

  • Only activities addressed to https://www.w3.org/ns/activitystreams#Public (in to or cc) are accepted
  • Activities older than ~30 minutes are skipped
  • Duplicate activity IDs are rejected to prevent reprocessing

5. Relay Endpoints

A typical relay exposes these HTTP endpoints:

EndpointMethodPurpose
/actorGETReturns the relay's ActivityPub actor document
/inboxPOSTReceives activities from subscribers
/.well-known/webfingerGETWebFinger discovery
/.well-known/nodeinfoGETNodeInfo discovery document
/nodeinfo/2.0GETNodeInfo schema (software name, version, stats)

Some implementations also expose:

  • /stats — relay statistics (subscriber count, activity throughput)

6. Types of Relays

General-purpose relays

Broadcast all public content from all subscribed servers. Maximum content discovery, but high resource cost. A general relay with a few large, active servers subscribed will generate significantly more traffic than one with many small servers.

Geographic / community relays

Restricted to servers in a specific region or community. Reduces volume while keeping content culturally relevant. Examples include relays limited to Australian/New Zealand instances or Canadian instances.

Topic-based / selective relays (FediBuzz model)

FediBuzz (relay.fedi.buzz) takes a fundamentally different approach. Instead of receiving activities from subscribers, it connects to Mastodon's Streaming API and allows per-subscriber customisation:

  • Follow specific hashtags — only relay posts matching chosen tags (supports smart matching: following #dd captures #dd1302 etc.)
  • Follow specific instances — only relay posts from chosen servers
  • Language filtering — only relay posts in chosen languages

This dramatically reduces resource consumption compared to general relays. The trade-off is that it requires API access to source instances rather than using the standard relay subscription model.


7. Building a Relay — Implementation Guide

Minimum viable relay

A minimal relay implementation must:

  1. Serve an actor document at a stable URL with a valid publicKey, inbox, and endpoints.sharedInbox
  2. Accept Follow activities where the object is as:Public — validate HTTP Signatures, store the subscriber, and respond with Accept
  3. Accept Undo{Follow} — remove the subscriber
  4. Accept incoming activities at the inbox — validate that they are addressed to Public, then distribute to all subscribers
  5. Distribute activities — for each subscriber, POST the activity (or an Announce wrapping it) to the subscriber's sharedInbox
  6. Sign all outgoing requests with HTTP Signatures using the relay actor's private key

Activity types to handle

Incoming activityRelay action
Follow (object = as:Public)Store subscriber; send Accept
Undo{Follow}Remove subscriber
CreateWrap in Announce; deliver to all subscribers
AnnounceWrap in Announce or forward; deliver to all subscribers
UpdateForward directly to all subscribers
DeleteForward directly to all subscribers
LikeForward directly to all subscribers
Undo (other than Follow)Forward directly to all subscribers
MoveForward directly to all subscribers
Add / RemoveForward directly to all subscribers

Delivery optimisation

  • Always use sharedInbox when available — sending one request per subscribing server instead of one per actor
  • Use a job queue for async delivery — a relay with 100 subscribers means 100 outgoing HTTP requests per incoming activity
  • Implement retry logic with exponential backoff for failed deliveries
  • Cache resolved actors and their public keys (typical TTL: ~2 days)
  • Skip delivery to servers that have been consistently unreachable

HTTP Signatures

The relay must verify incoming HTTP Signatures and sign all outgoing requests. See the HTTP Signatures knowledge base for full details.

Notable relay-specific concern: when forwarding an activity, the relay signs the outgoing request with its own key. The keyId in the Signature header is the relay actor's key, not the original author's. This is why some implementations extract the actor from the keyId rather than from the activity's actor field — they may differ when a relay forwards content.


8. Subscribing to a Relay — Admin Guide

Mastodon

  1. Log in with admin credentials
  2. Navigate to Preferences > Administration > Relays
  3. Select "Setup A Relay Connection"
  4. Enter the relay URL with the /inbox suffix (e.g. https://relay.example.com/inbox)
  5. Click "Save And Enable"
  6. Wait for approval if the relay requires it

Pleroma / Akkoma

Use the CLI:

mix pleroma.relay follow https://relay.example.com/actor

or:

pleroma_ctl relay follow https://relay.example.com/actor

Misskey and forks

Use the admin panel to add a relay with the /inbox endpoint.

snac

Use the /actor endpoint:

https://relay.example.com/actor

9. Resource Impact and Trade-offs

What relays cost

Subscribing to a relay increases:

  • Bandwidth — every public post from every server on the relay is delivered to your inbox
  • Storage — all relayed posts are stored locally (unless your software has a retention policy)
  • Processing — each incoming activity must be validated, stored, and indexed
  • Moderation burden — relayed content may include posts that violate your server's rules

Sizing guidelines

  • A general relay with a few large, very active servers will produce significantly more traffic than one with many small servers
  • Topic-based relays (FediBuzz) are much lighter because they filter content before delivery
  • Monitor disk usage and database size after subscribing — some admins report rapid growth

When relays are most useful

  • New instances with few users and an empty federated timeline
  • Small instances that want better hashtag search coverage
  • Niche instances that want to connect with related communities

When relays may not be appropriate

  • Large instances that already have strong organic federation
  • Resource-constrained servers that cannot handle the additional load
  • Heavily moderated servers where unfiltered relay content creates moderation overhead

10. Moderation and Security

Content moderation gaps

Current relay implementations provide minimal moderation capabilities. A relay typically re-broadcasts everything it receives without content filtering. The subscribing server's own moderation tools (domain blocks, keyword filters) still apply to relayed content, but the volume can make moderation more difficult.

Recommendation: Verify a relay's content and subscriber list before subscribing. Check whether the relay operator maintains a blocklist.

No boost notifications

When a relay Announces a post, the original author does not receive a notification. The relay actor is the one performing the Announce, and implementations treat relay announces differently from user boosts.

Domain blocking

Some relay implementations (notably aode-relay) support domain blocklisting and allowlisting:

  • Blocklist mode: accept all subscribers except blocked domains
  • Allowlist mode (restricted): only accept explicitly approved domains

API token concerns

Some relay services (e.g. FediBuzz) request API tokens from subscribing instances. This grants broader access than necessary — potentially including followers-only and mentioned-only posts, which contradicts the relay principle of only handling public content. Evaluate what access a relay service requests before providing credentials.


11. Standardisation Efforts

Current state

There is no formal relay specification. The relay concept emerged organically from Mastodon's implementation and was independently implemented by Pleroma using the LitePub protocol. This has led to protocol fragmentation.

FEP-a974

A Fediverse Enhancement Proposal (FEP-a974) exists to formalise relay behaviour, addressing:

  • Standard subscription and unsubscription flows
  • Activity acceptance criteria
  • Relay actor type definitions
  • Terminology standardisation

SocialHub discussions

The SocialHub ActivityPub forum has extensive ongoing discussion about relay standardisation, including debates about:

  • What to call servers that publish to and consume from relays
  • Whether relays should have moderation capabilities
  • How to handle the two competing subscription protocols

12. Existing Relay Software

SoftwareLanguageProtocol SupportKey Feature
pub-relayCrystalMastodon + LitePubRigorous HTTP Signature verification; LD-signature-aware forwarding
Activity-RelayGoMastodon + LitePubRedis-backed job queue; CLI admin; YAML config
ActivityRelay (Pleroma)PythonLitePubMature (14 releases); configurable DB backends
aode-relayRustMastodon + LitePubLightweight; blocklist/allowlist; Prometheus metrics; Telegram admin bot
buzzrelay (FediBuzz)RustFollow-onlyStreaming API approach; hashtag/instance/language filtering; PostgreSQL

All are licensed under AGPLv3.

Notable differences

  • pub-relay is the closest to a reference implementation for the Mastodon relay protocol
  • Activity-Relay requires Redis and has the most structured architecture (API server + job worker + control utility)
  • aode-relay is the most feature-rich for moderation (blocklist, allowlist, restricted mode)
  • buzzrelay is architecturally different — it connects to Mastodon's Streaming API rather than receiving activities at an inbox

13. Common Implementation Mistakes

  • Wrong object in the Follow: subscribing with the relay actor's id as the object instead of as:Public — the relay will treat this as a normal follow, not a relay subscription
  • Missing sharedInbox: if the subscribing server's actor does not expose endpoints.sharedInbox, the relay may not be able to deliver activities
  • Not handling both subscription protocols: if building a relay, accept subscriptions at both /inbox and /actor to support all platforms
  • Wrapping Delete in Announce: forwarding a Delete as Announce{Delete} changes its semantics — Delete should be forwarded directly
  • Not filtering non-public activities: relays must only process activities addressed to as:Public — relaying non-public content violates user privacy
  • No deduplication: without tracking processed activity IDs, the same activity can be relayed multiple times if it arrives through different paths
  • Not signing outgoing requests: all deliveries from the relay must be signed with the relay actor's key, or receiving servers will reject them
  • Ignoring the /actor endpoint: serving only /inbox and not an actor document at /actor breaks Pleroma/Akkoma/snac subscription

Reverse WebFinger Discovery (FEP-2c59) — Complete Reference

Overview

WebFinger (RFC 7033) is the standard mechanism for discovering an ActivityPub actor from a human-friendly address like user@domain.example. The forward direction (WebFinger to actor) is well-defined. The reverse direction (actor to WebFinger address) is not — and this causes real problems across the Fediverse.

FEP-2c59 (authored by Evan Prodromou, received 2024-01-04, status DRAFT) proposes adding a webfinger property to ActivityPub actor objects to solve the reverse discovery problem explicitly.

The Problem: Reverse Discovery Is Broken

Forward Discovery (Well-Defined)

Converting user@domain to an actor URL is straightforward:

  1. Construct the query: https://domain/.well-known/webfinger?resource=acct:user@domain
  2. Parse the JRD (JSON Resource Descriptor) response
  3. Extract the href from the link with rel="self" and an ActivityPub media type

Reverse Discovery (Problematic)

Going the other direction — from an actor URL back to a user@domain handle — has no standard mechanism. Current implementations reconstruct it by extracting preferredUsername from the actor and combining it with the hostname from the actor's id URL:

actor.preferredUsername + "@" + hostname(actor.id)

This approach has three fundamental problems:

  1. preferredUsername is optional — it is not a required property in the ActivityPub specification, so it may be absent entirely.

  2. Domain mismatch — organizations may want WebFinger addresses on a different domain than where their ActivityPub server runs. For example, alice@company.tld while the AP server is at social.company.tld. The current approach constructs alice@social.company.tld instead.

  3. Semantic overload — preferredUsername serves double duty as both a display name preference and the WebFinger handle component, preventing it from serving either purpose cleanly.

The W3C Social Web Incubator Community Group (SWICG) acknowledged this explicitly in their "ActivityPub and WebFinger" report:

"Back-linking an actor to a WebFinger address could be more explicit. Current use of preferredUsername is not ideal for constructing WebFinger addresses, and it also does not allow for expressing actual 'preferred usernames'."

The Solution: The webfinger Property

FEP-2c59 proposes that actors SHOULD include a webfinger property containing their canonical WebFinger address.

Wire Format

The address may be plain or use the acct: prefix:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://purl.archive.org/socialweb/webfinger"
  ],
  "type": "Person",
  "id": "https://social.example/users/alice",
  "preferredUsername": "alice",
  "webfinger": "alice@example.org"
}

Or with the acct: prefix:

{
  "webfinger": "acct:alice@example.org"
}

Both forms are valid. The property is functional — at most one value per actor.

JSON-LD Context

The webfinger property is registered under:

https://purl.archive.org/socialweb/webfinger

Include this URL in the actor's @context array for proper JSON-LD processing.

Domain Mismatch Use Case

The motivating scenario for FEP-2c59:

An organization hosts its ActivityPub server at social.company.tld but wants employees to have addresses like alice@company.tld. Today this works via WebFinger redirects — company.tld/.well-known/webfinger redirects queries to social.company.tld/.well-known/webfinger.

But Mastodon's reverse discovery constructs alice@social.company.tld (from the actor URL hostname), not alice@company.tld (the intended address).

With FEP-2c59:

{
  "type": "Person",
  "id": "https://social.company.tld/users/alice",
  "preferredUsername": "alice",
  "webfinger": "alice@company.tld"
}

The intended address is stated explicitly — no guessing required.

Validation Requirements

When an implementation encounters a webfinger property, it MUST validate the claim:

  1. Perform a WebFinger lookup on the stated address
  2. The JRD response MUST contain a self link whose href matches the actor's id URL exactly
  3. No redirects allowed — the match must be a direct string comparison

Why No Redirects

RFC 7033 (WebFinger) makes HTTP redirects mandatory to support. FEP-2c59 deliberately prohibits redirects during validation to simplify confirmation to a string comparison. This was a point of contention in the community discussion, with mro arguing it violates RFC 7033 semantics. Evan Prodromou maintained that forbidding redirects makes validation unambiguous.

Validation Example

Given an actor with "webfinger": "alice@company.tld" and "id": "https://social.company.tld/users/alice":

  1. Query https://company.tld/.well-known/webfinger?resource=acct:alice@company.tld
  2. Expect a JRD with a link:
    {
      "subject": "acct:alice@company.tld",
      "links": [
        {
          "rel": "self",
          "type": "application/activity+json",
          "href": "https://social.company.tld/users/alice"
        }
      ]
    }
    
  3. Confirm href equals the actor's id — validation passes

Security Considerations

The webfinger property should only be trusted when:

  • It comes from dereferencing the actor's id URL directly (i.e., you fetched the actor document from its authoritative origin)
  • It is delivered with the actor's HTTP Signature via ActivityPub

A third party could spoof the webfinger property otherwise. For example, if actor A delivers an activity containing actor B's profile with a modified webfinger value, the recipient should not trust that claim without independent verification.

Always validate the webfinger claim by performing the forward WebFinger lookup and confirming the self link matches.

Mastodon's Current Reverse Discovery

Mastodon does not implement FEP-2c59. It uses the preferredUsername + hostname approach:

  1. Extract preferredUsername and the hostname from the actor's id URL
  2. Construct acct:preferredUsername@hostname
  3. Perform a WebFinger lookup to verify the address resolves back to the same actor
  4. If the JRD subject differs from the requested resource, follow up with another WebFinger request to the canonical subject

Mastodon Username Rules

  • Alphanumeric characters and underscores allowed anywhere
  • Dots and dashes only in the middle (not at start or end)
  • Case-insensitive
  • Regex: [a-z0-9_]+([a-z0-9_.-]+[a-z0-9_]+)?

When Mastodon's Approach Breaks

  • preferredUsername is absent from the actor
  • The WebFinger domain differs from the actor URL domain
  • The actor URL uses subdomains or non-standard paths
  • preferredUsername contains characters not valid in WebFinger handles

Community Debate: Alternative Approaches

The SocialHub discussion revealed several alternative proposals:

alsoKnownAs (stevebate)

Use the existing alsoKnownAs property with acct: URIs instead of adding a new property. Evan Prodromou objected because Mastodon uses alsoKnownAs for its Move (account migration) function — adding WebFinger addresses to it could interfere with migration semantics.

aliases from XRD/JRD (erincandescent)

Use the aliases array concept from WebFinger's JRD format:

{
  "aliases": ["acct:bob@example.com"]
}

Advantages cited:

  • Aligns WebFinger XRD/JRD values directly with ActivityStreams
  • Semantics are already understood because everyone implements WebFinger
  • Enables future extensibility for emerging identifier schemes (e.g., DIDs)
  • More capable than a dedicated webfinger field

Property Naming (trwnh)

Suggested renaming webfinger to webfingerAcct or acct for semantic clarity, since the property specifically holds an acct: URI, not a generic WebFinger resource.

Related Specifications

SpecificationRelationship
RFC 7033 (WebFinger)The underlying protocol; defines the /.well-known/webfinger endpoint and JRD format
RFC 7565 (acct: URI)Defines the acct:user@host URI scheme used in WebFinger queries
FEP-d556Complementary proposal for server-level actor discovery via WebFinger (vs FEP-2c59's user-level focus)
W3C SWICG "ActivityPub and WebFinger" reportAcknowledges the reverse discovery problem; does not reference FEP-2c59 by name

Implementation Guidance

If You Are Building a New ActivityPub Server

  1. Include the webfinger property on all actor objects
  2. Add https://purl.archive.org/socialweb/webfinger to the @context
  3. Set the value to the canonical user@domain address (with or without acct: prefix)
  4. Ensure your WebFinger endpoint returns a JRD with a self link pointing to the actor's id URL

If You Are Consuming ActivityPub Actors

  1. Check for the webfinger property first
  2. If present, validate it by performing a forward WebFinger lookup and confirming the self link matches the actor's id
  3. If absent, fall back to the preferredUsername + hostname approach
  4. Always verify any constructed address via forward WebFinger lookup

Defensive Parsing

  • Accept both "user@domain" and "acct:user@domain" formats
  • Strip the acct: prefix before display (users expect user@domain)
  • Do not assume preferredUsername exists — it is optional
  • Do not assume the WebFinger domain matches the actor URL domain

Known Issues and Open Questions

  1. DRAFT status — FEP-2c59 has not reached FINAL status; no implementations are listed in the FEP itself
  2. No-redirect controversy — the prohibition on redirects during validation conflicts with RFC 7033's mandatory redirect support
  3. Property naming unresolved — whether webfinger, webfingerAcct, or acct is the best name remains debated
  4. aliases alternative — the community has not reached consensus on whether a dedicated property or the aliases approach is preferable
  5. Mastodon adoption unknown — Mastodon has not indicated plans to adopt FEP-2c59
  6. JSON-LD context availability — the https://purl.archive.org/socialweb/webfinger context document's long-term availability is not guaranteed

WebFinger Protocol Quick Reference

For implementors who need a refresher on the underlying WebFinger protocol:

  • Endpoint: GET /.well-known/webfinger?resource=acct:user@domain
  • Response: JRD (JSON Resource Descriptor) with subject, optional aliases, and links array
  • Key link relation: rel="self" with type="application/activity+json" (or application/ld+json; profile="https://www.w3.org/ns/activitystreams") points to the ActivityPub actor URL
  • Standard: RFC 7033 (IETF, 2013)
  • Not part of ActivityPub — WebFinger is a convention the Fediverse adopted; the W3C ActivityPub spec does not mention it

Friendica — Complete Reference

Overview

Friendica is a free, open-source, decentralized social networking platform — the Fediverse's answer to Facebook. Created by Mike Macgirvin (former Netscape/AOL/Sun messaging engineer) in July 2010 under the original name "Mistpark," it is one of the oldest continuously active Fediverse projects, predating Mastodon by six years. Licensed AGPL-3.0.

Friendica's defining characteristic is its multi-protocol bridge role. It simultaneously speaks ActivityPub, the Diaspora protocol, and its native DFRN protocol, and connects (via addons) to Bluesky, Tumblr, GNU Social, email (IMAP/SMTP), and RSS/Atom feeds. Fedi.Tips calls it "a sort of Swiss Army knife of the Fediverse." Where Mastodon is a Twitter replacement (microblogging), Friendica is a Facebook replacement (full social networking) with Circles/Groups, photo albums, events, forums, 200,000-character posts, and fine-grained ACL-based privacy controls.

Current maintainers are Tobias Diekershoff (FSFE) and Michael Vogel. As of 2025: ~220 active instances, ~20,800 registered users, ~2.8 million statuses, 27,000+ commits from 250+ contributors.


1. History and Lineage

DateEvent
July 2010Mike Macgirvin creates Mistpark in Australia, motivated by "Quit Facebook Day" privacy concerns
Mid-2010Within first month: federation with StatusNet (OStatus), RSS, email integration
Late 2010Renamed to Friendika
July 2011Zot protocol first named (Macgirvin's next-gen protocol design)
Sep 2011Macgirvin forks as "Free-Friendika" (MIT license)
Oct 2011Name changed to Friendica
Jan 2012First "Friendica" release (v2.37)
2012Diaspora protocol reverse-engineered from scratch (~6 months)
May 2012Macgirvin departs, forks into Red / Friendica Red (MIT)
2012-2013Red becomes Red Matrix
May 2015Red Matrix renamed to Hubzilla
Dec 2018ActivityPub support shipped
May 2023Initial Bluesky connector
Dec 2023Bidirectional Bluesky; Circles and Channels introduced
Jan 2025v2024.12: OStatus dropped, Prometheus metrics, FEP-67ff
Jan 2026v2026.01 "Blutwurz": reworked hook system, media embedding overhaul

The Fork Lineage

Mistpark (2010)
  └─> Friendika (2010) ─> Friendica (2011, AGPL-3.0)
  └─> Free-Friendika (2011, MIT)
        └─> Red / Friendica Red (2012)
              └─> Red Matrix (2013)
                    └─> Hubzilla (2015, Zot protocol)
                          └─> Osada, Zap, Roadhouse (2018-2022)
                                └─> Streams (2021-present, Nomad protocol)
                                      └─> Forte (2024, ActivityPub-only)

Founding Motivation

Macgirvin left Facebook in early 2010 and found no decentralized alternative with both Facebook-like interactivity and privacy. StatusNet's OStatus had "absolutely nothing in the way of privacy." He created the DFRN protocol to address four gaps:

  1. No protocol for friend connections
  2. No privacy support in social protocols
  3. No cross-server wall posting
  4. Private media required sending copies to all recipients

2. Technology Stack

LayerTechnology
Backend languagePHP (7.4+, 8.x recommended, supports 8.5)
DatabaseMariaDB (recommended), MySQL, PostgreSQL 9.6+
Web serverApache (mod-rewrite) or Nginx
Template engineSmarty3
Dependency managementComposer
DI containerDice
Themesfrio (default), vier, quattro
LicenseAGPL-3.0
Hardware minimum2 GB RAM
Required PHP extensionsCurl, GD, GMP, PDO, mbstring, Intl, MySQLi, OpenSSL, POSIX

Entry Points

  • Web: index.php → App::processRequest()
  • CLI: bin/console.php → App::processConsole()
  • Worker: bin/console.php worker (or legacy bin/worker.php)

Configuration Hierarchy (increasing priority)

  1. static/defaults.config.php — system defaults
  2. static/settings.config.php — admin-configurable defaults
  3. config/local.config.php — instance-specific overrides
  4. config database table — runtime settings (highest)

3. Federation Protocols

Friendica is unique in speaking multiple federation protocols simultaneously, acting as a bridge between otherwise-separate ecosystems.

Currently Supported

ProtocolPurposeSince
ActivityPubFederation with Mastodon, Pleroma, Pixelfed, PeerTube, Lemmy, etc.Dec 2018
Diaspora protocolFederation with Diaspora pods, Hubzilla2012
DFRNNative Friendica-to-Friendica federationJuly 2010
WebFingerUser discovery—
HTTP SignaturesRequest authentication for ActivityPub—
NodeInfoServer metadata discovery—
SalmonMessage exchange for replies and mentions—

Dropped

ProtocolDroppedReason
OStatus (PubSubHubbub + Atom)v2024.12Too few active OStatus-only servers

Supported FEPs

Nine FEPs including: group federation (Lemmy/Kbin compatible), OpenWebAuth (Hubzilla login), long-form text (partial), application actor identification, object links, and FEP-67ff (FEDERATION.md).


4. The DFRN Protocol

Distributed Friends and Relations Network — Friendica's native protocol for Friendica-to-Friendica federation. Creates an authenticated pipe between users using public-key cryptography.

Message Format

  • Atom Syndication Protocol wrapper with ActivityStreams 1.0, threading, and media extensions
  • Content in BBCode internally
  • Specification: spec/dfrn2.pdf in the Friendica repository

Key Concepts

  • Distinguishes author (content creator) from owner (profile host)
  • Communication boundary is the individual's profile page
  • "Friends of friends" are visible, but direct contact required for communication with third parties

Endpoints

EndpointPurpose
dfrn_requestFriend/contact requests
dfrn_notifyDelivery (push)
dfrn_pollFeed retrieval (pull)

Handshake

  1. Remote site POSTs to dfrn_poll with type=profile-check
  2. Includes duplex direction, relationship dfrn_id, and a random number encrypted with the site's DFRN public key
  3. Original site decodes dfrn_id, verifies relationship, decodes challenge, matches sec string

Delivery Model

  • Public messages: dual path — BBCode to DFRN clients + HTML conversion with PubSubHubbub notification
  • Private messages: direct delivery via dfrn_notify to recipients only; public hubs remain uninformed
  • Polling: src/Worker/OnePoll.php with configurable intervals (up to 5-minute checks)
  • Retry: failed deliveries are queued for automatic retry

5. ActivityPub Implementation

Architecture

Three main classes in src/Protocol/ActivityPub/:

ClassRole
ReceiverHTTP Signature verification, activity validation, JSON decoding
ProcessorActivity type handling (Create, Update, Delete, Like, Announce)
TransmitterJSON-LD generation for outbound activities

Delivery: Worker/Notifier calculates recipients by protocol, spawning APDelivery workers for ActivityPub contacts.

Supported Features

  • Follow/unfollow accounts
  • Public and non-public messaging
  • Posting, commenting, liking, unliking, deletion
  • Bidirectional comment distribution (thread-based and per-posting models)
  • Thread completion (prevents conversation fragmentation)
  • Failed delivery retry queuing
  • Sends Follow for root post IDs to request inclusion in receiver collections

Known Limitations

  • No native direct messages via ActivityPub (workaround: non-public post restricted to single recipient)
  • No account migration between nodes via ActivityPub

Mastodon-Compatible API

Extensive coverage:

  • Accounts: verify_credentials, follow/unfollow/block/unblock/mute/unmute, followers, following, relationships, search
  • Statuses: create/get/delete, favourite/unfavourite, reblog/unreblog, bookmark, pin/unpin, context
  • Timelines: home, public, tag, list, direct
  • Notifications: list, get, clear, dismiss
  • Other: conversations, lists, media, search v1/v2, instance info, follow requests, emojis, directory, polls, push subscriptions

Not implemented: profile updates via API, familiar followers, trending, poll voting, streaming, admin functions, domain blocks

Compatible clients: Tusky, Fedilab, Sengi, Twidere, AndStatus, Bitlbee, Raccoon for Friendica.


6. Cross-Network Connectivity

Built-in (no addon needed)

NetworkProtocol
Mastodon, Pleroma, Pixelfed, PeerTube, Lemmy, Kbin, MisskeyActivityPub
Diaspora, Hubzilla, SocialhomeDiaspora protocol
Other Friendica nodesDFRN
EmailIMAP4rev1 / ESMTP (bidirectional)
Any website/blogRSS/Atom feed import

Addon Connectors (bidirectional)

NetworkNotes
BlueskyNo API key needed; bidirectional since v2023.12
pump.ioPosting, relaying, reading
GNU SocialVia statusnet addon

Addon Connectors (post-only)

Tumblr, WordPress (XMLRPC), LiveJournal, Dreamwidth, InsaneJournal, Libertree, Blogger, Buffer

Deprecated

  • Twitter — removed due to API changes under Musk
  • Facebook/Google+ — removed when APIs shut down

7. Privacy and Access Control

Friendica's privacy model is significantly more granular than most Fediverse platforms:

  • Posts default to private (configurable by admin to default public)
  • Access Control Lists (ACLs) on every post via lock icon UI
  • Circles (formerly Groups) for organizing contacts into permission sets
  • Per-post overrides: select specific individuals or Circles to allow/deny
  • Multiple profiles: different profiles for different audiences (family, friends, public)
  • Anonymous profile viewing can be disabled
  • Post deletion triggers removal notifications to all recipients
  • Content expiration with automated removal from remote Friendica servers

Cross-Network Limitation

Privacy only fully works within Friendica's native protocols. Posts shared via ActivityPub or other protocols lose fine-grained ACL enforcement — the receiving server controls display. Private photo sharing only works reliably between Friendica members.

Once published, post permissions CANNOT be changed.


8. Content Model

Post Capabilities

FeatureDetails
Maximum length200,000 characters
MarkupBBCode (bold, italic, headings h1-h6, code blocks, tables, spoilers, lists)
MediaImages (with alt text, dimensions), video (YouTube/Vimeo/generic), audio, OEmbed
AlbumsPhoto albums with tagging and per-album privacy
EventsDate, time, location, RSVP
ForumsPublic and private, federated
PollsLimited (not supported via Diaspora protocol)
NotesPrivate notebook (notes to self)
MapsBy address, coordinates, or post location
Abstract/summaryPer-network overrides (e.g., [abstract=twit] for Twitter-length)

Object Types

Friendica represents posts as ActivityPub Note objects when federating via ActivityPub. Internally, content is stored in BBCode and converted to HTML or ActivityPub JSON as needed for each protocol.


9. Database Schema

97 tables, utf8mb4 charset. Schema version tracked by DB_UPDATE_VERSION.

Hub-and-Spoke Content Model

TablePurpose
item-uriURI registry for deduplication
postProtocol-agnostic metadata (author-id, owner-id, created)
post-userPer-user states (starred, hidden, visibility)
post-contentBody text
post-mediaAttachments with MIME types
post-thread / post-thread-userThread structure
post-historyEdit history
post-delivery / post-delivery-dataDelivery tracking
post-tag / post-categoryTags and categories
post-question / post-question-optionPolls
delayed-postScheduled posts

A single post can be visible to multiple users with different permission levels without duplicating content — the post-user table stores per-user state separately from post-content.

Contact Tables

TablePurpose
contactBoth local and remote actors
apcontactActivityPub-specific contact data
fcontactDiaspora-specific contact data
contact-relationRelationship graph
user-contactPer-user contact settings

Relationship Constants

NOTHING=0, FOLLOWER=1, SHARING=2, FRIEND=3, SELF=4

Server/Federation Tables

gserver (known servers), endpoint (AP endpoints), inbox-status (AP inbox tracking), diaspora-interaction (signed Diaspora interactions)


10. Architecture

8-Layer Model

  1. Client Layer — browsers, mobile apps (Raccoon, Fedilab), third-party clients via Mastodon API
  2. Frontend Layer — theme system (frio/vier/quattro), JavaScript, localization
  3. Application Layer — Router with 600+ routes (static/routes.config.php), modules, API endpoints
  4. Business Logic Layer — Model classes: Item, Contact, User
  5. Content Processing Layer — BBCode formatting, media processing, URL parsing
  6. Federation Layer — Friendica\Protocol\ActivityPub, Friendica\Protocol\Diaspora, Friendica\Protocol\DFRN
  7. Data Layer — Database abstraction (DBA), schema management (DBStructure)
  8. Background Processing — Worker queue with priority levels

Worker Queue

PriorityValue
CRITICAL10
HIGH20
MEDIUM30
LOW40
NEGLIGIBLE50

Tasks enqueued via Worker::add() into workerqueue table. Default 10 parallel instances. Worker/Notifier routes deliveries to protocol-specific workers (APDelivery, Delivery).

Namespaces

Friendica\Module, Friendica\Model, Friendica\Protocol, Friendica\Worker, Friendica\Core, Friendica\Database, Friendica\Util

Dependency Injection

Dice DI container. Services accessed via static DI class: DI::dba(), DI::config(), DI::logger(), DI::session(), DI::baseUrl(), DI::l10n().


11. Addon/Plugin System

Hook-based architecture with 100+ hooks. Addons live in addon/ directory, each in its own subdirectory.

Required Functions

function <addon>_install() {
    \Friendica\Core\Hook::register($hookname, $file, $function);
}
function <addon>_uninstall() { }

Callback Signature

function <addon>_<hookname>(App $a, &$b) { }

$a is the Friendica App class; $b is hook-specific data passed by reference.

Major Hook Categories

CategoryHooks
Contentpost_local, post_local_end, post_remote, display_item, prepare_body
Authauthenticate, logged_in, register_post
Profileprofile_post, profile_edit, profile_sidebar
Contactsfollow, unfollow, revoke_follow, block, unblock
Settingsaddon_settings, connector_settings
Systeminit_1, load_config, route_collection
Federationprobe_detect, item_by_link

Module Intercept

Addons can act as full page modules by defining:

function <addon>_module() {}      // signals module capability
function <addon>_content(App $a) {} // returns HTML

Notable Addons

  • Cross-posting: bluesky, tumblr, diaspora, discourse, wppost, ljpost, dwpost
  • Storage: s3_storage, webdav_storage
  • Auth: ldapauth, saml, keycloakpassword
  • Privacy: securemail (GPG-encrypted notifications)
  • Filters: advancedcontentfilter, langfilter, nsfw, superblock

12. Installation and Deployment

Methods

  1. Git clone: git clone -b stable + composer install --no-dev + web installer
  2. CLI: bin/console autoinstall with config file or env vars
  3. Docker: docker pull friendica (official image)
  4. YunoHost: app package available

Critical Requirements

  • Cron every 5-10 minutes: bin/worker.php (or daemon mode)
  • HTTPS/TLS mandatory
  • Must be at top-level domain or subdomain (not directory path) for Diaspora federation
  • Domain cannot be changed after installation

Scaling

  • Nginx preferred over Apache (~2x capacity)
  • Database tuning via mysqltuner.pl
  • PHP-FPM for faster processing
  • Configurable worker queue parallelism (default 10)
  • Extended poller intervals (30-60 min) for large instances

13. Federation Interoperability

Friendica as Protocol Bridge

Friendica's unique value is connecting users across protocol boundaries:

Mastodon user ←─ActivityPub─→ Friendica ←─Diaspora protocol─→ Diaspora pod
                                  ↕
                              DFRN native
                                  ↕
                           Bluesky (addon)
                                  ↕
                         RSS/Atom/Email/Tumblr

A Friendica user can follow a Mastodon account, a Diaspora contact, a Bluesky account, and an RSS feed — all in the same timeline.

vs. Mastodon

FeatureFriendicaMastodon
Post length200,000 chars500 chars
ProtocolsAP + Diaspora + DFRN + addonsAP only
Contact groupsCircles with ACLsLists (no ACLs)
RSS readerBuilt-inNo
Photo albumsYesNo
Events/calendarYesNo
Quote postsYes (early pioneer)Added later
ForumsYes (public + private)No
BBCodeYesNo

Known Issues

  • Friendica's rich content (BBCode formatting, long posts) may be truncated or stripped by Mastodon's HTML filtering
  • Privacy ACLs only enforceable within Friendica — remote servers control their own display
  • Private photos only reliable between Friendica members
  • Comment counts may be inaccurate on remote instances due to incomplete thread federation

14. Governance and Community

  • No corporation, foundation, or board — informal volunteer governance
  • Core maintainers: Tobias Diekershoff (FSFE), Michael Vogel
  • Communication: Friendica forums (dogfooding the platform)
  • Code: GitHub + self-hosted Gitea at git.friendi.ca
  • Mascot: Flaxy O'Hare (rabbit, CC0)
  • Release cadence: quarterly stable releases, year.month versioning
  • No direct donations accepted — covers server costs only

15. Common Implementation Mistakes

  • Assuming Friendica only speaks ActivityPub: Friendica may deliver content via DFRN or Diaspora protocol depending on the contact type — inspect the contact's protocol, not just the server software
  • Not handling long posts: Friendica posts can be up to 200,000 characters — truncate gracefully rather than rejecting
  • Ignoring BBCode in content: Friendica's native format is BBCode, converted to HTML for ActivityPub — the HTML may contain richer formatting than typical Mastodon posts
  • Expecting Mastodon API parity: Friendica's Mastodon API has gaps (no streaming, no admin API, no poll voting) — test against a real Friendica instance
  • Not supporting the Application instance actor: Friendica uses an instance-level actor for some federation tasks — verify keys from Application actors, not just Person
  • Dropping unknown properties: Friendica posts may include properties from DFRN or Diaspora context — ignore unknown properties rather than rejecting the entire object
  • Assuming public-by-default: Friendica defaults to private posts (admin-configurable) — a Friendica instance may send fewer public posts than expected

Kbin / Mbin — Complete Reference

Overview

Kbin (stylized /kbin) was a decentralized content aggregator and microblogging platform for the Fediverse — a Reddit + Mastodon hybrid. Created by Ernest Wiśniewski (Polish developer) with development becoming serious in early 2023, the flagship instance kbin.social launched in April 2023. The project received NLnet funding (NGI0 Entrust Fund, December 2022).

Kbin is now discontinued. Its active community fork Mbin (founded October 2023 by Melroy van den Berg) continues development with significant improvements to federation, performance, and governance. When this document says "Kbin/Mbin," the information applies to both; Mbin-specific features are noted.

Kbin's key differentiator from Lemmy: it combines two content models in one platform — Reddit-style link aggregation (threads organized into magazines) and Mastodon-style microblogging (short-form posts). This dual nature enables stronger integration with microblogging platforms like Mastodon.

Licensed AGPL-3.0. Built with PHP/Symfony/PostgreSQL.


1. Technology Stack

ComponentTechnology
BackendPHP 8.2+
FrameworkSymfony
DatabasePostgreSQL
Message queueRabbitMQ
CacheRedis / KeyDB / Valkey
Real-timeMercure (optional)
FrontendTwig templates, SCSS, JavaScript
Image processingGD or ImageMagick
Web serverNginx, Apache, or Caddy
DeploymentDocker / Docker Compose
LicenseAGPL-3.0

Language Breakdown

  • PHP: 86.3%
  • Twig: 9.4%
  • SCSS: 2.5%
  • JavaScript: 1.6%

Development Tools

  • PHPUnit (testing), PHPStan (static analysis), Psalm (security scanning), Composer (dependencies), API Platform (API generation)

2. Content Model

Magazines

The primary organizational unit — equivalent to subreddits (Reddit), communities (Lemmy), or topics (PieFed). Any registered user can create a magazine and automatically becomes its owner with administrative tools including moderator appointment.

Content Types

TypeDescriptionAP Object
Thread (link)External links and articles with titlesPage
Thread (text)Self-text discussion posts with titlesPage
MicroblogShort-form posts (like Mastodon)Note
CommentReplies to threads or microblogsNote (with inReplyTo)
Private messageDirect messages between usersChatMessage (custom)

The dual content model is what distinguishes Kbin/Mbin from Lemmy. Threads work like Reddit posts (link or self-text with a title, displayed in a list). Microblogs work like Mastodon posts (short-form, displayed in a stream). Both coexist within each magazine.

Voting

  • Upvote — positive engagement, federated as Like activity
  • Downvote ("Reduce") — negative engagement, local only — does NOT federate
  • Boost — reshare/reblog, federated as Announce activity

The non-federation of downvotes is a critical interoperability detail. Lemmy federates downvotes via Dislike; Kbin/Mbin does not send them. Downvotes from Kbin/Mbin users are only visible on the local instance.

Reputation

Users accumulate reputation points from boosts and favourites on their content. Reputation is cosmetic only — visible on profile pages but has no functional effect (does not gate features or permissions).

Content Organization

  • Follow magazines, users, or entire domains
  • Block users, magazines, or domains
  • Content categorized by tags and labels
  • RSS feeds for threads, microblogs, or combined

3. ActivityPub Implementation

Actor Types

ActorTypePathPurpose
InstanceApplication/i/actorServer-level actor, signs requests, inbox/outbox
UserPerson/u/usernameIndividual accounts with followers/following
MagazineGroup/m/nameCommunity container, announces user activities

JSON-LD Context

The @context resolves to ActivityStreams, W3C security vocabulary, and custom namespaces including ostatus, schema.org, Mastodon extensions (toot:), PeerTube extensions, and Lemmy extensions.

Magazine (Group) Federation

Magazines use the same Group actor Announce relay pattern as Lemmy communities. When a user creates a thread in a magazine, the magazine's Group actor wraps the activity in an Announce and distributes it to all followers:

User creates thread → Create{Page} sent to Magazine
Magazine wraps → Announce{Create{Page}} sent to all followers
Remote instances receive Announce → display thread in magazine

This means subscribing to a magazine is a Follow sent to the Group actor. The Group actor then relays all content via Announce.

Activities Reference

ActivityPurpose
FollowSubscribe to user or magazine
Accept / RejectFollow request responses
CreateCreate threads, microblogs, comments
UpdateEdit content
DeleteRemove content
LikeUpvote (no Dislike — downvotes are local only)
AnnounceBoost/reshare; also magazine relay wrapping
UndoReverse Like, Follow, or Announce
BlockBan user (optional expiration timestamp, magazine-level or instance-level)
FlagReport content (sent to magazine moderators' instances only)
Add / RemoveModerator assignment, thread pinning
LockLock threads/microblogs to prevent responses (Mbin)

Content Object Wire Format

Thread (Page):

{
  "type": "Page",
  "id": "https://instance.example/m/magazine/t/12345",
  "attributedTo": "https://instance.example/u/alice",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://instance.example/m/magazine/followers"],
  "name": "Thread title",
  "content": "<p>HTML body</p>",
  "mediaType": "text/html",
  "source": {
    "content": "Markdown body",
    "mediaType": "text/markdown"
  },
  "inReplyTo": null,
  "sensitive": false,
  "stickied": false,
  "commentsEnabled": true
}

Microblog (Note):

{
  "type": "Note",
  "id": "https://instance.example/m/magazine/p/67890",
  "attributedTo": "https://instance.example/u/alice",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "content": "<p>Short-form post content</p>",
  "source": {
    "content": "Short-form post content",
    "mediaType": "text/markdown"
  },
  "tag": [
    {"type": "Hashtag", "name": "#fediverse"}
  ]
}

Comment (Note with inReplyTo):

{
  "type": "Note",
  "id": "https://instance.example/m/magazine/t/12345/-/comment/99",
  "attributedTo": "https://instance.example/u/bob",
  "inReplyTo": "https://instance.example/m/magazine/t/12345",
  "content": "<p>Reply text</p>",
  "source": {
    "content": "Reply text",
    "mediaType": "text/markdown"
  }
}

Key Federation Details

  • Downvotes do NOT federate — only Like (upvote) and Announce (boost) are sent. No Dislike activity.
  • Reports (Flag) are sent exclusively to instances housing the magazine's moderators.
  • Bans (Block) include optional expiration timestamps and specify scope (magazine-level vs instance-level).
  • Content includes focal point metadata and blurhash via Mastodon extensions.
  • Supports all ActivityPub Actor Types including Service for bot/robot accounts.
  • Accepts application/json headers across all ActivityPub endpoints (not just application/activity+json).
  • All content preserves markdown source alongside HTML rendering.
  • Multi-language content mapping supported.

4. API

REST API with Swagger/OpenAPI documentation at /api/docs on each instance.

Authentication

OAuth2-based:

  1. Register client: POST /api/client → returns identifier and secret
  2. Request token → returns Bearer token, expiration, refresh token
  3. Include Authorization: Bearer <token> on requests

Scopes

ScopeAccess
readRetrieve threads, view favorites
writeAll modification operations

5. Kbin vs Lemmy

AspectKbin/MbinLemmy
LanguagePHP (Symfony)Rust (Actix-web)
Content typesThreads + MicroblogsThreads only
Communities"Magazines""Communities"
AP object (posts)Page (threads) + Note (microblogs)Page only
Mastodon integrationStrong — microblog section shows Mastodon contentLimited
Downvote federationNo (local only)Yes (Dislike activity)
Mention federationBetter (Mbin)Weaker
PeerTube integrationDirect channel following (Mbin v1.7+)Limited
Third-party appsVery limitedMany (Jerboa, Thunder, Voyager)
GovernanceCommunity-driven (Mbin)Lemmy team (2 primary devs)
MaturityNewer (2023)Older (2019)

Interoperability

Both use Group actors for communities/magazines and Page objects for threads. They federate with each other: Lemmy communities appear as magazines in Kbin/Mbin and vice versa. Comments federate as Note objects with inReplyTo.

Key friction points:

  • Lemmy sends Dislike for downvotes; Kbin/Mbin ignores them (or had historical display issues)
  • Kbin/Mbin microblog Note posts appear as comments in Lemmy (since Lemmy only understands Page for top-level posts)
  • Mention federation works better from Mbin than from Lemmy

6. History and the Mbin Fork

Kbin Timeline

DateEvent
Dec 2022NLnet grant funding begins
Early 2023Project moves to Codeberg, development accelerates
Apr 2023kbin.social launches with a few hundred users
Jun 2023Reddit API crisis — kbin.social grows from 300 to 30,000+ users in one week
Jun 2023Emergency infrastructure: Fastly caching, Cloudflare, server upgrades
Late 2023Ernest begins pattern of weeks-to-months-long absences
Oct 2023Mbin fork created on GitHub
2024kbin.social increasingly unstable, Ernest cites medical issues
Jun 2024Ernest promises instance handover, then goes silent again
Sep 2024kbin.social effectively ceases operation
PresentKbin discontinued; Mbin is the active continuation

Mbin

Founded: October 12, 2023, by Melroy van den Berg.

Governance: Uses the Collective Code Construction Contract (C4) — no single-maintainer bottleneck. Multiple contributors have owner rights. Pull requests merged by any maintainer with community consensus on Matrix.

Key improvements over Kbin:

  1. Federation compatibility — major fixes to interoperability issues
  2. Performance and scaling — database optimizations, reduced background request overhead
  3. Security — up-to-date dependencies, security-first patching
  4. Documentation — hosted at docs.joinmbin.org
  5. Thread/microblog locking
  6. Discoverability and indexability settings
  7. PeerTube channel following (since v1.7)
  8. All ActivityPub Actor Types including Service for bots
  9. Combined thread creation form (unified link/text/photo)

Current version: v1.9.1 (February 2026). 35 releases, 4,477 commits, 35+ contributors.

Around 8–10 months after forking, Mbin stopped porting Kbin code and focused on purely original development.


7. The Threadiverse Ecosystem

The "Threadiverse" is the link-aggregation / threaded-discussion portion of the Fediverse. All platforms interoperate via ActivityPub using Group actors for communities and Page/Note objects for content.

SoftwareLanguageStatusDifferentiator
LemmyRustActiveMost mature (2019), most users
MbinPHPActiveThreads + microblogs combined
PieFedPythonActivePrivacy-focused voting, rapid development
SublinksJavaIn devLemmy-compatible alternative backend
LotideRustLimitedMinimal, lightweight

8. Instances

Kbin Instances

8 tracked, mostly inactive or migrated to Mbin. kbin.social (flagship) is defunct.

Mbin Instances

23 tracked, almost all with >98% recent uptime:

  • fedia.io — one of the largest, migrated from Kbin
  • kbin.run — created due to kbin.social instability
  • kbin.melroy.org — run by Mbin founder

9. Interoperability Notes for Implementers

  1. Threads arrive as Page objects — same as Lemmy. If your software handles Lemmy's Page posts, Kbin/Mbin threads will work the same way. Title is in name, body in content/source.

  2. Microblogs arrive as Note objects — these are short-form posts without titles, identical in structure to Mastodon posts. They originate from a magazine but look like standard microblog posts. Lemmy displays these as comments since it only understands Page for top-level content.

  3. No Dislike activity — Kbin/Mbin never sends downvotes over federation. If you receive a Like from a Kbin/Mbin instance, it's an upvote. You will never receive a Dislike. If your platform sends Dislike to a Kbin/Mbin instance, it may be ignored or cause display issues.

  4. Magazines are Group actors — follow a magazine by sending Follow to the Group actor at /m/name. The magazine relays all content via Announce, identical to Lemmy communities.

  5. ChatMessage for DMs — Kbin/Mbin uses a custom ChatMessage type for private messages, not standard Note with direct addressing. Other platforms may not understand this type.

  6. Accepts application/json — Kbin/Mbin accepts both application/activity+json and plain application/json on all ActivityPub endpoints. No need to worry about content-type strictness.

  7. Report routing — Flag activities are sent only to instances that host the magazine's moderators, not broadcast widely.

  8. Ban expiration — Block activities can include expiration timestamps and scope (magazine-level vs instance-level). Handle the expiration field if present.

  9. Reputation is cosmetic — Kbin/Mbin exposes reputation scores on user profiles, but these have no functional effect and should not be used for trust decisions.

  10. Mastodon content in magazines — Kbin/Mbin's microblog section displays Mastodon posts matching magazine hashtags. This means Mastodon Note objects may appear alongside native Kbin/Mbin content in magazine feeds.

Lemmy — Complete Reference

Overview

Lemmy is a self-hosted, federated social link aggregation and discussion forum — the Fediverse equivalent of Reddit. Created by Dessalines in February 2019, with Nutomic as co-creator and primary federation implementer. Built in Rust (Actix-web, Diesel ORM, PostgreSQL) with a TypeScript/Inferno.js frontend. Licensed AGPL-3.0.

Lemmy federates via ActivityPub. Its fundamental design choice is representing communities as Group actors that automatically relay all content via Announce activities, ensuring cross-instance consistency. It is the largest platform in the "Threadiverse" — the threaded discussion subset of the Fediverse.


1. Technology Stack

ComponentTechnology
Backend languageRust
Web frameworkActix-web (actor-model based)
ORMDiesel (type-safe)
DatabasePostgreSQL (R2D2 connection pooling)
Frontend languageTypeScript + CSS
Frontend frameworkInferno.js (React-compatible)
API clientlemmy-js-client
Image servicepictrs
DeploymentDocker, Ansible, ARM64/RPi supported
LicenseAGPL-3.0
Federation libraryactivitypub-federation-rust (standalone reusable crate)

2. ActivityPub Object Type Mapping

Lemmy ConceptActivityPub TypeNotes
CommunityGroupAutomated relay actor; Announces all content to followers
UserPersonCreates content, moderates, sends PMs
InstanceApplicationInstance-level actor at root path
PostPageMandatory title (name), optional URL and body
CommentNoteTree structure via inReplyTo
Private MessageChatMessageDirect user-to-user, no threading

Why Page for Posts?

Lemmy posts have a mandatory title (name), distinguishing them from Note (typically untitled) and Article (long-form). The Page type aligns with the concept of a web page with a URL, title, and optional body.


3. Communities as Group Actors

This is the fundamental architectural decision. Communities are Group actors with their own inboxes. Every post, comment, vote, and moderation action is received by the community and then Announced (wrapped and forwarded) to all followers across all instances.

Community Object

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://join-lemmy.org/context.json"
  ],
  "id": "https://enterprise.lemmy.ml/c/main",
  "type": "Group",
  "preferredUsername": "main",
  "name": "The Main Community",
  "summary": "<p>Welcome to the main community!</p>",
  "inbox": "https://enterprise.lemmy.ml/c/main/inbox",
  "outbox": "https://enterprise.lemmy.ml/c/main/outbox",
  "followers": "https://enterprise.lemmy.ml/c/main/followers",
  "featured": "https://enterprise.lemmy.ml/c/main/featured",
  "attributedTo": ["https://enterprise.lemmy.ml/u/picard"],
  "publicKey": {
    "id": "https://enterprise.lemmy.ml/c/main#main-key",
    "owner": "https://enterprise.lemmy.ml/c/main",
    "publicKeyPem": "..."
  }
}

Key Fields

FieldDescription
preferredUsernameMachine-readable community name
nameHuman-readable display name
summaryDescription / rules (HTML)
icon / imageAvatar / banner
outboxLimited to 20 latest posts
followersCount only (no individual references — privacy)
attributedToCreators and moderators
featuredPinned posts collection
postingRestrictedToModsWhether only mods can post

The Announce Relay Pattern

User on Instance A              Community on Instance B         Instance C subscriber
       |                               |                              |
       |--- Create{Page} -----------> |                              |
       |                               |--- Announce{Create{Page}} ->|
       |                               |                              |

All content activities (Create, Update, Delete, Like, Dislike, Remove, Lock) flow through the community Group actor, which wraps each in an Announce and broadcasts to all followers. This is how cross-instance consistency is maintained.


4. Post (Page) Object

{
  "type": "Page",
  "id": "https://enterprise.lemmy.ml/post/123",
  "attributedTo": "https://enterprise.lemmy.ml/u/riker",
  "to": [
    "https://www.w3.org/ns/activitystreams#Public",
    "https://ds9.lemmy.ml/c/main"
  ],
  "audience": "https://ds9.lemmy.ml/c/main",
  "name": "An interesting link",
  "content": "<p>Check this out!</p>",
  "source": {
    "content": "Check this out!",
    "mediaType": "text/markdown"
  },
  "attachment": [],
  "image": {},
  "commentsEnabled": true,
  "sensitive": false,
  "stickied": false,
  "published": "2024-01-15T12:00:00.000Z"
}
FieldDescription
nameTitle (mandatory — distinguishes Post from Comment)
contentBody text (HTML-rendered)
sourceOriginal markdown with mediaType: "text/markdown"
audienceTarget community (for routing)
attachmentLinks/images array
imageThumbnail
commentsEnabledPost lock status (custom extension)
sensitiveNSFW flag
stickiedPinned status (custom extension)
languageLanguage metadata (identifier + name)

5. Comment (Note) Object

{
  "type": "Note",
  "id": "https://enterprise.lemmy.ml/comment/95",
  "attributedTo": "https://enterprise.lemmy.ml/u/picard",
  "to": "https://enterprise.lemmy.ml/c/main",
  "content": "I agree with this take.",
  "source": {
    "content": "I agree with this take.",
    "mediaType": "text/markdown"
  },
  "inReplyTo": [
    "https://enterprise.lemmy.ml/post/38",
    "https://voyager.lemmy.ml/comment/73"
  ],
  "tag": [
    {
      "type": "Mention",
      "href": "https://voyager.lemmy.ml/u/janeway",
      "name": "@janeway@voyager.lemmy.ml"
    }
  ],
  "distinguished": false,
  "published": "2024-01-15T13:00:00.000Z"
}
FieldDescription
inReplyToParent post and/or parent comment (builds tree)
tagMention objects for user references
distinguishedMod-highlighted comment (custom extension)

6. Voting — Like and Dislike

Lemmy uses both Like (upvote) and Dislike (downvote) as first-class ActivityPub activities. This is unique among major Fediverse platforms — most only support Like.

Upvote

{
  "type": "Like",
  "actor": "https://enterprise.lemmy.ml/u/picard",
  "object": "https://enterprise.lemmy.ml/post/123",
  "audience": "https://ds9.lemmy.ml/c/main"
}

Downvote

{
  "type": "Dislike",
  "actor": "https://enterprise.lemmy.ml/u/worf",
  "object": "https://enterprise.lemmy.ml/post/123",
  "audience": "https://ds9.lemmy.ml/c/main"
}

Undo Vote

{
  "type": "Undo",
  "actor": "https://enterprise.lemmy.ml/u/picard",
  "object": {
    "type": "Like",
    "actor": "https://enterprise.lemmy.ml/u/picard",
    "object": "https://enterprise.lemmy.ml/post/123"
  }
}

All votes include audience for community routing and are wrapped in Announce by the community actor.

Privacy note: Every instance that subscribes to the community receives all vote activities — instance admins can see who voted on what.

Ranking Algorithms

AlgorithmDescription
Active (default)Score + latest comment time with decay
HotScore + post publication time with decay
ScaledHot with boost for less active communities
New / OldChronological
Most CommentsComment count
New CommentsForum-style bump on new reply
Top (Day/Week/Month/Year/All)Score within time window

Score = upvotes minus downvotes.


7. Full Activity Reference

User → Community

ActivityPurpose
FollowSubscribe to community
Undo{Follow}Unsubscribe
Create{Page}New post
Create{Note}New comment
Update{Page}Edit post
Update{Note}Edit comment
LikeUpvote
DislikeDownvote
Undo{Like} / Undo{Dislike}Remove vote
DeleteDelete own content
Undo{Delete}Restore deleted content
FlagReport content (with summary reason)

Community → Followers

ActivityPurpose
Accept{Follow}Automatic response to Follow
Announce{*}Rebroadcast any received activity to all followers

Moderation

ActivityPurpose
RemoveRemove content (with summary reason)
BlockBan user (with target scope, optional removeData, expires, summary)
LockPrevent new comments on post
Add to /moderatorsAdd moderator
Remove from /moderatorsRemove moderator
Add to /featuredPin post
Remove from /featuredUnpin post

User → User

ActivityPurpose
Create{ChatMessage}Send private message
Update{ChatMessage}Edit private message
Delete{ChatMessage}Delete private message

Instance-Level

  • Instance actor (type Application) at root path
  • Admins can remove any content instance-wide
  • Delete on user actor with removeData: true for account deletion

All activities are signed with RSA keys (key ID: {actor-url}#main-key).


8. JSON-LD Context and Custom Extensions

Required Context

[
  "https://join-lemmy.org/context.json",
  "https://www.w3.org/ns/activitystreams"
]

Namespace Prefixes

{
  "lemmy": "https://join-lemmy.org/ns#",
  "litepub": "http://litepub.social/ns#",
  "pt": "https://joinpeertube.org/ns#",
  "sc": "http://schema.org/"
}

Custom Properties

PropertyNamespaceUsed onDescription
stickiedlemmyPagePinned post
distinguishedlemmyNoteMod-highlighted comment
commentsEnabledlemmyPagePost lock status
postingRestrictedToModslemmyGroupRestricted posting
moderatorslemmyGroupModerator collection
languagelemmyPage, NoteLanguage metadata
sensitiveasPageNSFW flag
matrixUserIdlemmyPersonMatrix chat ID

Important: Lemmy parses ActivityPub objects as plain JSON, not as JSON-LD. The @context is included for other software's benefit but Lemmy does not perform JSON-LD expansion or compaction.


9. Federation Modes and Fetching

Federation Modes

ModeDescription
AllowlistOnly connect to specified instances
BlocklistBlock specific instances, open to all others
Open (default)Connect to any instance

Cascading Fetch Behavior

  • Community fetch: Also fetches most recent posts (not comments/votes)
  • Post fetch: Also fetches community and author
  • Comment fetch: Also fetches all parent comments, the post, authors, and the community

This ensures referential integrity across the federated network.


10. REST API

AspectDetails
Versionv3 (/api/v3/...)
AuthJWT (cookies or Authorization header since 0.19.0)
Image servicepictrs — upload, resize, format conversion
FeedsRSS/Atom at /feeds/ paths
Rate limitingIP-based (Docker: requires X-Forwarded-For header)
Client librarylemmy-js-client (official TypeScript)
OpenAPI specUnofficial: mv-gh.github.io/lemmy_openapi_spec/

11. Interoperability Issues

name vs preferredUsername (Historical)

Lemmy initially reversed these: name for usernames, preferredUsername for display names. This is the opposite of the ActivityPub spec and Mastodon. Nutomic acknowledged it as "completely counterintuitive."

JSON-LD Context Errors

Lemmy's @context had incorrect declarations:

  • "stickied": "as:stickied" — falsely implied stickied is in the ActivityStreams namespace
  • "pt" prefix expanded to Lemmy's domain instead of PeerTube's

Nutomic admitted: "the truth is that I don't really understand how [@context] works."

Mastodon Reply Propagation

Replies from Mastodon can fail to reach all Lemmy instances because Mastodon doesn't include the community inbox in its recipient lists. The community Group actor must be in the recipient list to Announce the reply.

Mastodon Vote Federation

Mastodon's Like targets personal inboxes, not shared inboxes. Lemmy processes the vote locally but does not Announce it, causing vote count inconsistencies across instances.

Strict Parsing

Lemmy is "really inflexible when it comes to incoming activities." Arrays vs single values, or object IDs vs full inlined objects, can cause parsing errors. The Lemmy protocol is described as "a strict subset of the ActivityPub Protocol."


12. The Threadiverse Ecosystem

"Threadiverse" refers to Reddit-style threaded discussion platforms in the Fediverse. All federate with each other via ActivityPub.

PlatformLanguageTerminologyNotes
LemmyRustCommunitiesLargest, most mature
MbinPHP (fork of Kbin)MagazinesAlso supports microblogs (Mastodon-style)
PieFedPythonTopicsRapid development, approaching feature-parity
SublinksJava—Drop-in Lemmy replacement (alpha)

Users on any Threadiverse platform can see and interact with content from any other, including subscribing to Lemmy communities from Mbin or PieFed.


13. Known Quirks for Implementers

  1. Posts use Page, not Note — if your server sends Note objects to a Lemmy community, they will be treated as comments, not posts. Posts require Page type with a name (title).

  2. Community must be in recipients — activities targeting a Lemmy community must include the community in to or cc. Sending only to the post author's inbox will not distribute the activity.

  3. audience field — Lemmy uses the audience property to route activities to the correct community. Include it for reliable delivery.

  4. Dislike is real — unlike most Fediverse platforms, Lemmy uses Dislike as a distinct activity type for downvotes, not Undo{Like}.

  5. source with markdown — Lemmy preserves original markdown in the source field with mediaType: "text/markdown". The content field contains the HTML-rendered version.

  6. Outbox is limited — community outbox only contains the 20 most recent posts. Comments and votes are not included.

  7. Followers collection is opaque — returns only a total count, not individual follower references (for privacy).

  8. No JSON-LD processing — Lemmy parses JSON directly. Do not rely on JSON-LD compaction/expansion when interoperating with Lemmy.

  9. ChatMessage for PMs — Lemmy uses the non-standard ChatMessage type for private messages rather than Note with direct addressing.

Loops — Complete Reference

Overview

Loops is a federated, open-source short-form video sharing platform — the Fediverse equivalent of TikTok/Vine. Its tagline is "Short videos. Your community. Your rules." Created by Daniel Supernault (aka Dansup), the Canadian developer also behind Pixelfed (the Fediverse Instagram alternative). Branded as "Loops by Pixelfed," it is a separate platform under the Pixelfed project umbrella.

Built on Laravel (PHP), Vue 3, and Tailwind CSS with a custom ActivityPub implementation. Licensed AGPL-3.0. ActivityPub federation entered beta on October 14, 2025. As of March 2026, the latest release is v1.0.0-beta.10.


1. Technology Stack

ComponentTechnology
BackendPHP / Laravel
FrontendVue 3 + TypeScript
CSSTailwind CSS
Build toolVite
Mobile appReact Native (Expo)
DeploymentDocker / Docker Compose
CDNFastly (Fast Forward program)
LicenseAGPL-3.0

Repositories

RepositoryURL
Serverhttps://github.com/joinloops/loops-server
Mobile apphttps://github.com/joinloops/loops-expo
API docshttps://docs.joinloops.org/

2. The Key Design Decision: Note, Not Video

The most important technical decision in Loops' federation: Loops uses Note objects with video attachments instead of Video objects for maximum cross-platform compatibility.

From Daniel Supernault:

"The fediverse is optimized for notes. Mastodon, Pleroma, Misskey — they all handle notes beautifully. By wrapping video content as notes with video attachments, loops federate seamlessly across the entire fediverse without requiring special handling."

"This pragmatic approach means loops show up properly everywhere, not just on platforms that specifically understand video objects. It's about meeting the fediverse where it is, not where we wish it would be."

What Gets Federated

When a loop is posted, the federation sends:

  • A Note object with rich video attachments
  • Multiple video encodings for different devices (where supported)
  • Generated thumbnails and preview images (where supported)
  • Captions and content warnings
  • All standard interaction capabilities (Like, Announce, Reply)

Why Not Video Objects?

PeerTube uses Video objects, which provide richer video-specific metadata. However, many Fediverse platforms (especially microblogging platforms like Mastodon, Misskey, Pleroma) either don't handle Video objects at all or display them with degraded UX. By using Note — the type every Fediverse platform handles natively — Loops videos appear correctly in timelines across the entire Fediverse without special handling.

Comparison

ApproachUsed byProsCons
Note + video attachmentLoopsUniversal compatibility; shows up in all timelinesLess video-specific metadata
Video objectPeerTubeRich metadata (duration, resolution, chapters)Many platforms ignore or poorly display Video type

3. Federation Implementation

Instance Actor and Shared Inbox

Every Loops instance has a server-level actor that handles:

  • Server-to-server authentication
  • Instance metadata exchange
  • Account deletions and relay subscriptions

A shared inbox is implemented for optimized delivery — remote instances send activities once to the shared inbox rather than per- follower, reducing network overhead as instances grow.

HTTP Signatures

Request signing with:

  • SHA-256 digests
  • Date header parsing (handling format variations across servers)
  • Non-standard port number handling
  • Every federated request is cryptographically signed

WebFinger Discovery

Standard WebFinger discovery for both individual users and the instance actor, enabling seamless follow operations across the Fediverse.

Federation-Aware Comments

Loops implements a graph-walking validator that traces reply chains:

  • Top-level Note objects from remote servers are rejected — Loops is for videos only, not microblog posts
  • Replies to videos create Comment objects
  • Replies to comments become CommentReply objects with correct parent relationships
  • This enables nested conversations that work across platforms

This validator is important for interoperability: when a Mastodon user replies to a loop, the reply is accepted as a Comment. But if a Mastodon user tries to create a top-level post that arrives at a Loops instance, it is rejected.

What Works in Federation Beta

FeatureStatus
Follow any ActivityPub userWorking
Be followed from Mastodon/Pixelfed/etcWorking
Cross-platform commentsWorking
Cross-platform likesWorking
Share/Announce to followersWorking
Federated notificationsWorking
Multi-instance video distributionWorking
Account migration with follower transferPlanned

Federation Configuration

Federation is opt-in during beta for self-hosted instances:

  • Enable in instance settings
  • HTTPS required
  • Configure domain properly
  • Allocate storage for remote media caching
  • Documented in FEDERATION.md in the repository

4. Features

Available Now

  • Vertical swipe short-video feed
  • Following feed (chronological) and For You feed (algorithmic, powered by engagement/hashtags/social graph)
  • Videos up to 3 minutes (originally 30 seconds, extended over time)
  • In-app camera with multi-lens switching and caption editor
  • Duets (collaborative video creation)
  • Nested/threaded comments with @mentions across the Fediverse
  • Like, share, boost/repost
  • Hashtag browsing and trending topics
  • Profile and video search
  • Pinned videos (up to 3)
  • Playlists & Collections
  • Favourites (private bookmarks)
  • Sound library
  • Full ActivityPub federation (beta)
  • Native iOS and Android apps
  • Admin dashboard
  • Public API with OpenAPI documentation

Roadmap (2026)

QuarterFeatures
Q1Advanced moderation, push notifications, multi-account, stitches
Q2Creator analytics, AR filters, collaborative moderation, accessibility
Q3Embeddable player, account migration, live streaming, video editor
Q4Challenges, monetization options

5. Loops vs PeerTube

AspectLoopsPeerTube
FocusShort-form vertical video (TikTok/Vine)Long-form video (YouTube)
Video lengthUp to 3 minutesNo practical limit
UIMobile-first vertical swipeWeb-first video library
DiscoveryFor You algorithmic feed + hashtagsFederated search, channels
AP object typeNote with video attachmentsVideo
Tech stackLaravel (PHP) + Vue.jsNode.js + Angular
P2P deliveryNoYes (WebRTC)
Live streamingPlanned Q3 2026Yes
MaturityBeta (v1.0.0-beta.10)Stable (v6+, since 2018)

Loops and PeerTube are complementary, not competing — they target fundamentally different video use cases. PeerTube is for long-form content hosting (channels, playlists, educational videos). Loops is for short-form social video (trends, creativity, casual sharing).


6. Interoperability Notes for Implementers

  1. Loops videos arrive as Note objects — if your software handles Note with video attachments, Loops content will display correctly in timelines. No special Video type handling needed.

  2. Replying to a Loop — send a standard Note reply with inReplyTo pointing to the loop's Note ID. Loops will accept it as a Comment.

  3. Top-level Notes are rejected — Loops only accepts video content for top-level posts. If a Mastodon user mentions a Loops user in a standalone post (not a reply), Loops will not ingest it as a post.

  4. Like and Announce work normally — standard Like and Announce activities targeting a loop's Note ID work as expected.

  5. Video stays on origin server — when a loop federates, remote instances receive the Note metadata but the video file is served from the original Loops instance. This reduces storage requirements for remote instances but depends on the origin server's availability.

  6. Multiple encodings — Loops may include multiple video file attachments (different resolutions/encodings) in the Note object. Consumers should select the appropriate encoding for their display context.


7. API

Loops provides a full public REST API (OpenAPI spec v1.0.0):

  • OAuth authentication with 2FA support
  • Video upload and management
  • Duets
  • Playlists and collections
  • Explore/trending endpoints
  • For You feed with impression tracking
  • Full-text search
  • Privacy controls
  • 25+ language support
  • AI content detection flags
  • Alt text and content sensitivity marking

Documentation: https://docs.joinloops.org/


8. Known Considerations

  • Beta federation: ActivityPub support is in beta (since October 2025). Some edge cases with remote platforms may still need work.
  • Opt-in federation: Self-hosted instances must explicitly enable federation in settings during the beta period.
  • Video bandwidth: Short-form video demands significant bandwidth and storage. Instance operators should plan for CDN/object storage costs. Loops benefits from Fastly Fast Forward sponsorship for its premiere instance.
  • No monetization yet: Creator monetization features are planned for Q4 2026. This may affect creator adoption in the near term.
  • Recommendation algorithm limitations: The "For You" feed uses engagement, hashtags, and social graph signals, but federated privacy constraints limit the data available compared to centralized platforms like TikTok.

Mastodon -- Complete Federation Reference

Overview

Mastodon is a free, open-source, decentralized microblogging platform -- the dominant software in the Fediverse and the de facto reference implementation for ActivityPub social networking. Created by Eugen Rochko (Gargron) in 2016. Built in Ruby on Rails with a PostgreSQL database, Redis for caching/queues, and a React.js frontend. Licensed AGPL-3.0.

Mastodon federates via ActivityPub (server-to-server). Because of its dominance, Mastodon's specific implementation choices have become de facto standards that other Fediverse software must accommodate, even when those choices deviate from or extend the ActivityPub specification.


1. JSON-LD @context Structure

Mastodon's @context is a three-element JSON array:

[
  "https://www.w3.org/ns/activitystreams",
  "https://w3id.org/security/v1",
  {
    "manuallyApprovesFollowers": "as:manuallyApprovesFollowers",
    "toot": "http://joinmastodon.org/ns#",
    "featured": { "@id": "toot:featured", "@type": "@id" },
    "featuredTags": { "@id": "toot:featuredTags", "@type": "@id" },
    "alsoKnownAs": { "@id": "as:alsoKnownAs", "@type": "@id" },
    "movedTo": { "@id": "as:movedTo", "@type": "@id" },
    "schema": "http://schema.org#",
    "PropertyValue": "schema:PropertyValue",
    "value": "schema:value",
    "discoverable": "toot:discoverable",
    "suspended": "toot:suspended",
    "memorial": "toot:memorial",
    "indexable": "toot:indexable",
    "attributionDomains": {
      "@id": "toot:attributionDomains",
      "@type": "@id"
    },
    "Hashtag": "as:Hashtag",
    "Emoji": "toot:Emoji",
    "sensitive": "as:sensitive",
    "votersCount": "toot:votersCount",
    "blurhash": "toot:blurhash",
    "focalPoint": { "@container": "@list", "@id": "toot:focalPoint" }
  }
]

Namespace Definitions

PrefixURINotes
as:https://www.w3.org/ns/activitystreams#Standard ActivityStreams
toot:http://joinmastodon.org/ns#Mastodon-specific extensions
schema:http://schema.org#BUG: should be https://schema.org/ -- causes issues with strict JSON-LD processors
sec:From https://w3id.org/security/v1Public keys, signatures

Key toot: Namespace Terms

  • toot:Emoji -- custom emoji type
  • toot:featured -- pinned posts collection (@id, @type: @id)
  • toot:featuredTags -- featured hashtags collection
  • toot:discoverable -- boolean, whether to list in directory
  • toot:indexable -- boolean, consent for search indexing (FEP-5feb)
  • toot:suspended -- boolean, account suspension status
  • toot:memorial -- boolean, memorial/deceased account
  • toot:votersCount -- poll total voter count
  • toot:blurhash -- BlurHash string for media placeholders
  • toot:focalPoint -- [x, y] coordinates for image cropping
  • toot:attributionDomains -- domains allowed to use fediverse:creator (since 4.3)

Key as: Extended Terms

  • as:Hashtag -- hashtag tag type
  • as:manuallyApprovesFollowers -- locked account flag
  • as:movedTo -- account migration target
  • as:sensitive -- content warning flag
  • as:alsoKnownAs -- account aliases for migration

Key schema: Terms

  • schema:PropertyValue -- profile metadata field type
  • schema:value -- profile metadata field value

Gotcha: The schema: prefix maps to http://schema.org# (with hash, no HTTPS). This is technically incorrect per schema.org's own context (https://schema.org/). Strict JSON-LD processors may fail to resolve these terms. Implementations should accept both forms.


2. Content-Type and Accept Headers

For Fetching ActivityPub Resources (GET)

Send the Accept header as:

Accept: application/activity+json, application/ld+json

Mastodon uses HTTP content negotiation. If the Accept header does not include an ActivityPub media type, Mastodon serves the HTML profile page instead of the JSON-LD representation.

Both of these are valid and equivalent:

  • application/activity+json
  • application/ld+json; profile="https://www.w3.org/ns/activitystreams"

For Sending Activities (POST to inbox)

Set the Content-Type header to:

Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"

Or equivalently:

Content-Type: application/activity+json

Gotcha: Some HTTP libraries default to application/json or application/x-www-form-urlencoded. Always set Content-Type explicitly. Send the request body as a raw JSON string, not form-encoded.


3. HTTP Signatures

Mastodon requires HTTP Signatures on all incoming POST requests and optionally on GET requests (when authorized fetch is enabled).

Algorithm

RSA-SHA256 (RSASSA-PKCS1-v1_5 with SHA-256) using the actor's RSA private key. The corresponding public key is published in the actor document under publicKey.

Signature Header Format

Signature: keyId="https://example.com/users/alice#main-key",
           headers="(request-target) host date digest",
           signature="<base64-encoded-signature>"

Required Signed Headers

For GET requests (when authorized fetch is enabled):

  • (request-target) -- the HTTP method and path (e.g., get /users/bob)
  • host -- target hostname
  • date -- RFC 2616 date (must be within clock skew tolerance)

For POST requests (always required):

  • (request-target)
  • host
  • date
  • digest -- mandatory for POST; Mastodon will reject POSTs without a signed Digest header

Digest Header

For POST requests, compute the SHA-256 hash of the request body:

Digest: SHA-256=<base64-encoded-sha256-hash-of-body>

The digest header name must appear in the headers parameter of the Signature header.

Key ID Format

The keyId is typically {actor_uri}#main-key. Mastodon dereferences this to fetch the actor document, extracts publicKey.publicKeyPem, and verifies the signature.


4. Authorized Fetch (Secure Mode)

Enabled by setting AUTHORIZED_FETCH=true (or LIMITED_FEDERATION_MODE=true) in the Mastodon environment.

What Changes

  • All GET requests to ActivityPub representations of public posts and profiles require HTTP signatures (normally these are anonymous)
  • Linked-Data Signatures are no longer generated for public posts
  • Suspended/blocked servers cannot fetch public content because they must identify themselves via signature
  • Server-level and user-level blocks become more effective

Limitations

  • Uses significantly more server resources (signature verification on every request)
  • Causes compatibility problems with older software that does not sign GET requests
  • Does not prevent determined adversaries -- a bad actor can set up a new instance to bypass blocks
  • Authorized fetch is circumventable by design; it is a friction mechanism, not a security boundary

Limited Federation Mode

LIMITED_FEDERATION_MODE=true is a superset of authorized fetch. It additionally restricts federation to manually approved servers only. Administrators must explicitly allowlist each domain.


5. Supported Object Types

First-Class Types

TypeMastodon Representation
NoteRegular status/toot
QuestionPoll status

Converted Types (Best-Effort)

These types are accepted but not given full treatment:

TypeHandling
ArticleUses content (or name if no content) as status text; appends url; summary becomes CW; icon becomes thumbnail
PageSame conversion logic as Article
ImageSame conversion logic
AudioSame conversion logic
VideoSame conversion logic
EventSame conversion logic

Critical gotcha: Article objects are not rendered with their full HTML content the way Note objects are. The content is used to generate status text, but formatting, structure, and richness are lost. Many platforms (WordPress, WriteFreely, Ghost) send Article objects that display poorly on Mastodon. Some platforms have switched to sending Note instead for better Mastodon compatibility.


6. Poll Implementation (Question/Answer)

Mastodon represents polls as Question objects (used as an Object type, not as an IntransitiveActivity). Polls are wrapped in Create activities like normal statuses.

Poll Structure

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://example.com/users/alice/statuses/12345",
  "type": "Question",
  "content": "<p>What is your favorite color?</p>",
  "published": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-02T00:00:00Z",
  "oneOf": [
    {
      "type": "Note",
      "name": "Red",
      "replies": { "type": "Collection", "totalItems": 42 }
    },
    {
      "type": "Note",
      "name": "Blue",
      "replies": { "type": "Collection", "totalItems": 58 }
    }
  ],
  "toot:votersCount": 100
}

Key Properties

  • oneOf -- array of options for single-choice polls
  • anyOf -- array of options for multiple-choice polls
  • Each option: type: "Note", name: "<option text>", replies.totalItems: <vote count>
  • Options have no id property
  • endTime -- ISO 8601 timestamp when voting closes
  • closed -- ISO 8601 timestamp when voting actually closed (may differ from endTime)
  • votersCount (toot:votersCount) -- total number of unique voters

Voting Mechanism

Votes are sent as Create activities where the object is a Note with:

  • name exactly matching the poll option's name
  • inReplyTo pointing to the Question's id
  • to addressing the poll author

For multiple-choice polls, Mastodon sends separate Create activities for each selected option from the same voter.

Poll Updates

Poll results are updated via Update activities on the Question object. Remote instances can re-fetch the poll to get current vote counts.


7. Edit / Update Activities

Mastodon has supported editing statuses since version 3.5.0 (March 2022).

How It Works

  • An Update activity is sent with the full updated object as object
  • The updated timestamp on the object signals that this is an edit (not a first-time creation)
  • Receiving instances check: if a status with that id already exists locally, the Update triggers an edit; otherwise it is treated as a new status
  • Mastodon's FetchRemoteStatusService automatically converts a Create to an Update when the status already exists in the local database

Edit History

  • Edit history is stored locally and viewable on the originating instance
  • Edit history is not federated in the ActivityPub representation (as of early 2026, there is an open issue requesting this: #23292)
  • The StatusEdit entity in the REST API exposes edit history

Limitations

  • Remote instances only see the latest version of a post
  • There is no standard way to fetch previous versions via ActivityPub

8. Announce (Boost) Activities

Outgoing Announces

When a user boosts a post, Mastodon sends:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://example.com/users/alice/statuses/67890/activity",
  "type": "Announce",
  "actor": "https://example.com/users/alice",
  "published": "2024-01-01T12:00:00Z",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://example.com/users/alice/followers",
          "https://remote.example/users/bob"],
  "object": "https://remote.example/users/bob/statuses/11111"
}

The object field is a URI string, not an inline object. The receiving instance must dereference (fetch) the URI to get the full status content.

Incoming Announces

Mastodon accepts both:

  • object as a URI string (standard pattern) -- fetches the original
  • object as an inline full object -- uses the embedded data

When processing an incoming Announce, Mastodon uses ActivityPub::FetchRemoteStatusService to retrieve the original status if needed.

Boost Counters

Statuses expose a shares collection:

  • shares.totalItems -- number of boosts received
  • Since Mastodon 4.3, like and boost counts are exposed in ActivityPub Note objects
  • Since Mastodon 4.4, favorite and boost counts match remote server values when available

Gotcha: Boost/like counts are inherently inconsistent across instances. Only the originating instance knows the true total. Other instances only see counts from their own users plus what has been federated to them.


9. Direct Messages (Mentions-Only Visibility)

Mastodon does not have a dedicated direct message ActivityPub type. "Direct messages" are simply Note objects with restricted addressing.

Addressing Rules for Direct Messages

{
  "type": "Note",
  "to": ["https://remote.example/users/bob"],
  "cc": [],
  "tag": [
    {
      "type": "Mention",
      "href": "https://remote.example/users/bob",
      "name": "@bob@remote.example"
    }
  ]
}

Requirements:

  • No as:Public (https://www.w3.org/ns/activitystreams#Public) in to or cc
  • No follower collection URI in to or cc
  • Only specific actor URIs in to
  • All actors in to/cc must have a corresponding Mention tag

Visibility Level Calculation

Mastodon calculates visibility from addressing, not from an explicit visibility field:

VisibilitytoccMention tags
publicas:Publicfollowers collection--
unlistedfollowers collectionas:Public--
privatefollowers collection(no as:Public)--
limitedspecific actors--Not all actors are Mentioned
directspecific actors--All actors are Mentioned

Gotcha: The distinction between limited and direct depends on whether all addressed actors have corresponding Mention tags. If you address actors in to without Mention tags, Mastodon treats it as limited (not direct).


10. Custom Emoji Federation

Custom emoji are represented as Emoji tags on objects:

{
  "type": "Note",
  "content": "<p>Hello :coolcat:</p>",
  "tag": [
    {
      "id": "https://example.com/emojis/coolcat",
      "type": "Emoji",
      "name": ":coolcat:",
      "icon": {
        "type": "Image",
        "mediaType": "image/png",
        "url": "https://example.com/system/custom_emojis/images/coolcat.png"
      }
    }
  ]
}

Properties

  • type: "Emoji" (from toot:Emoji)
  • name: shortcode including colons (e.g., :coolcat:)
  • icon.type: "Image"
  • icon.mediaType: MIME type (e.g., image/png)
  • icon.url: direct URL to the emoji image

Behavior

  • Mastodon scans name, summary, and content for shortcode substrings and links them to the emoji image
  • Custom emoji from remote instances are visible in federated posts
  • Administrators can see and copy emoji from federated instances
  • Emoji updates and deletions do not reliably federate
  • Custom emoji may not render in display names and bios in all contexts

11. HTML Sanitization

Mastodon sanitizes all incoming HTML to protect API client developers from unexpected markup.

Allowed Elements

a, abbr, audio, b, blockquote, br, code, div, em, i, img, li, ol, p,
pre, source, span, strong, ul, video

Allowed CSS Classes

mention, hashtag, ellipsis, invisible, h-*, p-*, u-*, dt-*, e-*

(Microformats2 classes are preserved.)

Behavior

  • Unsupported elements are stripped (content preserved, tags removed)
  • Unsupported attributes are stripped
  • Links (<a>) are kept only if the protocol is supported (http, https); other protocols are converted to plain text
  • Mentions and hashtags are represented as <a> tags with class="mention" or class="hashtag"

Gotcha: If your platform sends rich HTML (tables, headings, definition lists, details/summary, etc.), Mastodon will strip all of it. Only the plain text content inside those elements survives. Design your content to degrade gracefully.


12. Character Limits

Composing Limit

Mastodon's default composing limit is 500 characters. This is enforced client-side and in the REST API. Instance administrators can modify this by changing source code, but it is not a simple configuration option.

Receiving Limit

Mastodon accepts and displays posts longer than 500 characters from remote instances. The ActivityPub protocol has no character limit.

  • Long posts are displayed with automatic truncation and a "Read More" link in the web UI
  • Most Mastodon-compatible mobile clients also truncate with "Read More"
  • The post content is stored in full -- no data is lost

Hard Size Limits (FEDERATION.md)

PropertyLimitBehavior if exceeded
JSON-LD serialization1 MBActivity rejected
Username2048 charsActor rejected
Display name2048 charsTruncated
Profile note (bio)20 kBTruncated
Profile fields50 fieldsList truncated
Field name/value2047 charsTruncated
Poll options500List truncated
Custom emoji shortcode2048 charsRejected
Media descriptions (alt)1500 charsTruncated
Account aliases256List truncated
Attribution domains256List truncated

13. Thread Fetching and Reply Dereferencing

inReplyTo Resolution

When Mastodon encounters a status with an inReplyTo pointing to an unknown URI, it fetches the parent status from the remote server. This works recursively up the reply chain to build the thread context.

Same-Server Reply Fetching

Upon discovering a remote status, Mastodon fetches up to 5 replies from the same server as the original post. This helps fill in thread context but is limited in scope.

Reply Distribution Problem

Replies are sent to the parent post's instance but are not forwarded through follower networks automatically. This creates a fundamental gap:

  • If A posts, B replies, and C replies to B: A's instance may never see C's reply unless C explicitly mentions A
  • Each instance has an incomplete view of any conversation
  • Reply counts, like counts, and boost counts differ across instances

Fetch All Replies (4.4+)

Mastodon 4.4 introduced a "fetch all replies" feature (disabled by default). When triggered:

  • Paginates through the first layer of replies collections from the source server
  • Collects reply URIs
  • Launches background workers to fetch them

Mastodon 4.5 Improvements

  • Fetch all replies is enabled by default
  • Automatically checks for missing replies on page load and every 15 min
  • New AsyncRefresh API: the /api/v1/statuses/:id/context endpoint returns a Mastodon-Async-Refresh HTTP header when background fetch jobs are pending, allowing clients to poll for completion

14. NodeInfo Implementation

Discovery Endpoint

GET /.well-known/nodeinfo

Response:

{
  "links": [
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.0",
      "href": "https://mastodon.example/nodeinfo/2.0"
    }
  ]
}

NodeInfo 2.0 Response

GET /nodeinfo/2.0
{
  "version": "2.0",
  "software": {
    "name": "mastodon",
    "version": "4.5.0"
  },
  "protocols": ["activitypub"],
  "services": {
    "outbound": [],
    "inbound": []
  },
  "usage": {
    "users": {
      "total": 12345,
      "activeMonth": 5678,
      "activeHalfyear": 9012
    },
    "localPosts": 678901
  },
  "openRegistrations": true,
  "metadata": {
    "nodeName": "Example Mastodon",
    "nodeDescription": "A Mastodon instance"
  }
}

Note: software.name is always lowercase "mastodon". Use this to detect Mastodon instances programmatically.


15. Mastodon REST API Compatibility Layer

Mastodon's REST API has become a de facto standard. Many Fediverse platforms implement it (partially or fully) to allow Mastodon client apps to work with them:

PlatformMastodon API Support
PleromaNear-complete, with Pleroma-specific extensions
AkkomaNear-complete (Pleroma fork), with additional extensions
GoToSocialWell-implemented, works with major Mastodon apps
FirefishPartial support (now discontinued)
SharkeyPartial support (Misskey fork)
PixelfedPartial support for photo-related endpoints
FriendicaPartial support

API Discovery Challenge

Different platforms support different subsets of the Mastodon API and add their own extensions. There is no standardized way to discover which endpoints a server supports. Client libraries like Megalodon abstract over platform differences.


16. Recent Version Changes (4.x Series)

Mastodon 4.3 (October 2024)

Federation-relevant changes:

  • attributionDomains: new toot: property for fediverse:creator author attribution on external articles
  • Like and boost counts now exposed in ActivityPub Note objects
  • summary field in non-Note objects treated as HTML (was plain text)
  • Grouped notifications in REST API
  • Numeric actor IDs: new users get numeric-based ActivityPub URIs (preparation for future account renaming)

Mastodon 4.4 (July 2025)

Federation-relevant changes:

  • Quote post display: incoming quote posts per FEP-044f rendered in web UI; new quote attribute on Status entity
  • RFC 9421 HTTP Message Signatures: experimental support for verification of incoming signatures (behind feature flag)
  • FASP (Fediverse Auxiliary Service Providers): initial support for shared decentralized services (behind feature flag)
  • Fetch all replies: new backend feature to fetch missing remote replies (disabled by default)
  • Remote counts: favorite/boost counts match remote server values

Mastodon 4.5 (November 2025)

Federation-relevant changes:

  • Quote post authoring: users can compose quote posts; quoted_status_id API parameter; new quote states (blocked_account, blocked_domain, muted_account)
  • Fetch all replies enabled by default: automatic background fetching of missing conversation participants
  • AsyncRefresh API: Mastodon-Async-Refresh HTTP header for async background job status on context endpoint
  • RFC 9421 standard: experimental flag removed; incoming HTTP Message Signatures now verified by default

Supported FEPs

  • FEP-67ff: FEDERATION.md
  • FEP-f1d5: NodeInfo in Fediverse Software
  • FEP-8fcf: Followers collection synchronization
  • FEP-5feb: Search indexing consent (toot:indexable)
  • FEP-044f: Consent-respecting quote posts
  • FEP-3b86: Activity Intents (Follow, Announce, Like, Object intents)

17. Common Federation Gotchas

JSON-LD Issues

  1. schema.org base URI bug: Mastodon maps schema: to http://schema.org# instead of https://schema.org/. Strict JSON-LD processors will fail. Workaround: accept both forms.

  2. Context order matters: Some implementations are sensitive to the order of items in the @context array. Match Mastodon's order when possible.

  3. Unknown properties ignored: Mastodon silently ignores JSON-LD properties it does not understand. Your custom extensions will not cause errors but will not be processed.

Reply Propagation

  1. Incomplete threads: Mastodon instances have fundamentally incomplete views of conversations. Replies are not forwarded upstream. Only the instance where a post originated has the full picture.

  2. Counter inconsistency: Like counts, boost counts, and reply counts differ across instances. Never assume these numbers are authoritative on any instance except the originating one.

Content Handling

  1. Article objects degraded: Mastodon does not render Article objects with full fidelity. Long-form content platforms should consider sending Note for Mastodon compatibility or accept that their content will be reduced to plain text + URL.

  2. HTML stripped aggressively: Tables, headings, definition lists, details/summary, horizontal rules, and other block-level elements are stripped. Only a minimal subset of HTML survives.

  3. Hashtag/mention encoding: When a mention is present, hashtags in the Note activity can sometimes be replaced with mentions during federation delivery (the object itself retains correct tags when fetched directly).

Protocol Behavior

  1. Block activity sent S2S: Mastodon sends Block activities server-to-server when a user blocks a remote account, even though the ActivityPub spec defines Block for client-to-server only. Your implementation should handle incoming Block activities gracefully.

  2. Linked-Data Signatures disabled in secure mode: When AUTHORIZED_FETCH=true, Mastodon stops generating LD-Signatures on public posts. Implementations that rely on LD-Signatures for relay forwarding will break.

  3. Clock skew sensitivity: HTTP signature verification checks the Date header. If your server's clock is significantly off, signatures will be rejected.

Performance

  1. Link preview DDoS effect: Every instance that receives a post with a URL will independently fetch the link preview (OpenGraph data). A post that goes viral can cause hundreds of concurrent requests to the linked website.

  2. Inbox forwarding: Mastodon does not forward activities through inboxes the way the AP spec describes. Replies to your posts from third-party servers may never reach followers who are not on the replier's server.


18. WebFinger

Mastodon requires WebFinger for user discovery. The endpoint:

GET https://example.com/.well-known/webfinger?resource=acct:alice@example.com

Must return a JRD document with at minimum:

  • subject: the acct: URI
  • links: array including a link with rel: "self", type: "application/activity+json", and href pointing to the actor URI

Mastodon uses username@domain as the canonical user identifier. The WebFinger lookup is fundamental to Mastodon's database design: every remote actor is stored with a username and domain pair resolved via WebFinger.


19. Actor Structure

Mastodon actors are Person type (or Application for the instance actor, Service for bot/automated accounts). Key properties:

  • preferredUsername -- the local username (before the @)
  • name -- display name
  • summary -- bio (HTML)
  • url -- profile page URL (HTML)
  • inbox -- ActivityPub inbox endpoint
  • outbox -- ActivityPub outbox endpoint
  • followers -- followers collection URI
  • following -- following collection URI
  • featured (toot:featured) -- pinned posts collection
  • featuredTags (toot:featuredTags) -- featured hashtags
  • publicKey -- RSA public key for HTTP signature verification
  • endpoints.sharedInbox -- shared inbox for efficient delivery
  • icon -- avatar image
  • image -- header/banner image
  • attachment -- array of schema:PropertyValue for profile fields
  • discoverable (toot:discoverable) -- directory listing consent
  • indexable (toot:indexable) -- search indexing consent
  • memorial (toot:memorial) -- deceased account flag
  • suspended (toot:suspended) -- suspension flag
  • manuallyApprovesFollowers -- locked account
  • movedTo -- migration target actor URI
  • alsoKnownAs -- array of aliases (for migration verification)
  • attributionDomains (toot:attributionDomains) -- fediverse:creator domains

20. Supported Activities (Inbox Processing)

ActivityObject TypeMastodon Behavior
CreateNoteCreates a new status
CreateQuestionCreates a poll status
CreateOtherBest-effort conversion to status
UpdateNote/QuestionEdits status (if updated present, since 3.5)
UpdatePersonUpdates remote actor profile
DeleteNoteDeletes remote status locally
DeletePersonRemoves remote actor and content
AnnounceStatus URICreates a boost
LikeStatus URICreates a favorite
FollowActor URISends follow request
AcceptFollowConfirms follow relationship
RejectFollowRejects follow request
UndoFollowUnfollows
UndoLikeRemoves favorite
UndoAnnounceRemoves boost
UndoBlockRemoves block
BlockActor URIRecords block (non-standard S2S use)
FlagActor + objectsReports content/user to moderators
MoveActor URITriggers account migration
AddStatus to featuredPins a status
RemoveStatus from featuredUnpins a status

Mbin — Complete Reference

Overview

Mbin is a federated content aggregator and microblogging platform for the Fediverse — a Reddit + Mastodon hybrid. It is the active community fork of Kbin, created by Melroy van den Berg on October 21, 2023 (first release v1.0.0 on October 30, 2023) after Kbin's sole developer Ernest Wisniewski became unable to maintain the project.

Mbin's key differentiator is its hybrid dual content model: it combines Reddit-style link aggregation (threads organized into magazines) and Mastodon-style microblogging (short-form posts) in a single platform. This enables significantly better Mastodon integration than Lemmy or PieFed.

Governed under the Collective Code Construction Contract (C4) — no single maintainer, consensus-based on Matrix, any maintainer can merge PRs. 35 releases, 4,477 commits, 30+ contributors as of early 2026. Licensed AGPL-3.0. Built with PHP 8.3+/Symfony 7.4/PostgreSQL.


1. Technology Stack

ComponentTechnology
BackendPHP 8.3+ (8.4 recommended)
FrameworkSymfony 7.4.x
ORMDoctrine 2.19.6
DatabasePostgreSQL (14–18)
Message queueRabbitMQ (with optional AMQProxy for connection pooling)
CacheRedis / Valkey / KeyDB
Real-timeMercure (optional, server-sent events)
FrontendTwig templates (9.4%), SCSS (2.5%), JavaScript (1.6%)
BundlerWebpack
Web serverNginx, Apache, or Caddy
Image processingGD with blurhash support
Object storageLocal filesystem or S3 (AWS, MinIO, Ceph)
DeploymentDocker (Debian Trixie base) or bare metal
LicenseAGPL-3.0
DocumentationDocusaurus (docs.joinmbin.org)

Language Breakdown

  • PHP: 86.3%
  • Twig: 9.4%
  • SCSS: 2.5%
  • JavaScript: 1.6%

Key Dependencies

  • Symfony 7.4 (framework-bundle, security-bundle, twig-bundle, messenger)
  • Doctrine ORM + Migrations
  • OAuth2 providers: Facebook, GitHub, Google, Keycloak, Discord, Azure
  • TOTP-based two-factor authentication
  • AWS S3 SDK, blurhash, web push notifications, JWT via phpseclib
  • swagger-php for API documentation
  • PHPUnit + Paratest (parallel testing), PHPStan (static analysis)

2. Content Model

Magazines

The primary organizational unit — equivalent to subreddits (Reddit), communities (Lemmy), or topics (PieFed). Any registered user can create a magazine and automatically becomes its owner. Magazines are represented as ActivityPub Group actors at /m/name.

The Hybrid Dual Content Model

This is Mbin's defining feature. Two content types coexist within each magazine:

TypeDescriptionAP ObjectEntity Class
Thread (Entry)Links, articles, discussion posts with titlesPageEntry + EntryComment
Microblog (Post)Short-form posts (like Mastodon)NotePost + PostComment
CommentReplies to threads or microblogsNote (with inReplyTo)EntryComment or PostComment
Private messageDirect messages between usersChatMessage—

Why this matters for federation: Lemmy and PieFed only see Mastodon posts that users intentionally tag to appear on the Threadiverse. Mbin's microblog section can follow Mastodon users directly, display their posts in the microblog view, and federate mentions bidirectionally. This makes Mbin the strongest Threadiverse bridge to the microblogging Fediverse.

Navigation Structure

The UI reflects the hybrid model with tabs: Combined, Threads, Microblog, People, Magazines. The combined view (v1.9.0+) shows threads and microblogs together as the default homepage.

Voting and Boosting

  • Upvote — federated as Like activity (equivalent to Mastodon favourite)
  • Downvote — federated as Dislike activity (historically had federation issues inherited from Kbin)
  • Boost — federated as Announce activity (separate from voting)

Critical difference from Lemmy: In Mbin, boosting and voting are separate functions. In Lemmy, upvoting a post effectively boosts it. In Mbin, you can upvote without boosting and vice versa.

  • Upvotes and boosts are public (visible to everyone)
  • Downvotes are NOT public (to prevent harassment)
  • Boosting elevates a post to the top of "Active" list and adds points for the "Hot" section

Entity classes: Vote, EntryVote, EntryCommentVote, PostVote, PostCommentVote. Favourites are separate: Favourite, EntryFavourite, EntryCommentFavourite, PostFavourite, PostCommentFavourite.


3. ActivityPub Implementation

Actor Types

ActorTypePathPurpose
InstanceApplication/i/actor and /Server-level actor, signs requests, inbox/outbox
UserPerson/u/usernameIndividual accounts with followers/following, discoverable/indexable flags
MagazineGroup/m/nameCommunity container, announces user activities, moderator attribution

JSON-LD Context

All payloads include a @context resolving to https://instance.example/contexts which maps multiple namespaces:

  • ActivityStreams (https://www.w3.org/ns/activitystreams)
  • W3C Security vocabulary
  • ostatus
  • schema.org
  • toot (Mastodon extensions)
  • pt (PeerTube extensions)
  • lemmy (Lemmy extensions)

Discovery Protocols

ProtocolEndpointSource File
WebFinger/.well-known/webfingerWebFingerController.php + Service/ActivityPub/Webfinger/
NodeInfo/.well-known/nodeinfoNodeInfoController.php
Host-Meta/.well-known/host-metaHostMetaController.php

Shared Inbox

/f/inbox for instance-wide activity delivery.

HTTP Signatures

  • Implementation: src/Service/ActivityPub/HttpSignature.php
  • Validation: src/Service/ActivityPub/SignatureValidator.php
  • Key generation: src/Service/ActivityPub/KeysGenerator.php
  • Private key rotation via CLI: mbin:user:private-keys:rotate
  • After rotation, other instances take up to 24 hours to update stored keys

4. ActivityPub Object Types and Wire Format

Thread (Page)

{
  "type": "Page",
  "id": "https://instance.example/m/magazine/t/12345",
  "attributedTo": "https://instance.example/u/alice",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://instance.example/m/magazine/followers"],
  "audience": "https://instance.example/m/magazine",
  "name": "Thread title",
  "content": "<p>HTML body</p>",
  "mediaType": "text/html",
  "source": {
    "content": "Markdown body",
    "mediaType": "text/markdown"
  },
  "inReplyTo": null,
  "sensitive": false,
  "stickied": false,
  "commentsEnabled": true,
  "tag": [
    {"type": "Hashtag", "name": "#fediverse", "href": "https://instance.example/tag/fediverse"}
  ]
}

Microblog (Note)

{
  "type": "Note",
  "id": "https://instance.example/m/magazine/p/67890",
  "attributedTo": "https://instance.example/u/alice",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://instance.example/m/magazine/followers"],
  "content": "<p>Short-form post content</p>",
  "source": {
    "content": "Short-form post content",
    "mediaType": "text/markdown"
  },
  "tag": [
    {"type": "Hashtag", "name": "#fediverse"}
  ]
}

Comment (Note with inReplyTo)

{
  "type": "Note",
  "id": "https://instance.example/m/magazine/t/12345/-/comment/99",
  "attributedTo": "https://instance.example/u/bob",
  "inReplyTo": "https://instance.example/m/magazine/t/12345",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://instance.example/m/magazine/followers"],
  "content": "<p>Reply text</p>",
  "source": {
    "content": "Reply text",
    "mediaType": "text/markdown"
  },
  "tag": [
    {"type": "Mention", "href": "https://instance.example/u/alice", "name": "@alice"}
  ]
}

Vote (Like/Dislike)

{
  "type": "Like",
  "id": "https://instance.example/u/alice/like/456",
  "actor": "https://instance.example/u/alice",
  "object": "https://other.example/m/magazine/t/12345",
  "to": ["https://other.example/m/magazine"]
}

Like activities use the magazine ID in the to field (changed in v1.9.1 from using the followers collection).

Collection Endpoints

CollectionTypeDescription
OutboxOrderedCollectionCreate activities, paginated with first
FollowersOrderedCollectionUsers: individual refs; Magazines: counts only
FollowingOrderedCollectionUsers only
ModeratorsOrderedCollectionNon-paginated list of moderator URIs
FeaturedOrderedCollectionNon-paginated pinned threads

5. Activity Reference

Content Activities

ActivityPurpose
CreateCreate threads, microblogs, comments, messages
UpdateEdit content or account profiles
DeleteRemove content/accounts, replaced with Tombstone; optional removeData flag
LockDisable comments on threads/microblogs

Social Activities

ActivityPurpose
FollowSubscribe to user or magazine
Accept / RejectFollow request responses (auto-sent on Follow receipt)
UndoReverse Follow, Like, Dislike, or Announce
LikeUpvote
DislikeDownvote
AnnounceBoost/reshare; also magazine relay wrapping

Moderation Activities

ActivityPurpose
BlockBan user from magazine or instance (optional expiration)
FlagReport content (distributed only to instances hosting magazine moderators)
Add / RemoveModerator assignment and thread pinning to target collections

Magazine Announcements

Magazines Announce user activities to followers. The full set of announced activities: Create, Update, Add, Remove, Announce, Delete, Like, Dislike, Flag, Lock. Flag announcements are restricted to instances hosting the magazine's moderators.

User creates thread → Create{Page} sent to Magazine
Magazine wraps      → Announce{Create{Page}} sent to all followers
Remote instances    → Receive Announce → display thread in magazine

6. Async Message Processing Architecture

Mbin uses Symfony Messenger with RabbitMQ (Redis fallback) for asynchronous processing of all federation messages.

Incoming Inbox Message Types (15)

ActivityMessage, AddMessage, AnnounceMessage, BlockMessage, ChainActivityMessage, CreateMessage, DeleteMessage, DislikeMessage, EntryPinMessage, FlagMessage, FollowMessage, LikeMessage, LockMessage, RemoveMessage, UpdateMessage

Outgoing Outbox Message Types (15)

AddMessage, AnnounceLikeMessage, AnnounceMessage, BlockMessage, CreateMessage, DeleteMessage, DeliverMessage, EntryPinMessage, FlagMessage, FollowMessage, GenericAnnounceMessage, LikeMessage, LockMessage, RemoveMessage, UpdateMessage

Worker Configuration

php bin/console messenger:consume scheduler_default old async \
  outbox deliver inbox resolve receive failed --time-limit=3600

Recommended: 6 Supervisor worker processes, running as www-data.

AMQProxy

Optional AMQP connection pooling proxy (port 5673) that reduces TCP connection overhead by reusing RabbitMQ channels.


7. Magazine (Group) Federation Details

Magazines are the core organizational unit and federate identically to Lemmy communities: as Group actors using the Announce relay pattern.

Magazine Features

  • Any user can create a magazine and becomes its owner
  • Owners appoint moderators with Add/Remove to /moderators collection
  • Custom CSS per magazine (local display only, does not federate)
  • Magazine banners compatible with Lemmy community banners (v1.9.0+)
  • Magazine tags — moderators set hashtags that route matching microblogs into the magazine
  • Pinned content via featured collection
  • Discoverable flag controls search visibility
  • Indexable flag controls robots.txt advisory

Magazine Rules Deprecation

The magazine rules field is deprecated — rules cannot be properly federated to other servers. The workaround appends rules to the magazine description with a ### Rules header.

Entity Classes

Magazine, MagazineBan, MagazineBlock, MagazineLog (15+ specialized subclasses), MagazineOwnershipRequest, MagazineSubscription, MagazineSubscriptionRequest, Moderator, ModeratorRequest


8. REST API

REST API with Swagger/OpenAPI documentation generated via swagger-php.

Authentication

OAuth2 with RSA key pair:

  • Private key: openssl genrsa -des3 -out ./config/oauth2/private.pem 4096
  • Environment variables: OAUTH_PRIVATE_KEY, OAUTH_PUBLIC_KEY, OAUTH_ENCRYPTION_KEY
  • External SSO via Facebook, GitHub, Google, Keycloak, Discord, Azure

API Resource Groups (12)

Bookmark, Combined, Domain, Entry, Instance, Magazine, Message, Notification, OAuth2, Post, Search, User

Key Endpoints

  • /api/instance/settings — instance configuration
  • /api/instance/ban, /api/instance/unban — instance-level bans
  • Thread and microblog locking endpoints (v1.9.1+)
  • Entry/post CRUD with image upload support

9. Moderation Tools

Magazine-Level

  • Owners appoint moderators
  • Moderators can: pin/unpin threads, ban/unban users, lock/unlock content, delete/restore content, add/remove other moderators
  • Public moderation logs with type filtering (v1.9.0+)
  • Moderator assignments federate via Add/Remove activities

Instance-Level

  • Global moderators view, approve, or deny account signups (MBIN_NEW_USERS_NEED_APPROVAL, default: false)
  • Federation allow list (MBIN_USE_FEDERATION_ALLOW_LIST, default: false)
  • Instance-wide user blocking via Block activities
  • Federated bans — both incoming and outgoing (v1.9.0+)

CLI Admin Commands

CommandPurpose
mbin:user:createCreate users with optional admin/moderator privileges
mbin:user:adminGrant/revoke admin privileges
mbin:user:deleteDelete user and notify fediverse
mbin:user:moderatorGrant/revoke global moderator
mbin:user:verifyActivate/deactivate users (bypasses email verification)
mbin:user:passwordReset passwords
mbin:user:private-keys:rotateRotate federation authentication keys
mbin:magazine:createCreate/remove/purge magazines
mbin:messages:remove_and_banSearch DMs, ban senders, remove messages
mbin:check:duplicates-users-magazinesFind/remove duplicate accounts
mbin:ap:actor:updateUpdate remote users and avatars
mbin:ap:importImport ActivityPub resources by URL

Anti-Abuse

  • Anubis DDoS protection integration (v1.9.0+)
  • robots.txt blocks for vote, boost, report, crosspost, and search paths
  • Per-user and per-magazine discoverable/indexable settings

10. Deployment

Hardware Requirements

ResourceMinimumRecommended
vCPU4 cores (≥2GHz)12 cores
RAM6 GB32 GB
Storage40 GB—

Docker Deployment

  • Pre-built image: ghcr.io/mbinorg/mbin
  • Base image: Debian Trixie, Node.js v24
  • Built-in Caddy web server for automatic HTTPS
  • Services: PHP app, Messenger worker, PostgreSQL, RabbitMQ, Valkey, Caddy
  • Volumes: caddy_config, caddy_data, media, messenger_logs, oauth, php_logs, postgres, rabbitmq_data, rabbitmq_logs

Bare Metal

  • OS: Debian 12+ or Ubuntu 22.04 LTS+
  • PHP-FPM: pm.max_children=70, pm.start_servers=10
  • PHP config: max_execution_time=60, upload_max_filesize=12M, memory_limit=512M
  • OPCache: opcache.memory_consumption=512, opcache.jit=1255, preload enabled
  • Node.js 22+ required for frontend asset building
  • Supervisor for worker process management
  • Installation root: /var/www/mbin

11. Codebase Structure

Top-Level src/ Directories (33)

ActivityPub/           Command/              Controller/
DTO/                   DataFixtures/         DoctrineExtensions/
Document/              Entity/ (106 classes) Enums/
Event/                 EventListener/        EventSubscriber/
Exception/             Factory/              Feed/
Form/                  Kernel.php            Markdown/
Message/               MessageHandler/       Middleware/
PageView/              Pagination/           Payloads/
Provider/              Repository/           Scheduler/
Schema/                Security/             Service/ (48 items)
Twig/                  Utils/                Validator/

ActivityPub Controllers (14 files + 2 subdirectories)

ContextsController, EntryCommentController, EntryController, HostMetaController, InstanceController, InstanceOutboxController, MessageController, NodeInfoController, ObjectController, PostCommentController, PostController, ReportController, SharedInboxController, WebFingerController + Magazine/ + User/

Service Layer Key Classes

ActivityPubManager, ApHttpClient, HttpSignature, KeysGenerator, SignatureValidator, Note, Page, MarkdownConverter, DeliverManager, EntryManager, PostManager, MagazineManager, UserManager, VoteManager, FavouriteManager, BookmarkManager, ReportManager, ReputationManager, TagManager, MentionManager, SearchManager, FeedManager, ImageManager


12. Mbin vs Lemmy

AspectMbinLemmy
LanguagePHP 8.3+ (Symfony)Rust (Actix-web)
Content typesThreads + MicroblogsThreads only
Communities"Magazines" (Group)"Communities" (Group)
AP objectsPage (threads) + Note (microblogs)Page only
Mastodon integrationStrong — microblog section shows Mastodon contentLimited
User followingYes — can follow individual accountsNo — communities only
Boost vs voteSeparate functionsCombined (upvote = boost)
Downvote federationDislike (historical issues)Dislike (reliable)
Mention federationStrong (bidirectional with Mastodon)Weaker
Third-party appsLimited (Interstellar)Many (Boost, Thunder, Voyager)
GovernanceC4 collective, multiple maintainers2 primary developers
MaturityNewer (Oct 2023)Older (Feb 2019)

Interoperability

Both use Group actors for communities/magazines and Page objects for threads. They federate with each other: Lemmy communities appear as magazines in Mbin and vice versa.

Key friction points:

  • Mbin microblog Note posts appear as comments in Lemmy (Lemmy only understands Page for top-level posts)
  • Lemmy combines upvoting and boosting; Mbin treats them separately
  • Magazine banners are compatible with Lemmy community banners (v1.9.0+)
  • Mbin's @context includes the lemmy namespace for compatibility

13. History and Governance

Kbin Background

Kbin was created by Ernest Wisniewski (Polish developer), with development starting January 2021 and kbin.social launching April 2023. During the Reddit API crisis (June 2023), kbin.social grew from ~300 to 30,000+ users in one week, eventually reaching 123,000+.

Ernest experienced compounding personal crises (divorce, surgery, full-time job) and began disappearing for weeks to months. Pull requests on Codeberg sat unmerged. kbin.social went offline permanently.

The Fork

Melroy van den Berg (Dutch software engineer, DevOps architect) announced the Mbin fork on October 21, 2023. His stated motivation: "I saw the project slowly dying over the past months, and I couldn't let this happen."

The name "Mbin" = "M" (Melroy) + "bin" (from kbin). Melroy acknowledged: "I know, I wasn't creative."

Within one week, the community had already shipped GUI improvements, backend fixes, security patches, and documentation. After ~8-10 months, Mbin stopped porting Kbin code entirely — all subsequent development is original work.

C4 Governance

The Collective Code Construction Contract (from ZeroMQ/Pieter Hintjens):

  • No single-maintainer bottleneck — multiple contributors hold org owner rights
  • All maintainers peer-review each other's code
  • PRs merged by any maintainer after consensus on Matrix
  • "Bad actors" removed by public discussion and majority agreement
  • Deliberately prevents the single-point-of-failure that killed Kbin

Release Timeline

VersionDateKey Changes
v1.0.0Oct 30, 2023First release
v1.7.0mid 2024PeerTube support, DMs, push notifications
v1.8.4Sep 7, 2024Security patch, dead instance handling
v1.9.0Dec 14, 2024Combined homepage, magazine banners, federated bans, Symfony 7
v1.9.1Feb 9, 2025Thread/microblog locking, RSS improvements, faster search

14. Instances and Ecosystem

~18 instances, ~8,172 total users, ~750 monthly active users.

InstanceURLUsersMAU
Fediafedia.io6,036488
kbin.earthkbin.earth770131
the/brain/binthebrainbin.org24534
GehirnEimergehirneimer.de13628

Fedia.io dominates with ~74% of all users (concentration risk).

Mobile Apps

Interstellar is the primary mobile client (Android, iOS, Linux, Windows) — functional but limited compared to Lemmy-specific apps. The Threadiverse primer recommends Mbin only for desktop browsing.

A unified TypeScript client (github.com/aeharding/threadiverse) is in development for Lemmy, PieFed, and Mbin.


15. Common Implementation Mistakes

  1. Sending Note objects to a magazine expecting thread display — Mbin uses Page for threads (entries) and Note for microblogs. A Note sent to a magazine appears in the microblog section, not as a thread. Use Page with a name (title) for thread-style posts.

  2. Ignoring the separate boost/vote model — Unlike Lemmy where upvoting boosts, Mbin treats Like (upvote) and Announce (boost) as independent actions. Implement both if you want full interoperability.

  3. Expecting downvotes to always federate — Mbin sends Dislike activities but historically had federation issues inherited from Kbin. Downvotes are not publicly visible on Mbin. Do not assume reliable Dislike delivery from older Mbin versions.

  4. Not including the magazine in activity recipients — Activities targeting a magazine must include the magazine Group actor in to or cc. The magazine must receive the activity to Announce it to followers.

  5. Assuming ChatMessage is standard — Mbin uses a custom ChatMessage type for private messages, not Note with direct addressing. Other platforms may not understand this type.

  6. Ignoring source with markdown — All content preserves original markdown in the source field alongside HTML in content. Prefer rendering from source if you want accurate markdown.

  7. Not handling both Page and Note from the same magazine — A single magazine may produce both Page (threads) and Note (microblogs) objects. Consuming software must handle both types from the same Group actor.

  8. Expecting Like activities to use followers collection in to — As of v1.9.1, Like/Dislike activities use the magazine ID in the to field instead of the followers collection.

  9. Treating magazine rules as a reliable field — The rules field is deprecated and cannot federate. Rules are embedded in the magazine description under a ### Rules header instead.

  10. Not accepting application/json content type — Mbin accepts both application/activity+json and plain application/json on all ActivityPub endpoints, and may send requests with application/json. Strict content-type checking will break interoperability.

Misskey — Complete Reference

Overview

Misskey is a free, open-source, decentralized microblogging platform — a feature-rich Japanese-origin Fediverse platform that predates many others. Created by syuilo (Eiji Shinoda) in 2014 as a BBS-style forum, it adopted ActivityPub in 2018. The name comes from the song "Brain Diver" by the band May'n. Licensed AGPL-3.0.

Misskey is explicitly not a Mastodon fork — it is "a project completely different from Mastodon or other alike projects." Its cultural DNA reflects Japanese social media preferences: emoji reactions as the primary engagement mechanism (not simple likes), rich visual formatting (MFM), integrated file management (Drive), and playful features like isCat mode and the mascot Ai (藍). Community members are called "Misskists."

As of late 2024: ~918,550 registered accounts, ~25,782 active users, 1,096+ instances. The flagship instance misskey.io is reportedly the second largest instance in the entire Fediverse. MisskeyHQ exists as a company entity, funded by donations and software licensing.


1. Technology Stack

ComponentTechnology
BackendNode.js with TypeScript
FrameworkNestJS (dependency injection)
DatabasePostgreSQL (TypeORM)
Cache / QueueRedis (ioredis) / BullMQ
FrontendVue.js 3 (Composition API, TypeScript)
Build toolVite
LicenseAGPL-3.0

Resource Footprint

Small instances: ~848 MB RAM with CPU bursts. A $10/month VPS suffices for small communities; $20/month for 15–50 users.

Repository

https://github.com/misskey-dev/misskey


2. ActivityPub Extensions

Misskey uses the JSON-LD namespace https://misskey-hub.net/ns# (prefix misskey). This is the most extensive set of custom ActivityPub extensions in the Fediverse ecosystem.

Extension Reference

PropertyOnDescription
_misskey_contentNoteDeprecated. MFM source text (equivalent to source property)
_misskey_summaryActorActor summary in MFM format
_misskey_quoteNoteID of quoted note. Compatible with fedibird:quoteUri and as:quoteUrl
_misskey_reactionLikeEmoji reaction type. Unicode emoji or :name: custom emoji string
_misskey_votesQuestion optionVote count (equivalent to replies.totalItems)
_misskey_talkNoteBoolean true marks note as a chat message
isCatActorBoolean — actor identifies as a cat (triggers visual effects)
_misskey_followedMessageActorCustom message on follow notification (since 2024.9.0-alpha.11)
_misskey_requireSigninToViewContentsActorForbids display to non-signed-in viewers
_misskey_makeNotesFollowersOnlyBeforeActorRestricts past notes to followers only. Value: Unix epoch ms (negative = relative)
_misskey_makeNotesHiddenBeforeActorHides past notes from all except author. Same value format
_misskey_licenseEmojiLicense metadata. Properties: freeText (string or null)

Emoji Reactions Wire Format

Misskey's emoji reactions are the most significant interoperability concern. When a user reacts with an emoji, Misskey sends a Like activity with _misskey_reaction set to the emoji:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {
      "misskey": "https://misskey-hub.net/ns#",
      "_misskey_reaction": "misskey:_misskey_reaction"
    }
  ],
  "type": "Like",
  "id": "https://misskey.example/likes/abc123",
  "actor": "https://misskey.example/users/alice",
  "object": "https://remote.example/notes/xyz",
  "_misskey_reaction": "👍",
  "content": "👍"
}

For custom emoji reactions:

{
  "type": "Like",
  "_misskey_reaction": ":blobcat:",
  "content": ":blobcat:",
  "tag": [
    {
      "type": "Emoji",
      "id": "https://misskey.example/emojis/blobcat",
      "name": ":blobcat:",
      "icon": {
        "type": "Image",
        "url": "https://misskey.example/files/blobcat.png"
      }
    }
  ]
}

Interoperability: Platforms that do not understand _misskey_reaction will treat these as standard Like activities (favourites). Custom emoji reactions are only visible to other Misskey-family software. The content field is also set to the reaction value as a fallback.

Quote Posts Wire Format

{
  "type": "Note",
  "id": "https://misskey.example/notes/abc123",
  "content": "<p>My thoughts on this</p>",
  "_misskey_quote": "https://remote.example/notes/original",
  "quoteUrl": "https://remote.example/notes/original"
}

Both _misskey_quote and quoteUrl are set for compatibility. Also recognized: https://fedibird.com/ns#quoteUri.


3. MFM (Misskey Flavored Markdown)

Proprietary markup language usable in notes, content warnings, usernames, and bios. General syntax: $[name.attribute1,attribute2=value content]

Text Formatting

  • Bold: **text**
  • Small: <small>text</small>
  • Center: <center>text</center>
  • Quotes: > text
  • Ruby: $[ruby text reading]
  • Links: [label](url)
  • Code: backticks (inline), triple backticks with language (blocks, 200+ languages via Shiki)

Visual Effects

SyntaxEffect
$[flip text]Horizontal/vertical flip
$[font.serif text]Font change (serif, monospace, cursive, fantasy)
$[blur text]Blur until hover
$[fg.color=hex text]Foreground color
$[bg.color=hex text]Background color
$[border.style=solid,width=4 text]Border (solid, dotted, dashed, double, groove, ridge, inset, outset)
$[position.x=0.8,y=0.5 text]Position shifting
$[rotate.deg=30 text]Rotation
$[scale.x=4,y=2 text]Scaling (also $[x2], $[x3], $[x4])

Animations

SyntaxEffect
$[jelly text]Jiggles
$[tada text]Celebration
$[jump text]Bouncing
$[bounce text]Elasticity
$[spin text]Rotation (modifiers: .left, .alternate, .x, .y)
$[shake text]Vibration
$[twitch text]Random twitching
$[rainbow text]Color cycling
$[sparkle text]Shimmer

All animations support .speed=5s for timing control.

Federation note: MFM is rendered as HTML when federating via ActivityPub. The _misskey_content (deprecated) and source properties carry the original MFM source. Non-Misskey platforms see plain HTML with animations and effects stripped.


4. Note System

Visibility Levels

LevelDescription
publicVisible to everyone, appears on all timelines
homeVisible to everyone but only appears on home timeline
followersOnly visible to followers
specifiedOnly visible to specified users (direct message)

Features

  • Content Warning (CW): summary field hides content behind a toggle
  • Renote: Boost/reblog (Announce activity)
  • Quote Renote: Boost with added commentary (_misskey_quote)
  • Polls: Question activity type with _misskey_votes for counts
  • Reactions: Full emoji reactions (see Section 2)
  • Mentions: @-mentions across the Fediverse
  • Hashtags: Standard Hashtag tag type

Timelines

TimelineContent
HomeNotes from followed users
LocalAll public notes from the instance
Social (Hybrid)Home + Local combined
GlobalAll known public notes including remote

5. Unique Features

Drive

Cloud storage system for managing uploaded files. Files can be organized into folders and reused across multiple notes without re-uploading. Each file retains metadata (type, size, hash). Drive capacity is configurable per-user by instance administrators via role policies.

Antennas

Customizable filtered feeds that collect notes matching set conditions (keywords, users, file attachments) in real time. Essentially continuous background searches. Antennas exclude the user's own posts.

Deck UI

Multi-column layout with side-by-side views for an information-dense interface. Users can arrange timeline columns, notification panels, and other widgets freely.

Channels

Topic-based note collections within an instance. Similar to forums or discussion threads organized by subject.

Pages

Static page creation system using MFM and custom emoji, enabling users to build content beyond notes.

Other Features

  • Clips — public/private categorized bookmarks
  • Plugins — extend web client functionality via AiScript
  • Themes — full client appearance customization
  • Widgets — small interactive dashboard displays
  • Webhooks — external service integration
  • Word mute / Thread mute — content filtering
  • Charts — server data visualization
  • Online status — activity indicators on profile icons
  • Share form — at /share path for social sharing buttons
  • Safe mode — disables custom CSS, plugins, themes
  • Embeds — embed notes and timelines on external websites
  • isCat mode — users identify as cats with visual effects in supporting clients

6. API

REST API

All endpoints use HTTP POST (not GET for reads):

POST /api/notes/create
POST /api/notes/show
POST /api/users/show
POST /api/following/create

Authentication via access tokens. SDK: misskey-js (TypeScript).

Streaming API

WebSocket-based with channel multiplexing:

{
  "type": "connect",
  "body": {
    "channel": "homeTimeline",
    "id": "arbitrary-unique-id"
  }
}

Available channels: globalTimeline, homeTimeline, hybridTimeline, localTimeline, main.

Multiple channels can be multiplexed on a single WebSocket connection using different IDs.


7. Fork Ecosystem

Misskey has the most extensive fork tree in the Fediverse. All forks federate with each other and the broader Fediverse.

Active Forks

ForkTypeKey Differentiators
SharkeySoft fork (tracks upstream)Federated note editing with history, Mastodon-compatible API + OAuth2, multi-platform import (Mastodon/Pleroma/Firefish/Twitter/Instagram/Facebook), GDPR data export, "Bubble" timeline, Argon2 hashing, multiple translation services
CherrypickSoft forkCompatible with Misskey client ecosystem
Meiskeyv11 forkBased on older Misskey v11

Discontinued / EOL Forks

ForkStatusNotes
Firefish (was Calckey)Discontinued 2024Added recommended timeline, account migration, mobile-optimized UI. Lead developer became absent
IceshrimpTransitioningJS version: security patches only. Iceshrimp.NET: complete C# rewrite (beta), Mastodon API support
FoundKeyEnd of LifeHard fork of v12, goal was removing bloat
CatodonDiscontinued Nov 2025Community-driven fork of Iceshrimp, created in reaction to Firefish governance failures

Fork Relationship

Misskey (syuilo, 2014–)
├── Sharkey (soft fork, ACTIVE)
├── Cherrypick (soft fork, ACTIVE)
├── Meiskey (v11 fork, ACTIVE)
├── FoundKey (v12 hard fork, EOL)
└── Calckey (2022) → Firefish (2023, DISCONTINUED)
    ├── Iceshrimp → Iceshrimp.NET (C# rewrite)
    └── Catodon (DISCONTINUED)

Pattern: Forks emerge from (a) feature gaps upstream won't fill, (b) governance/communication issues, or (c) architectural changes (Iceshrimp.NET's language rewrite).


8. Misskey vs Mastodon

AspectMisskeyMastodon
OriginJapan (2014)Germany (2016)
Character limitConfigurable per instance500 default
ReactionsFull emoji reactions (custom + Unicode)Favourites only
File managementBuilt-in DriveNo persistent storage
MarkupMFM (animations, colors, effects)Limited Markdown
ChannelsTopic-based communitiesNo
AntennasCustom filtered feedsNo equivalent
Resource usageLighter than MastodonHeavier
Mobile appsLimited (PWA, third-party)Official iOS/Android + many third-party
Post editingNot in core (Sharkey has it)Supported
User base~918k (mostly Japanese)~7.6M total

9. Interoperability Notes for Implementers

  1. Emoji reactions arrive as Like activities — check for _misskey_reaction to distinguish a specific emoji reaction from a generic favourite. If absent, treat as a standard Like. The content field also contains the reaction value.

  2. Custom emoji in reactions — when _misskey_reaction contains a :name: string, the tag array includes an Emoji object with the image URL. Display the custom emoji image if available, fall back to treating it as a Like.

  3. Quote posts — Misskey sends _misskey_quote and quoteUrl on Note objects. Also check for fedibird:quoteUri (Fedibird/Mastodon compatibility). Display as an embedded quote if your platform supports it.

  4. MFM content — notes from Misskey contain HTML in content (with MFM effects stripped) and optionally MFM source in the source property. Use the HTML for display; the MFM source is only useful if you want to re-render with a MFM parser (library: mfm-js).

  5. isCat property on actors — a boolean extension. Misskey-family clients show cat ears and modify text display for cat-mode users. Safe to ignore but do not strip when forwarding actor documents.

  6. Chat messages — notes with _misskey_talk: true are Misskey chat messages. They federate as normal Notes to non-Misskey platforms. Display as regular posts if your platform has no chat feature.

  7. All API endpoints use POST — unlike Mastodon's REST conventions, Misskey uses POST for everything including reads. If implementing a Misskey-compatible API, every endpoint must accept POST.

  8. Visibility level "home" — Misskey has a fourth visibility level (home) where notes are visible to everyone but excluded from the local and global timelines. This maps to ActivityPub to: followers, cc: Public (the inverse of Mastodon's "unlisted"). Handle carefully when federating.

  9. Poll vote counts — Misskey includes _misskey_votes on poll options. This is equivalent to replies.totalItems but may be more reliably present. Prefer _misskey_votes when available.

  10. Note content restrictions — the _misskey_makeNotesFollowersOnlyBefore and _misskey_makeNotesHiddenBefore properties on actors signal that historical content has access restrictions. Respect these when fetching older notes from Misskey actors.


10. Known Considerations

  • No post editing in core Misskey — users must delete and redraft. The Sharkey fork adds federated note editing with version history.
  • Cannot follow hashtags — use Antennas (keyword-filtered feeds) instead.
  • No official mobile apps — third-party options include SocialHub (iOS) and Milktea (Android). The web client supports PWA.
  • Antennas exclude personal posts from their results.
  • Mute functionality gaps regarding mentions.
  • No MRF equivalent for regex-based content filtering (unlike Pleroma/Akkoma).
  • November 2025 announcement about potentially replacing ActivityPub with "Misskey's own low-overhead federation system" — details unclear, impact on interoperability unknown.
  • Geographic registration restrictions on misskey.io — initially blocked Europeans (GDPR concerns), later restricted to Japanese users, Korea allowed since February 2026.
  • Recent security fixes — CVE-2026-28431, CVE-2026-28432, CVE-2026-28433 patched in version 2026.3.1.

NodeBB — Complete Reference

Overview

NodeBB is a modern, open-source forum software built on Node.js with native WebSocket real-time updates. Founded in 2014 by Julian Lam, Andrew Rodrigues, and Barış Soner Üşaklı in Toronto, Canada. Licensed GPL-3.0.

Starting with v4.0.0 (released January 20, 2025), NodeBB includes ActivityPub federation as a core feature — not a plugin. This makes NodeBB the first major traditional forum software to ship ActivityPub in its core. The implementation was funded by the NLNet Foundation (NGI Zero Core fund, approved August 2023).

NodeBB organizes content as forum topics (not ephemeral posts). Content is presented chronologically with active topics "bumped" to the top when receiving replies. This is fundamentally different from microblogging platforms — NodeBB brings the structured discussion forum paradigm into the Fediverse.


1. Technology Stack

ComponentTechnology
BackendNode.js
Real-timeWebSockets (Socket.IO)
DatabaseMongoDB (default), Redis, or PostgreSQL
FrontendServer-rendered templates + client-side JS
LicenseGPL-3.0

Database Architecture

NodeBB provides a unified database abstraction layer (hashes, sets, sorted sets, lists) that works identically across all three backends. Data is stored as key-value objects (e.g., user:<uid>).

Multi-database support: Sessions can be separated into a different database instance (e.g., Redis for sessions, MongoDB for data). Redis pub-sub is used for inter-process communication regardless of primary database, enabling horizontal scaling across multiple Node.js processes.

Plugin System

Hooks-based architecture with four hook types:

TypeBehavior
FiltersTake input, modify, return changed value
ActionsExecute side effects, return nothing
StaticLike actions but NodeBB waits for completion
ResponseReturn HTTP responses

Plugins can mount API routes at /api/v3/plugins. Widget system supports template-and-location based widget areas. Large npm-based plugin ecosystem (SSO, media embedding, advertising, emoji, push notifications, rich-text, galleries, etc.).


2. ActivityPub Implementation

Why Core, Not Plugin

ActivityPub required extensive architectural changes that couldn't be accomplished via a plugin. It was built directly into the NodeBB core.

Configuration

  • Global toggle: ACP > Settings > Federation (ActivityPub)
  • New v4 installs: federation enabled by default, all categories federate
  • Upgrades from v3: federation disabled by default (opt-in)
  • Per-category control: the "fediverse" pseudo-user is granted viewing/posting privileges on a per-category basis
  • Domain filtering: allow-list or deny-list modes

Development Timeline

DateMilestone
Mid-2023Julian conceives inter-NodeBB communication idea
Aug 2023NLNet Foundation funding approved
Jun 2024v4.0.0-alpha
Sep 2024v4.0.0-beta.1
Nov 2024RC1
Jan 20, 2025v4.0.0 stable
2025–2026Continued releases through v4.9.0+

3. Actor Types

ActorTypePathPurpose
UserPerson/u/usernameIndividual user accounts
CategoryGroup/category/<cid>Forum categories, Group Federation
InstanceApplication(instance-level)Server-level actor

Category as Group Actor (FEP-1b12)

Each category identifies itself as a Group actor. Categories:

  • Maintain follow relationships with other actors and remote users
  • Can follow other Group actors from different forums
  • Federate content via the Announce relay pattern
  • Have a unique handle — a "slugified" version of the category name (e.g., "Category About Cats" → category-about-cats)

When a user posts content (new topic or reply), the category wraps it in an Announce activity and distributes to all followers:

User creates post → Create{Note} sent to Category
Category wraps → Announce{Create{Note}} sent to all followers
Remote instances receive → display post in corresponding category

This is the same pattern used by Lemmy communities and Kbin/Mbin magazines. Remote users can follow a NodeBB category the same way they follow a Lemmy community.

The Uncategorized Pseudo-Category

Serves as a catch-all for manually discovered remote content (via URL paste into search). Content lands here automatically before admins move it to appropriate local categories. The Uncategorized category does NOT use the Announce pattern and has automated pruning.


4. Content Model and Conversational Context

Two-Level Hierarchy

NodeBB maps forum structure to ActivityPub using a two-level hierarchy:

Category (audience) → Topic (context) → Post
     Group actor        OrderedCollection    Note/Article

Every post carries both properties:

  • audience → points to the category (Group actor)
  • context → points to the topic (resolvable URL returning an OrderedCollection per FEP-7888)

Object Types

NodeBB ConceptAP ObjectNotes
Topiccontext (OrderedCollection)Resolvable collection of posts
Post / ReplyNote or ArticleWithin a context, with inReplyTo for threading
CategoryGroup actorUses audience property

NodeBB builds topics from incoming ActivityPub activities (Create, Question, Listen) and objects (Note, Article).

Context Resolution (FEP-7888)

When NodeBB encounters an object with a context property:

  1. Primary: Resolvable context — resolves the URL to retrieve a Collection, parses all objects, organizes them into a single topic. Supports synchronization headers for freshness verification.

  2. Fallback: Reply chain traversal — traverses inReplyTo chain upward to the root node, organizes chain objects into a topic.

Reply chain traversal has limitations:

  • If any object in the chain becomes unresolvable, the chain breaks
  • Only follows the direct reply path, missing sibling branches

Outboxes

User and category outboxes (v4.10.0+) return paginated OrderedCollection containing activities (Create, Like, etc.) with first, last, prev, next navigation.


5. FEP Support

NodeBB evaluates FEPs using four positions (mirroring Mozilla's Specification Positions): positive, neutral, defer, negative.

Implemented

FEPTitle
FEP-0151NodeInfo in Fediverse Software
FEP-11ddContext Ownership and Inheritance
FEP-1b12Group Federation
FEP-4f05Soft Deletion
FEP-7888Demystifying the context property
FEP-9098Custom emojis
FEP-ae0cFediverse Relay Protocols (Mastodon and LitePub)
FEP-b2b8Long-form Text
FEP-f15dContext Relocation and Removal
FEP-f228Backfilling Conversations
FEP-fb2aActor metadata
FEP-fe34Origin-based security model

Partially Implemented

FEP-7458 (Using the replies collection)

Positive (Not Yet Implemented)

FEP-044f, FEP-8b32, FEP-9967, FEP-c0e0

NodeBB is an active participant in the SWICG Forum and Threaded Discussions Task Force, promoting threaded discussion formats in the Fediverse.


6. Content Discovery and Pruning

Discovery Methods

  1. Follow users/categories — search for handles (e.g., user@domain.social)
  2. URL paste — paste a remote content URL into NodeBB's search bar to pull it in; content lands in Uncategorized
  3. Cross-posting (v4.8.0+) — topics from remote categories can be added to local categories

No Relay Support

NodeBB explicitly does NOT support relays. This is intentional — relays "do not guarantee the quality of incoming content." The design prioritizes relationship-based content distribution over algorithmic or broadcast discovery.

Content Pruning

NodeBB automatically manages remote content to prevent database bloat:

SettingDefaultCondition for removal
Remote content retention30 daysTopics with no local engagement (votes or replies)
Remote user retention7 daysAccounts with no posts and no follow relationships

Both settings are configurable via the admin panel.


7. NodeBB vs Discourse (Federation)

AspectNodeBBDiscourse
LanguageNode.jsRuby on Rails
AP integrationCore feature (v4+)Plugin (discourse-activity-pub)
AP sinceJanuary 20252023 (plugin)
Actor modelGroup (categories)Group (categories)
Context supportFEP-7888 (resolvable)Separate approach
FEPs implemented12Fewer
Real-timeNative WebSocketsLong polling / MessageBus
DatabaseMongoDB/Redis/PostgreSQLPostgreSQL only
LicenseGPL-3.0GPL-2.0

Both bring threaded forum discussions to the Fediverse, using categories as Group actors. NodeBB's core integration means tighter coupling with the ActivityPub protocol and more extensive FEP adoption. Discourse's plugin approach allows easier opt-in/opt-out but has less deep integration.


8. Interoperability Notes for Implementers

  1. Categories are Group actors — follow a NodeBB category by sending Follow to the Group actor at /category/<cid>. The category relays all content via Announce, identical to Lemmy communities. Category handles are slugified names (e.g., general-discussion).

  2. Posts carry both context and audience — context points to the topic (resolvable OrderedCollection), audience points to the category (Group actor). This two-level hierarchy is NodeBB-specific and differs from Lemmy's single-level approach.

  3. Topics are resolvable collections — if your software encounters a NodeBB context URL, resolve it to get the full topic as an OrderedCollection. This is the recommended way to backfill conversations (per FEP-7888 and FEP-f228).

  4. Note and Article objects accepted — NodeBB processes both Note and Article types when building topics. Send whichever is appropriate for your content.

  5. No relay federation — NodeBB will not participate in relay subscriptions. Content exchange requires explicit follow relationships.

  6. Remote content is pruned — NodeBB deletes remote content after 30 days (configurable) if it has no local engagement. If your software references old NodeBB content, it may have been pruned from remote instances that imported it. Similarly, content your software sends to NodeBB will be pruned if no local user engages with it.

  7. Cross-posting — since v4.8.0, a single topic can appear in multiple local categories. This means the same remote content may be accessible via different category Group actors on the same instance.

  8. Soft deletion (FEP-4f05) — NodeBB supports soft deletion. When content is deleted, a Delete activity with a Tombstone object is sent rather than simply disappearing.

  9. Custom emojis (FEP-9098) — NodeBB supports federated custom emoji. Remote emoji in posts and chats are rendered (since v4.7.0).

  10. Content in Uncategorized has no audience — manually discovered content landing in the Uncategorized pseudo-category may not have a proper audience property pointing to a Group actor. This content is not Announced to followers.

PeerTube — Complete Reference

Overview

PeerTube is a free, open-source, decentralized video streaming platform — the Fediverse's alternative to YouTube. Created by Chocobozzz and supported by the French non-profit Framasoft since October 2017, it federates via ActivityPub. As of October 2025, it has approximately 1,906 active instances, 815,000 registered users, and 1.56 million hosted videos. Licensed under AGPL-3.0.

PeerTube federations are asymmetrical — one instance can follow another to display their videos without the other having to reciprocate. This is fundamentally different from Mastodon's symmetrical user-follow model.


1. Technical Stack

LayerTechnology
Backend languageTypeScript (Node.js)
Backend frameworkExpress
DatabasePostgreSQL 12+ (with pg_trgm and unaccent extensions)
Cache / QueueRedis (BullMQ for job queues)
ORMSequelize
Video processingFFmpeg (LTS 4.3+)
OAuthBuilt-in OAuth 2.0
Web serverNginx (official configs provided)
Package managerpnpm
Frontend frameworkAngular (TypeScript)
PlaybackVideoJS, hls.js, P2P Media Loader
Frontend buildWebpack
Frontend CSSSASS / Bootstrap
MobileOfficial app (iOS + Android, December 2024)
LicenseAGPL-3.0
RuntimeNode.js LTS 20.19+ (excl. v21) or v22.12+ (excl. v23)

Server Components

  • REST API — handles client requests and video operations
  • RTMP server — accepts live streaming input (port 1935/TCP, 1936/TCP for RTMPS)
  • ActivityPub implementation — federation between instances
  • Socket.io server — real-time client notifications
  • Task scheduler — processes transcoding and ActivityPub delivery jobs via BullMQ

2. Actor Model

PeerTube uses a two-tier actor model that is central to how it federates video content:

  • Person — represents user accounts
  • Group — represents video channels, owned by Person actors
  • Application — platform-level instance actor for federation and anonymous activities

A single Person can own multiple Group (channel) actors.

Person Actor (Account)

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {"pt": "https://joinpeertube.org/ns#"}
  ],
  "type": "Person",
  "id": "https://peertube.example/accounts/alice",
  "preferredUsername": "alice",
  "name": "Alice",
  "summary": "<p>Bio text</p>",
  "inbox": "https://peertube.example/accounts/alice/inbox",
  "outbox": "https://peertube.example/accounts/alice/outbox",
  "following": "https://peertube.example/accounts/alice/following",
  "followers": "https://peertube.example/accounts/alice/followers",
  "publicKey": {
    "id": "https://peertube.example/accounts/alice#main-key",
    "owner": "https://peertube.example/accounts/alice",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  },
  "endpoints": {
    "sharedInbox": "https://peertube.example/inbox"
  }
}

Group Actor (Video Channel)

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {"pt": "https://joinpeertube.org/ns#"}
  ],
  "type": "Group",
  "id": "https://peertube.example/video-channels/alice_channel",
  "preferredUsername": "alice_channel",
  "name": "Alice's Channel",
  "summary": "<p>Channel description</p>",
  "inbox": "https://peertube.example/video-channels/alice_channel/inbox",
  "outbox": "https://peertube.example/video-channels/alice_channel/outbox",
  "following": "https://peertube.example/video-channels/alice_channel/following",
  "followers": "https://peertube.example/video-channels/alice_channel/followers",
  "attributedTo": [
    {
      "type": "Person",
      "id": "https://peertube.example/accounts/alice"
    }
  ],
  "publicKey": {
    "id": "https://peertube.example/video-channels/alice_channel#main-key",
    "owner": "https://peertube.example/video-channels/alice_channel",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  },
  "endpoints": {
    "sharedInbox": "https://peertube.example/inbox"
  }
}

Key points:

  • The Group actor's attributedTo points to the owning Person actor
  • Users follow channels (Group), not accounts (Person) directly
  • Both Person and Group actors are discoverable via WebFinger
  • The shared inbox path is /inbox
  • The Application instance actor handles platform-level federation and anonymous GET request signing

Interoperability with Non-Channel Platforms

For platforms that don't have a channel concept, PeerTube recommends:

  1. Simulate a Group actor representing the account, or
  2. Put the Person actor as a Group actor in attributedTo owned by a global Person actor

Without a Group actor in attributedTo, PeerTube cannot properly federate the video.


3. Supported Activities

ActivityDescription
AcceptApproves follow requests
AnnounceChannel announces a video (primary video distribution mechanism)
ApproveReplyComment moderation approval (v6.2+, implements FEP-5624)
CreateCreates Video, Note (comment), CacheFile, Playlist
DeleteRemoves Video, Note, Person, Group, Playlist, CacheFile
DislikeThumbs down on a video (non-standard — most Fediverse software only has Like)
FlagFederated report functionality
FollowSubscribe to a channel or instance
LikeThumbs up on a video
RejectDenies follow requests
UndoReverses Follow, Announce, Like, Dislike, CacheFile
UpdateModifies Video, Note, Person, Group, Playlist, CacheFile
ViewView count tracking

How Video Publishing Works

When a user uploads a video:

  1. The Person actor sends a Create{Video} activity
  2. The Group (channel) actor sends an Announce{Video} to its followers
  3. Followers of the channel receive the video via the Announce

This two-step flow is how PeerTube distributes videos — the channel Announce is the primary distribution mechanism.


4. Object Types

Video Object

PeerTube uses Video as the object type (not Note). This is an extended ActivityStreams object with many custom properties:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1",
    {"pt": "https://joinpeertube.org/ns#"},
    {"sc": "http://schema.org/"}
  ],
  "type": "Video",
  "id": "https://peertube.example/videos/watch/abc-123",
  "name": "My Video Title",
  "content": "<p>Video description</p>",
  "summary": "Content warning text",
  "sensitive": false,
  "published": "2025-06-15T12:00:00Z",
  "updated": "2025-06-15T13:00:00Z",
  "attributedTo": [
    {
      "type": "Group",
      "id": "https://peertube.example/video-channels/alice_channel"
    },
    {
      "type": "Person",
      "id": "https://peertube.example/accounts/alice"
    }
  ],
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://peertube.example/video-channels/alice_channel/followers"],
  "duration": "PT5M30S",
  "downloadEnabled": true,
  "waitTranscoding": true,
  "state": 1,
  "commentsPolicy": 0,
  "canReply": "https://www.w3.org/ns/activitystreams#Public",
  "isLiveBroadcast": false,
  "url": [
    {
      "type": "Link",
      "mediaType": "text/html",
      "href": "https://peertube.example/videos/watch/abc-123"
    },
    {
      "type": "Link",
      "mediaType": "video/mp4",
      "href": "https://peertube.example/static/streaming-playlists/hls/abc-123/master.m3u8",
      "height": 1080,
      "fps": 30
    }
  ],
  "embedUrl": "https://peertube.example/videos/embed/abc-123",
  "tag": [
    {
      "type": "Hashtag",
      "name": "#technology"
    }
  ]
}

Key points about the Video object:

  • attributedTo must contain both a Group (channel) and a Person (account) — the Group entry is required for federation
  • name is the video title (not summary as with Mastodon posts)
  • content is the video description (HTML)
  • summary is used for content warnings (like Mastodon)
  • duration uses ISO 8601 duration format (e.g., PT5M30S)
  • url is an array with multiple entries for different formats and resolutions (HTML page, MP4 files, HLS playlists)
  • If embedUrl is absent, the video has embedding restrictions
  • sensitive and a tag of type: SensitiveTag indicate sensitive content

Video Object Extensions

Live streaming properties:

  • isLiveBroadcast — whether this is a live stream
  • liveSaveReplay — whether to save the replay after stream ends
  • permanentLive — persistent stream URL that can be reused
  • latencyMode — latency configuration for the stream
  • schedules — array for scheduled broadcast times

Interaction controls:

  • commentsPolicy — comment policy (integer value)
  • canReply — FEP-5624; when set to the public collection, comments require approval via ApproveReply
  • downloadEnabled — boolean controlling whether viewers can download

State:

  • waitTranscoding — whether to wait for transcoding before publishing
  • state — current video state (integer)

Note (Comments)

Comments are represented as Note objects, compatible with Mastodon and other text-based platforms:

{
  "type": "Note",
  "id": "https://peertube.example/comments/456",
  "content": "<p>Great video!</p>",
  "inReplyTo": "https://peertube.example/videos/watch/abc-123",
  "attributedTo": "https://peertube.example/accounts/bob",
  "published": "2025-06-15T14:00:00Z",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://peertube.example/accounts/alice"]
}

When a Mastodon user replies to a PeerTube video post, the reply appears as a comment on the video in PeerTube.

CacheFile (Redundancy)

A non-standard object type used for PeerTube's video mirroring system:

{
  "type": "CacheFile",
  "object": "https://peertube.example/videos/watch/abc-123",
  "expires": "2025-07-15T12:00:00Z",
  "url": {
    "type": "Link",
    "mediaType": "application/x-mpegURL",
    "href": "https://mirror.example/redundancy/hls/abc-123/master.m3u8"
  }
}

Other Object Types

TypePurpose
PlaylistNon-standard OrderedCollectionPage containing PlaylistElement items
PlaylistElementIndividual playlist entries with start/stop timestamps
WatchActionSchema.org-derived object for aggregated viewer statistics

5. Video Redundancy and CacheFile

PeerTube has a built-in redundancy system allowing instances to mirror videos from other instances, improving resilience and bandwidth sharing.

How Redundancy Works

  1. An admin configures a redundancy strategy (cache trending videos, recently uploaded videos, etc.)
  2. PeerTube periodically checks for new videos to duplicate
  3. When a video is selected, all resolution files are imported and stored locally
  4. A Create{CacheFile} ActivityPub message is sent to federated instances
  5. The caching instance is injected as a WebSeed by instances that receive this message — viewers can now download video chunks from the mirror
  6. When the cache is full, old videos are evicted and new ones selected

ActivityPub Flow

  • Create{CacheFile} — sent when a mirror instance begins caching
  • Undo{CacheFile} — sent when the cached copy is removed

Redundancy Strategies

  • Most viewed — cache the most popular videos
  • Recently added — cache the newest videos
  • Complete mirror — use recently-added with view count set to 0

Benefits

  • If the origin server goes down, the video remains accessible from cache instances
  • Servers share bandwidth for popular content
  • P2P delivery benefits from additional WebSeeds

6. P2P Video Delivery

PeerTube uses HLS with WebRTC P2P for video playback:

  • Video chunks are loaded via HTTP from the origin server and any mirrors (WebSeeds)
  • Simultaneously, chunks are exchanged between viewers via WebRTC peer-to-peer connections
  • Under optimal conditions (many concurrent viewers), P2P can reduce server bandwidth usage by 80-90%
  • P2P efficacy diminishes with few concurrent viewers

Up until version 6.0.0, PeerTube also supported WebTorrent for P2P delivery. WebTorrent was dropped in v6.0 in favour of HLS-only P2P.

Privacy Consideration

P2P streaming exposes viewer IP addresses to other peers. This is inherent to how WebRTC works and should be considered when deploying PeerTube in privacy-sensitive contexts.


7. Live Streaming

PeerTube supports live streaming (introduced in v3.0, January 2021):

  • RTMP ingestion — stream via OBS or any RTMP-compatible software (port 1935/TCP)
  • RTMPS — encrypted streaming (port 1936/TCP)
  • Live transcoding — real-time transcoding to multiple resolutions
  • HLS output — live streams delivered via HLS with P2P WebRTC
  • Permanent live streams — persistent stream URLs that can be reused
  • Stream scheduling — schedule when a stream starts (v7.3+)
  • Live chat — basic integration (v7.3+)
  • Save replay — optionally save recordings as VOD after stream ends
  • Federation — live streams federate to channel followers via ActivityPub using Video objects with isLiveBroadcast: true

Live transcoding is processed differently from VOD transcoding — it happens in real-time and can be offloaded to remote runners.


8. JSON-LD Context

PeerTube uses extended contexts with multiple custom namespaces:

"@context": [
  "https://www.w3.org/ns/activitystreams",
  "https://w3id.org/security/v1",
  {"pt": "https://joinpeertube.org/ns#"},
  {"sc": "http://schema.org/"}
]
NamespacePrefixPurpose
https://www.w3.org/ns/activitystreams—ActivityStreams 2.0 vocabulary
https://w3id.org/security/v1—W3C Security Vocabulary (publicKey)
https://joinpeertube.org/ns#pt:PeerTube-specific properties (commentsPolicy, downloadEnabled, isLiveBroadcast, etc.)
http://schema.org/sc:Schema.org vocabulary (WatchAction, etc.)
https://join-lemmy.org/ns#lemmy:Lemmy compatibility (postingRestrictedToMods)

When processing PeerTube JSON-LD documents, unknown properties from the pt: namespace should be ignored rather than causing errors.


9. HTTP Signatures and WebFinger

HTTP Signatures

PeerTube signs ActivityPub messages with JSON Linked Data Signatures using the private key of the account that authored the action. HTTP Signatures are used for server-to-server authentication.

Each actor (Person, Group, Application) has its own key pair. The Application instance actor is used for platform-level operations.

WebFinger

PeerTube supports WebFinger at /.well-known/webfinger for actor discovery. Both Person (account) and Group (channel) actors are discoverable:

  • Account: acct:alice@peertube.example
  • Channel: acct:alice_channel@peertube.example

10. Cross-Platform Federation

Mastodon Interoperability

Action on MastodonResult on PeerTube
Follow a PeerTube channelVideos appear in Mastodon home timeline
Reply to a PeerTube video postAppears as a comment on the video
Favourite a PeerTube videoAppears as a thumbs up (Like)
Boost a PeerTube videoIncreases reach on federated timelines
Action on PeerTubeResult on Mastodon
Upload a videoAppears as a post in followers' timelines
Like a Mastodon commentStandard Like activity
DislikeNot processed — Mastodon ignores Dislike activities

Dislike (Non-Standard)

PeerTube supports the Dislike activity (thumbs down), which is non-standard in the broader Fediverse. Most Fediverse software only implements Like. Mastodon does not send or process Dislike activities, so dislikes from PeerTube are silently ignored by Mastodon and most other platforms.

Comment Approval (FEP-5624)

PeerTube v6.2+ supports comment moderation via the ApproveReply activity (implementing FEP-5624). When a video has canReply set to the public collection, comments from remote instances require approval before becoming visible. The origin PeerTube instance sends an ApproveReply activity back to the commenter's instance when approved.

Asymmetrical Instance Following

PeerTube instances can follow other PeerTube instances to display their videos without the followed instance needing to reciprocate. This is an admin-level operation used for content discovery.


11. Plugin System and Remote Runners

Plugin System

  • Plugins are installed via NPM in a dedicated directory
  • The server requires the module and calls its register() function
  • Hooks fire on application events (video creation, page initialization, transcoding, etc.)
  • Themes operate as client-only plugins with CSS injection
  • Plugins can add custom API routes, settings pages, and client-side components

Remote Runners

PeerTube can offload heavy processing to remote machines:

  • Remote runners register with the instance using registration tokens
  • They poll the REST API for pending jobs
  • Supported tasks: VOD transcoding, Studio transcoding, Live transcoding, Automatic transcription
  • When remote runners are enabled for a task, PeerTube stops processing that task locally
  • The runner posts the job result back to PeerTube

Known limitation: Server-side transcoding plugins are disabled when remote runners are enabled for transcoding tasks.


12. Common Implementation Mistakes

  • Missing Group actor in attributedTo: PeerTube requires videos to have an attributedTo field containing a Group actor — without it, the video cannot be properly federated. If your platform does not have channels, simulate a Group actor or use the Person actor in the Group role
  • Treating PeerTube videos as Note objects: PeerTube uses Video as the object type, not Note — code that only handles Note will miss all PeerTube content. Implement handling for type: "Video" in your ActivityPub processor
  • Ignoring the two-tier attributedTo: PeerTube's attributedTo contains both a Group (channel) and a Person (account) — if you only read the first entry, you may attribute the video to the channel instead of the person, or vice versa
  • Not handling Dislike gracefully: PeerTube sends Dislike activities that most Fediverse software does not understand — your implementation should ignore unknown activity types rather than erroring
  • Assuming video URL is a single string: PeerTube's url field is an array with multiple entries for different formats (HTML page, MP4 at various resolutions, HLS playlists) — pick the appropriate entry based on mediaType
  • Not handling CacheFile: if you receive a Create{CacheFile} activity, it means a remote instance is mirroring one of your videos — you should add the mirror as a WebSeed for that video, not reject the activity as unknown
  • Expecting symmetrical follows: PeerTube instance-level follows are asymmetrical — following an instance does not mean they follow you back. Don't assume mutual federation.
  • Ignoring embedUrl absence: if a PeerTube Video object lacks embedUrl, the video has embedding restrictions — do not attempt to generate an embed URL by guessing the pattern
  • Not supporting ApproveReply: if your users comment on PeerTube videos with comment approval enabled, the comment won't be visible until the PeerTube instance sends back an ApproveReply — handle this pending state in your UI rather than showing it as posted

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

ComponentTechnology
Backend languagePython (3.9+, ~70% of codebase)
Web frameworkFlask
Frontendhtmx + vanilla JavaScript + Bootstrap CSS
Template engineJinja2
DatabasePostgreSQL 17
ORMSQLAlchemy (Flask-SQLAlchemy)
MigrationsAlembic (flask db upgrade)
Task queueCelery with Redis broker
CacheRedis 6.2 (optional)
Application serverGunicorn
Real-time notificationsFastAPI + Uvicorn (separate service)
LintingRuff
i18nBabel
DeploymentDocker (5-service compose), bare metal, YunoHost
LicenseAGPL-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 ConceptActivityPub TypeNotes
CommunityGroupRelay actor; Announces content to followers
UserPersonCreates content, moderates
BotServiceBot accounts
FeedFeedPieFed extension (FEP-1d80); federated multi-community collection
PostPagePrimary post type, mandatory title (name)
ArticleArticleLong-form content
Link postLinkURL submissions
CommentNoteTree structure via inReplyTo
PollQuestiononeOf/anyOf choices, up to 15 options
EventEventstartTime, endTime, timezone, participantCount
VideoVideoPeerTube video embeds
Direct messageChatMessagePrivate 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

AttributeDescription
sensitiveNSFW flag
nsflNot-safe-for-life flag (separate from NSFW)
genAIAI-generated content flag
postingRestrictedToModsOnly moderators can post
newModsWantedCommunity is seeking moderators
privateModsModerator list is hidden
defaultPostTypeDefault content type for new posts
questionAnswerStackOverflow-style Q&A mode enabled
moderatorsOrderedCollection of moderators
featuredPinned posts collection
tagsForPostsAvailable 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

ActivityPurpose
FollowSubscribe to community/feed
Accept / RejectSubscription response
CreateNew post, comment, chat message, poll
UpdateEdit post/comment, update community profile
DeleteRemove post, comment, PM, feed
LikeUpvote
DislikeDownvote
EmojiReactCustom emoji reaction (unicode or :name: format)
PollVoteVote in a poll
ChooseAnswerMark comment as answer (Q&A mode)
AddAdd moderator, sticky post, add community to feed
RemoveRemove moderator, unsticky post, remove from feed
LockLock post or comment (including children)
FlagReport content
AnnounceBoost/share (wraps other activities)
UndoReverse any previous activity

Community → Followers

ActivityPurpose
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

PropertyUsed onDescription
tagsForPostsGroupAvailable flair/tag options (Lemmy CommunityTag)
postingRestrictedToModsGroupRestricted posting
languagePage, NoteLanguage metadata (identifier + name)

PieFed-Specific Extensions

PropertyUsed onDescription
genAIGroup, PageAI-generated content flag
nsflGroup, PageNot-safe-for-life flag
flairNoteUser flair (custom extension on comments)
postingWarningGroupContextual warning above comment form
interactionPolicyPageInteraction restrictions
newModsWantedGroupCommunity seeking moderators
questionAnswerGroupQ&A mode enabled

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

AspectDetail
AlgorithmRSA-SHA256 (also accepts hs2019)
Key size2048-bit RSA
Signed headers(request-target), Host, Date, Digest, Content-Type, Accept
Date tolerance3,600 seconds (1 hour)
FallbackLD signatures via URDNA2015 normalization
Key cacheUp 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

PathPurpose
/.well-known/webfingerUser, community, and feed discovery
/.well-known/nodeinfoNodeInfo schema links
/nodeinfo/2.0, /nodeinfo/2.1Server stats and protocol info
/u/<actor>User actor (content-negotiated JSON/HTML)
/c/<actor>Community actor
/inboxShared inbox
/site_inboxSite-level inbox
/api/v1/instanceMastodon-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.

AspectDetail
Base path/api/alpha/
DocumentationSwagger at /api/alpha/swagger
Total endpoints100+
Rate limitingApplied 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

TypeDetails
Link postsURL submissions
Text postsMarkdown body
Image postsWith alt text; width control via ![alt :: width=300px](url)
Video postsDirect upload (v1.5+, admin-configurable)
PollsQuestion with oneOf/anyOf, up to 15 options, Mastodon-compatible
EventsTime, timezone, location, participant count
PeerTube videosEmbedded player, auto-import from channels
Cross-postsDeduplicated with consolidated comment views
Scheduled postsWith timezone support
Wiki pagesPer-community editable wikis
Emoji reactionsUnicode and custom (:piefed:), federated as Likes for Lemmy compat
Quote postsv1.6+, Mastodon quote-boost interop
StackOverflow Q&AComments markable as answers via ChooseAnswer
SpoilersFlair-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)

ServicePurpose
dbPostgreSQL 17
redisRedis 6.2
celeryCelery worker for async federation tasks
appFlask/Gunicorn web app (port 8030)
piefed_notifsFastAPI/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

AspectPieFedLemmy
LanguagePython/FlaskRust/Actix-web
Resource usage~1 load avg~12 load avg (same hardware)
Feed actor typeYes (FEP-1d80)No
Private votingProxy user profilesAll votes public/federated
Cross-post dedupMerged comment viewsSeparate posts
AI content flaggenAI propertyNo
NSFL flagSeparate from NSFWNo (NSFW only)
EmojiReactYes (federated as Likes to Lemmy)No
ChooseAnswerYes (Q&A mode)No
Event objectsYesNo
PollVoteYes (Mastodon-compatible)No native polls
Flair federationflair on Note + tagsForPoststagsForPosts only
API path/api/alpha//api/v3/
API compatibility95% Lemmy-compatible—
JSON-LD processingPlain JSON (no expansion)Plain JSON (no expansion)

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

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

LayerTechnology
Backend languagePHP
Backend frameworkLaravel (currently v12)
DatabaseMySQL 8.0 or PostgreSQL 13
Cache / QueueRedis
Queue managementLaravel Horizon
OAuthLaravel Passport
Frontend frameworkVue.js 2.6.14
Frontend stateVuex
CSSBootstrap
BuildWebpack via Laravel Mix
MobileReact Native (iOS + Android)
StorageLocal filesystem or S3/Object Storage
LicenseAGPL-3.0
RuntimePHP 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

ActivityDescription
AcceptApproves follow requests
AddFederates Stories (uses Bearcap URIs for access control)
AnnounceReblogs/boosts
CreateCreates Note and Question objects
DeleteRemoves Person, Tombstone, and Story objects
FlagFederated report functionality
FollowFollow request
LikeFavorites a post
RejectDenies follow requests
UndoReverses Announce, Follow, and Like
UpdateModifies Note (status) and Person (profile)
ViewStory view tracking
Story:ReactionReaction to a Story (Pixelfed-only)
Story:ReplyReply 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#"}
]
NamespacePurpose
https://www.w3.org/ns/activitystreamsActivityStreams 2.0 vocabulary
https://w3id.org/security/v1W3C 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:

CollectionPathContent
Following/users/{username}/followingAccounts this user follows
Followers/users/{username}/followersAccounts following this user
Outbox/users/{username}/outboxUser'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

FeaturePixelfed to MastodonMastodon to Pixelfed
Photo postsAppear as image posts with textAppear normally if image attached
Text-only postsN/A (Pixelfed requires media)Not displayed on Pixelfed
Album posts (>4 images)Only first 4 images shownN/A (Mastodon max 4)
StoriesNot visibleN/A
BoostsAppear as boostsAppear as boosts
Likes/FavouritesFederate normallyFederate normally
RepliesFederate, but display may be incompleteFederate normally
Content warningsShow as content warningsShow 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

VariableDescription
ACTIVITY_PUBEnable/disable federation entirely
AP_REMOTE_FOLLOWAllow/prevent remote following

Media

VariableDefaultDescription
MAX_PHOTO_SIZE15000 (KB)Per-file size limit (15 MB)
MAX_ACCOUNT_SIZE1000000 (KB)Per-user total storage (1 GB)
MAX_ALBUM_LENGTH4Items per post
IMAGE_QUALITY80JPEG quality 1-100
PF_OPTIMIZE_IMAGES—Automatic image optimization
PF_OPTIMIZE_VIDEOS—Automatic video optimization
PF_ENABLE_CLOUD—S3/Object Storage support

Accounts

VariableDefaultDescription
MAX_CAPTION_LENGTH500Caption character limit
MAX_BIO_LENGTH125Bio character limit
MAX_NAME_LENGTH30Display name limit
OPEN_REGISTRATIONtrueNew account creation
PF_MAX_USERS1000User registration cap
ENFORCE_EMAIL_VERIFICATION—Email confirmation required

Features

VariableDefaultDescription
STORIES_ENABLEDfalseStories 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"

WriteFreely — Complete Reference

Overview

WriteFreely is a free, open-source, federated blogging platform written in Go, created by Matt Baer and developed under Musing Studio (formerly the Write.as team). Licensed AGPL-3.0.

WriteFreely originated from Write.as, a privacy-focused anonymous writing platform launched in late 2014. After adding ActivityPub federation support, the codebase was refactored and released as open source in November 2018. It describes itself as "the social media hater's blogging platform" — deliberately rejecting feeds, alerts, and engagement metrics in favor of a distraction-free writing environment.

WriteFreely's federation model is write-only/broadcast: blogs can be followed from Mastodon and other ActivityPub platforms, but WriteFreely cannot follow others, does not display incoming replies or comments, and has no follower moderation. This is a deliberate design choice — it is a writing platform, not a social network.

As of early 2026, Write.as has hosted over 600,000 users with 6.6 million posts. The WriteFreely open-source software powers hundreds of independent instances across the fediverse.


1. Technology Stack

ComponentTechnology
BackendGo (golang) — 64% of codebase
TemplatesGo Template — 24%
StylingLESS — 6.5%
Client-sideJavaScript — 3.8%
DatabaseMySQL/MariaDB 5.6+ or SQLite
Rich editorProseMirror (WYSIWYG "classic" mode)
LicenseAGPL-3.0

Key Technical Characteristics

  • Single binary deployment on any platform/architecture Go supports
  • Minimal resources: runs on servers with 256 MB RAM, including Raspberry Pi
  • No external dependencies in SQLite mode
  • Built-in HTTP server with TLS support (Let's Encrypt auto-cert)
  • Optional Gopher protocol server (since v0.13)
  • Go 1.23+ and Node.js 15+ required for development builds

Database

Two backends supported:

  • MySQL/MariaDB 5.6+: CREATE DATABASE writefreely CHARACTER SET latin1 COLLATE latin1_swedish_ci;
  • SQLite: Built-in, no external database needed

PostgreSQL is not supported.

Database tables include: user access tokens, public/private RSA keypairs per collection (for signing ActivityPub requests), collections (blogs), posts, remote users, and remote follows.


2. ActivityPub Implementation

Actor Model

Each blog (collection) is an ActivityPub actor of type Person. In single-user mode, the instance acts as the single blog actor.

The fediverse handle format is @blog@instance.com (or @username@instance.com in single-user mode).

Each collection/blog has:

  • A public/private RSA keypair for signing requests
  • An inbox endpoint for receiving activities
  • An outbox endpoint for published content
  • A followers collection

Object Types

WriteFreely federates posts as either Article or Note:

  • Article: Posts containing a double-line break (paragraph break). The default for multi-paragraph blog posts. Includes the post title in the name property.
  • Note: Posts without paragraph breaks (single-paragraph). Can be forced for all posts via notes_only = true configuration.

The heuristic: if the post body contains \n\n (double newline), it is sent as Article; otherwise as Note. This was implemented in v0.13 (merged March 2021).

Since v0.16, posts include preview/summary fields so microblogging platforms like Mastodon and Threads show excerpts with links rather than just a link.

Activities

WriteFreely supports a deliberately limited set of activities:

Outbound (WriteFreely sends):

ActivityTrigger
Create{Article} or Create{Note}Post published
Update{Article} or Update{Note}Post edited
DeletePost deleted

Inbound (WriteFreely receives):

ActivityEffect
FollowRemote user follows a blog
Undo{Follow}Remote user unfollows
LikeRemote user favorites a post (count tracked since v0.16)

Write-Only / Broadcast Nature

This is the most critical detail for interoperability:

  • Blogs can be followed from Mastodon, Pleroma, and other AP platforms
  • Posts are delivered to followers' timelines
  • No incoming replies/comments: WriteFreely does not display replies from federated users on the blog itself
  • No outgoing follows: Cannot follow other users from WriteFreely
  • No blocking/managing follows: No moderation tools for followers
  • No Announce/boost: WriteFreely does not send or process boosts
  • Mentions as workaround: Authors can mention their own Mastodon account (@handle@their.instance) in posts so fediverse replies route to their microblogging account

HTTP Signatures

RSA-SHA256 signatures with per-blog keypairs. Signed headers include: request target, date, host, and digest. Remote user data stored: actor ID, inbox URL, shared inbox URL, user handle, and public key.

Libraries

  • go-fed/activity/streams: ActivityPub library for Go
  • writefreely/go-nodeinfo: Fork of NodeInfo with WriteFreely-specific metadata

3. Configuration

WriteFreely uses an .ini config file (config.ini by default).

Instance Modes

  • Single-user: One blog, the instance is the blog actor
  • Multi-user: Multiple accounts, each with up to 5 blogs (default), local timeline/reader, admin dashboard, invitation system

Key Federation Settings

FieldDescriptionDefault
federationActivityPub federation toggletrue
notes_onlySend all posts as Note (not Article)false
public_statsNodeInfo statistics visibilitytrue

Other Notable Settings

FieldDescriptionDefault
single_userSingle-blog instance modefalse
editorEditor template: pad, bare, classicpad
open_registrationPublic signup (multi-user)true
max_blogsBlogs per account (multi-user)5
default_visibilityNew blog visibilityunlisted
local_timelineInstance reader (multi-user)true
monetizationWeb Monetization supporttrue
gopher_portGopher server port (0 = disabled)0

4. NodeInfo

WriteFreely implements NodeInfo via github.com/writefreely/go-nodeinfo (v1.2.0, MIT license), a fork with WriteFreely-specific metadata.

Discovery

/.well-known/nodeinfo → points to full NodeInfo URL.

WriteFreely-Specific Metadata

{
  "metadata": {
    "nodeName": "My Blog",
    "nodeDescription": "A writing community",
    "private": false,
    "software": {
      "homepage": "https://writefreely.org",
      "github": "https://github.com/writefreely/writefreely",
      "follow": "https://writing.exchange/@writefreely"
    },
    "maxBlogs": 5,
    "publicReader": true,
    "invites": true
  },
  "protocols": ["activitypub"],
  "services": {
    "outbound": ["rss2.0"]
  },
  "software": {
    "name": "writefreely",
    "version": "0.16.0"
  }
}

5. API

WriteFreely provides a RESTful API (shared with Write.as) with full read access and publishing.

Authentication

Token-based: Authorization: Token {access_token} (UUID format). Anonymous publishing is supported — no auth required for creating posts.

Accepts form data (default) or application/json. Returns JSON.

Core Endpoints

Posts:

MethodEndpointAuthPurpose
POST/api/postsOptionalCreate post
GET/api/posts/{id}NoRetrieve post
POST/api/posts/{id}OptionalUpdate post
DELETE/api/posts/{id}OptionalDelete post
POST/api/posts/claimRequiredClaim anonymous posts

Collections (Blogs):

MethodEndpointAuthPurpose
POST/api/collectionsRequiredCreate collection
GET/api/collections/{alias}NoGet metadata
POST/api/collections/{alias}/postsRequiredPublish to blog
GET/api/collections/{alias}/postsNoList posts
GET/api/collections/{alias}/posts/{slug}NoGet single post

Users:

MethodEndpointAuthPurpose
POST/api/auth/loginNoAuthenticate
GET/api/meRequiredGet user info
GET/api/me/postsRequiredList user's posts
GET/api/me/collectionsRequiredList user's blogs

Data Models

Post: id, slug, token (for anonymous updates), title, body (Markdown), appearance (sans/serif/wrap/mono/code), language, rtl, created, updated, views, tags, collection.

Collection: alias (URL slug), title, description, style_sheet, script, visibility (0=Unlisted, 1=Public, 2=Private, 4=Password-protected), views, total_posts.


6. Features

Writing and Publishing

  • Distraction-free Markdown editor with three modes: pad (default), bare, classic (WYSIWYG via ProseMirror, since v0.13)
  • MathJax formula rendering
  • Hashtag organization
  • Custom CSS and JavaScript per blog
  • Font appearances: serif, sans-serif, monospace, wrapped
  • RTL script support, 20+ language localizations
  • Draft posts, static pinned pages, post signatures
  • RSS feed per blog (automatic)
  • SEO best practices encoded by default
  • No native image hosting — must embed from external sources (Snap.as or other hosts)

Multi-User Community

  • Multiple blogs per account (configurable, default 5)
  • Local timeline / reader for shared content
  • Privacy levels: public, unlisted, private, password-protected
  • Open or closed registration, invitation system
  • Admin dashboard with instance stats and user management

Federation Features

  • Fediverse verification badges via rel="me" (since v0.14)
  • Like counts visible to blog authors (since v0.16)
  • Subscribers page showing fediverse followers
  • fediverse:creator tag linking to another profile (since v0.16)
  • Mentions via @handle@their.instance in post content

Other Protocols and Integrations

  • Gopher protocol server (since v0.13)
  • Web Monetization micropayments (since v0.13)
  • Email newsletters via Mailgun (since v0.15)
  • SMTP for password resets and notifications (since v0.16)
  • OAuth 2.0: Generic, Gitea, GitLab, Slack, Write.as

7. Ecosystem

WriteFreely is part of the Musing Studio ecosystem:

ServicePurpose
Write.asHosted blogging platform ($1-10/month)
WriteFreelyOpen-source software (self-hosted)
WriteFreely.hostManaged WriteFreely community hosting
Snap.asMinimalist photo sharing
Remark.asCommenting system for Write.as blogs
Submit.asAccept writing submissions
Read.as / ReadFreelyActivityPub reading client (paused)

Musing Studio was founded by Matt Baer in 2015. He runs the company solo. Core values: ad-free, tracking-free, customer-funded (no venture capital), open web interoperability.


8. Comparisons

WriteFreely vs Plume

AspectWriteFreelyPlume
LanguageGoRust
Federation modelWrite-only (broadcast)Bidirectional (shows replies)
CustomizationCustom CSS onlyThemes, fonts, layouts
MaintenanceActively maintainedNot actively maintained
Object typesArticle + NoteArticle

WriteFreely vs Ghost

AspectWriteFreelyGhost
LanguageGoNode.js
AP integrationSince 2018 (core)Since 2024 (core)
FocusMinimalist writingFull-featured CMS
Image hostingNone (external only)Built-in
NewslettersMailgun integrationBuilt-in
ThemesCustom CSSFull theme system
Resources256 MB RAM1 GB+ RAM

9. Interoperability Notes for Implementers

  1. Blogs are Person actors — each WriteFreely blog (collection) presents itself as a Person actor with a fediverse handle of @alias@instance.com. Follow a blog by sending Follow to this actor.

  2. Write-only federation — WriteFreely will never send Follow, Announce, Like, or reply activities. It only sends Create, Update, and Delete for its own posts. If your software expects bidirectional interaction, WriteFreely will not reciprocate.

  3. Article vs Note distinction — multi-paragraph posts arrive as Article objects (with name containing the title), single-paragraph posts arrive as Note objects (no name). If an instance has notes_only = true, all posts arrive as Note. Your software should handle both types from WriteFreely.

  4. No incoming comment support — if your users reply to a WriteFreely post, their reply will be delivered to the WriteFreely inbox but will not be displayed on the blog. The reply exists only on your platform. Authors may work around this by mentioning their Mastodon account in posts.

  5. Like tracking — since v0.16, WriteFreely tracks Like activities and shows a count to the blog author. Sending Like to a WriteFreely blog will be acknowledged, but Undo{Like} handling may vary.

  6. No shared inbox optimization — WriteFreely stores shared inbox URLs from remote actors but primarily uses individual inboxes. Verify delivery works with both paths.

  7. Post excerpts on microblogging platforms — since v0.16, WriteFreely includes preview/summary fields on Article objects. Mastodon and Threads will show an excerpt with a link rather than just a bare link. Older WriteFreely versions may send Articles without summaries.

  8. NodeInfo identifies the software — look for "name": "writefreely" in the NodeInfo software block to identify WriteFreely instances. The metadata includes WriteFreely-specific fields like maxBlogs, publicReader, and invites.

  9. RSS is always available — every WriteFreely blog has an RSS feed regardless of federation settings. If federation is disabled, RSS is still the primary syndication method.

  10. No image hosting — WriteFreely posts reference externally-hosted images via Markdown image syntax. If your software processes WriteFreely content, images will be URLs to third-party hosts (including Snap.as), not to the WriteFreely instance itself.

Sponsors

Details

Marketplace
reiver/vibefed
Category
Community