
vibefed
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@vibefedRun it inside Claude Code after adding the marketplace with /plugin marketplace add reiver/vibefed.
Contents
Discovered from sourceSkills 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
linksarray, 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.1or/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)activeHalfyearoractiveHalfYear(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 / Language | Pattern to look for |
|---|---|
| Rails | get '/.well-known/nodeinfo' in routes.rb; nodeinfo_controller.rb |
| Django | path('.well-known/nodeinfo' in urls.py |
| Express / Node | app.get('/.well-known/nodeinfo' |
| Spring Boot | @GetMapping("/.well-known/nodeinfo") |
| Go | nodeinfo.NodeInfoPath constant; NodeInfoDiscover handler |
| Mastodon | WellKnown::NodeinfoController |
| Misskey / Calckey | nodeinfo 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 today1.1— addsservices2.0— addsusage.localComments; most common2.1— addssoftware.repositoryandsoftware.homepage; current standard2.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:
- Verdict: NodeInfo detected / Not detected / Possibly delegated to library
- 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
- Discovery endpoint (
- Schema versions supported (if determinable)
- Evidence: File names and line numbers containing the implementation
- Implementation style: Direct / Library delegation / Framework built-in
- Completeness notes (if applicable):
- e.g. "Discovery endpoint found but no schema endpoint detected"
- e.g. "Schema endpoint found but
usagestats appear hardcoded rather than queried from a database" - e.g. "Missing
openRegistrationsfield in schema response"
- 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
resourcequery parameter - Returns a JSON response (JRD format) with a
subjectfield
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:
| Framework | Pattern to look for |
|---|---|
| Express / Node | app.get('/.well-known/webfinger' |
| Rails | get '/.well-known/webfinger' in routes.rb |
| Django | path('.well-known/webfinger' in urls.py |
| Spring Boot | @GetMapping("/.well-known/webfinger") |
| Mastodon / ActivityPub | Check for webfinger_controller or webfinger_resource |
| PHP | $_GET['resource'] near a well-known path check |
Step 5 — Report Results
Provide a clear summary with:
- Verdict: WebFinger detected / Not detected / Possibly delegated to library
- Evidence: List the specific files and line numbers (if available) that contain the implementation
- Implementation style: Direct route handler / Library delegation / Framework built-in
- Completeness notes (if applicable): e.g. "Handler found but no
relparameter filtering detected" or "Missingapplication/jrd+jsoncontent type header" - 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
subjectfield, typically alsolinksand/oraliases - HTTP 404 if the resource is not found
- HTTP 400 if the
resourceparam 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:
- Copy the URL of the content or actor
- Paste it into their own instance's search bar
- Wait for it to resolve
- 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/Followhttps://w3id.org/fep/3b86/Likehttps://w3id.org/fep/3b86/Announcehttps://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:
| Intent | Rel suffix | Primary parameters | Purpose |
|---|---|---|---|
| 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:
| Parameter | Description |
|---|---|
{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:
- User visits a remote server and sees social interaction buttons (Follow, Like, Share, etc.)
- User clicks a button
- Remote server checks if the user is already recognized (e.g., via cookie)
- If unrecognized, user enters their Fediverse ID (
@user@server) - Remote server performs a WebFinger query for the user's home server
- Remote server finds the appropriate Activity Intent link in the response
- Remote server substitutes parameter values into the URI Template
- User is redirected to their home server's Activity Intent endpoint
- Home server shows a confirmation page (CSRF-protected POST form)
- User confirms; home server executes the activity
- Home server uses
on-success/on-cancelto 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:
- Activity Intents — use if present in WebFinger response
- oStatus subscribe — fall back to the
http://ostatus.org/schema/1.0/subscribetemplate (Mastodon's/authorize_interactionendpoint) - 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
templateproperty - 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)
| Aspect | Activity Intents (FEP-3b86) | Fedilinks (FEP-07d7) |
|---|---|---|
| Approach | Server-side | Client-side (browser) |
| Discovery | WebFinger lookup | web+ap:// URI scheme |
| Browser changes | None required | Requires protocol handler registration |
| Adoption barrier | Server implements WebFinger links | Needs browser vendor support |
| Works today | Yes, with any browser | No — no AP implementations parse web+ap:// URIs |
| Scope | All activity types + Object | Object 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)
| Implementation | Intents Published |
|---|---|
| Emissary | Create, Follow, Like |
| Forte | Create |
| Loops | Follow |
| PieFed | Create |
| streams | Create |
| WordPress (ActivityPub plugin v7.6.0+) | Create, Follow |
Client Implementations (Consuming Activity Intents)
| Implementation | Features |
|---|---|
| Emissary | Share/like buttons on remote content |
| Forte | Wall-to-wall post/reply buttons |
| streams | Wall-to-wall functionality |
| Web Intents library | In 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)
- Add Activity Intent links to your WebFinger JRD response
- Use the
https://w3id.org/fep/3b86/*namespace forrelvalues - Use RFC 6570 URI Templates in the
templateproperty - At minimum, publish Follow and Create intents (most useful)
- Consider also publishing Like, Announce, and Object intents
- 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)
- Intent URLs are loaded via GET — display a confirmation page
- Include a CSRF token in the confirmation form
- The actual mutation happens via POST form submission
- After completion, handle
on-success:- If
(close), close the window (JavaScriptwindow.close()) - If a URL, show an interstitial page with the destination
- If
- If the user cancels, handle
on-cancelthe same way - 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)
- When a user wants to interact with content, prompt for their Fediverse ID
- Perform a WebFinger query for their ID
- Look for the appropriate Activity Intent link in the response
- If not found, fall back to oStatus subscribe, then hard-coded URLs
- Substitute parameter values into the URI Template (percent-encode per RFC 3986)
- Redirect the user to the constructed URL
- Optionally include
on-successand/oron-cancelcallback URLs
Known Issues and Open Questions
- DRAFT status — FEP-3b86 has not reached FINAL; the spec may change
- Mastodon adoption unclear — the largest Fediverse implementation has not committed to support
- Open redirect debate unresolved — thisismissem proposed OAuth-style preregistered redirect URIs, which would be more secure but add complexity
- Limited client adoption — only 3 implementations consume intents; most Fediverse software only displays intents for its own users
- 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)
- 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
| Field | Description |
|---|---|
id | Unique identifier for this status update |
attributedTo | ID of the actor whose status this is |
content | Plain text content of the status |
published | Timestamp when the status was created |
Optional Fields
| Field | Description |
|---|---|
endTime | Timestamp when the status expires. If present and in the past, implementations MUST NOT display this status |
attachment | Structured 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
ActorStatusobject (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 ifDeleted)
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
objectID matches the actor's current status, clear it - If the actor has
statusHistory, the status stays in history - The actor's
statusfield 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
statusHistoryas well as clearing from profile - If the actor has no
statusHistory, this is identical toRemove
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
objectfrom 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:
| Activity | Profile | History | Use case |
|---|---|---|---|
Remove | Cleared | Kept (if statusHistory exists) | "I'm done with this status, but it's part of my history" |
Delete | Cleared | Removed | "I want this status to no longer exist anywhere" |
Remove (no history) | Cleared | N/A | Identical 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
| Platform | Feature | Interactable? | Media? | Limit | History? |
|---|---|---|---|---|---|
| Early Facebook (2006–2009) | "is..." status | No | No | Very short | Yes |
| VKontakte | Status/tagline | No | No | Short | Yes |
| Discord | Custom status | No | Emoji only | 128 chars | No |
| GitHub | Custom status | No | Emoji only | Short | No |
| Slack | Custom status | No | Emoji only | 100 chars | No |
| FEP-82f6 | ActorStatus | No | Attachment metadata | 100+ chars | Optional |
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 action | Activity |
|---|---|
| Set status | Create{ActorStatus} |
| Clear status | Remove{ActorStatus} |
| Delete status | Delete{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
featuredhas 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 (Updatewith a side effect) - It opens the door to restoring expired statuses by resetting
endTimeto a future date - The
Removeactivity 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
- Create an
ActorStatusobject withid,attributedTo,content,published, and optionallyendTimeand/orattachment - Send
Create{ActorStatus}to the actor's followers - Update the actor's
statusfield with the new status - Do NOT send
Update{Actor}— theCreateimplicitly updates remote copies
Receiving a Status Update
- On
Create{ActorStatus}: update the actor's displayed status. If you track history and the actor hasstatusHistory, add to it. If nostatusHistory, discard the previous status. - On
Remove{ActorStatus}: if the object ID matches the current status, clear it. Keep in history if applicable. - On
Delete{ActorStatus}: clear from profile AND remove from history. - 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
endTimeis present and in the past, do NOT display - If
statusHistoryis 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
endTimeand stop displaying expired statuses. There is no push notification for expiration — it's poll-based on theendTimevalue. - 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
statusHistorycollection 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:
- It MUST be a valid Markdown document
- 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
| Field | Purpose |
|---|---|
doap:name | Project name |
doap:homepage | Project website |
doap:description | Multilingual description |
doap:repository | Repository URLs |
doap:release | Version and date information |
doap:implements | Federation protocols supported |
doap:supportedFEPs | Adopted FEPs |
doap:maintainer | Project 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
-
Create the file at the root of your project repository
-
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.)
-
List supported FEPs with links to the FEP specifications
-
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
-
Document addressing and delivery:
- How public/followers-only/direct addressing works
- Shared inbox support
- Relay support
-
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:
- Federation philosophy
- Inbox behavior (what the server does when receiving various activities)
- Web application-triggered activities (what the server sends in response to user actions)
Early Adoption Timeline
| Date | Event |
|---|---|
| January 5, 2020 | Darius Kazemi proposes FEDERATION.md on SocialHub |
| January 9, 2020 | WriteFreely becomes first adopter |
| February 4, 2020 | Zot (Hubzilla family) adopts |
| February 8, 2020 | Discussed at W3C Social CG meeting |
| March–October 2020 | tavern, Smithereen, Lemmy adopt |
| April 2023 | silverpill proposes FEP-67ff (~12 implementations) |
| September 5, 2023 | FEP-67ff received as DRAFT |
| September 22, 2024 | FEP-67ff achieves FINAL status |
| Present | 40+ 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:
| Project | Category |
|---|---|
| Mastodon | Microblogging |
| Pleroma / Akkoma | Microblogging |
| GoToSocial | Microblogging |
| Pixelfed | Photo sharing |
| PeerTube | Video sharing |
| Lemmy | Link aggregation |
| BookWyrm | Book reviews |
| WriteFreely | Long-form writing |
| Friendica | Social networking |
| Hubzilla | Social networking |
| Funkwhale | Music sharing |
| WordPress ActivityPub | Blogging plugin |
| Mitra | Microblogging |
| Smithereen | Social networking |
| Bonfire | Social networking |
10. Capability Discovery Landscape
FEDERATION.md addresses documentation but not machine-readable discovery. Several other FEPs tackle the machine-readable side:
| FEP | Approach | Machine-readable? | Status |
|---|---|---|---|
| FEP-67ff | FEDERATION.md documentation | No (human only) | FINAL |
| FEP-c893 | DOAP JSON-LD companion file | Yes | DRAFT |
| FEP-6481 | IRI list in NodeInfo metadata | Yes | WITHDRAWN |
| FEP-9fde | Reverse-FQDN operations in NodeInfo | Yes | DRAFT |
| FEP-eb22 | Type lists in NodeInfo | Yes | DRAFT |
| FEP-844e | Capability URIs on AP actors | Yes | DRAFT |
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.repositoryfield 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 actorfollowers— anOrderedCollectionof actors who follow this actorfollowing— anOrderedCollectionof actors this actor followsmanuallyApprovesFollowers—false= open/unlocked account (auto-accepts);true= locked account (requires manual approval). Defined in the ActivityPub Miscellaneous Terms asas: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
objectis the actor being followed (Bob) - The
actoris the one initiating the follow (Alice) - The
idshould 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
followingcollection tentatively, or wait until theAcceptarrives — implementations differ
Step 2: Bob's server receives the Follow
On receiving the Follow in Bob's inbox, Bob's server:
- Validates the HTTP Signature on the request (to confirm it came from Alice's server)
- Checks whether Bob has
manuallyApprovesFollowers: trueorfalse - 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
followingcollection - Bob's server adds Alice to Bob's
followerscollection - 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:
| Visibility | to | cc |
|---|---|---|
| Public | as:Public | followers collection |
| Unlisted | followers collection | as:Public |
| Followers-only | followers 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
Followactivities 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 anAcceptactivity) orReject(sending aRejectactivity, 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
-
New account declares
alsoKnownAspointing to the old account:{ "type": "Person", "id": "https://new.example/users/alice", "alsoKnownAs": ["https://old.example/users/alice"] } -
Old account sends a
Moveactivity 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" } -
Receiving servers (i.e. servers that have followers of the old account) automatically re-issue a
Followfrom 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
alsoKnownAsmust be set on the new account before theMoveis sent from the old account, or receiving servers may reject it
9. Common Implementation Mistakes
- Not waiting for
Acceptbefore adding tofollowing: Adding the followee tofollowingbefore theAcceptarrives means the collection is inaccurate for locked accounts - Not handling silent
Reject: If a locked account never sends aReject, the pending state must time out gracefully - Not validating HTTP Signatures on incoming
Followactivities: anyone could POST a fakeFollowto your inbox - Sending
Acceptto the wrong URL: TheAcceptmust be delivered to theinboxof the Follow'sactor, not theobject - Not using
sharedInbox: Sending one request per follower per instance instead of usingsharedInboxcauses serious performance problems at scale - Forgetting to handle
Undo Follow: When Alice unfollows Bob, Bob's server must remove Alice from thefollowerscollection, 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
| Direction | Activity | Required action |
|---|---|---|
| Outgoing follow | Send Follow to target's inbox | Add to local pending state |
Incoming Accept | Receive in own inbox | Move from pending → active; add to following |
Incoming Reject (or silence) | Receive in own inbox (or timeout) | Remove from pending |
Incoming Follow | Receive in own inbox | Queue or auto-accept; send Accept/Reject |
Outgoing Accept | Send to follower's inbox | Add follower to followers collection |
| Outgoing unfollow | Send Undo{Follow} to target's inbox | Remove from following |
Incoming Undo Follow | Receive in own inbox | Remove actor from followers collection |
| Delivering posts | POST 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
Followrequests 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:
- User sends
Followto the group's inbox - Group auto-accepts with an
Accept{Follow}(public groups SHOULD do this) - User is added to the group's
followerscollection - 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 addresseesattributedTo— 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
- Alice creates a post and sends
Create{Page}to the group's inbox - The group validates the activity (checks blocks, permissions)
- The group wraps it:
Announce{Create{Page}} - The group sends the
Announceto 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
audienceproperty 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.
| Implementation | Sends | Accepts |
|---|---|---|
| Lemmy | Announce(Activity) + Announce(Object) for Mastodon compat | Both |
| Friendica | Announce(Object) | Both |
| Hubzilla | Announce(Object) | Both |
| NodeBB | Announce(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-1b12 | FEP-400e | |
|---|---|---|
| Mechanism | Group wraps activities in Announce | Actors send Add to group's wall collection |
| Group identification | audience property | wall property on Group actor |
| Content distribution | Group sends Announce to followers | Group sends Add to followers |
| Detection | Check for Group type + audience usage | Check for wall property on actor |
| Status | FINAL | — |
| Adoption | Lemmy, Friendica, Hubzilla, Lotide, PeerTube, Kbin, NodeBB | Smithereen (~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
| Platform | Group Type | audience | Announce wrapping | Moderation | Notes |
|---|---|---|---|---|---|
| Lemmy | Community = Group | Yes (since 0.17.0) | Announce(Activity) + Announce(Object) | Full (attributedTo) | Reference implementation |
| Friendica | Forum = Group | Yes | Announce(Object) | Yes | Federated forums since 2019.03 |
| Hubzilla | Forum = Group | Yes | Announce(Object) | Yes | Workaround for Mastodon compat |
| Lotide | Community = Group | Yes | Yes | — | — |
| PeerTube | Channel = Group | Yes | Yes | — | Video-oriented |
| Kbin/Mbin | Magazine = Group | Yes | Yes | Yes | Lemmy-compatible |
| NodeBB | Category = Group | Yes (deviation) | Announce(Object) | — | Categories only; audience at 2nd-order parent |
| Guppe | Auto-group = Group | No | Announce(Object) | No | ~200 lines; simplest possible group (boost bot) |
| Mastodon | Pending | No | No (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
audiencematches 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:
- Verifies the
Announcecame from the group (HTTP Signature check) - Extracts the inner
Create{Page} - Displays the post in the Technology community feed
- The
Announcewrapper 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 inname, not in HTML content. - Delete vs Remove: Use
Removefor moderation actions, notDelete.Deleteimplies 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
wallproperty.
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 aLinksubtype)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:
tagarray — the structured metadata, used by receiving servers to index the post under that tagcontentfield — the HTML body, where hashtags appear as<a>links withrel="tag"andclass="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
namefield may preserve the original capitalisation the author typed ("#Eclipse2024") or may be lowercased
Mastodon's behaviour:
- Stores tags lowercased internally
- The
namefield in the outgoing ActivityPub object reflects the database canonical form, not necessarily what the author typed hrefis 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:
| Platform | Tag 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
tagarray entry: including#hashtagincontentHTML but omitting the structuredHashtagentry intag— receiving servers may not index it - Wrong
hrefhost: pointinghrefat a different server's tag page rather than the originating server's - Including
#inhref: thehrefURL path should not contain#, which is a URL fragment character — use/tags/catsnot/tags/#cats - Omitting
nameprefix: some implementations send"name": "cats"without the#— conventions vary, but including#is more common and matches Mastodon's behaviour - Case mismatch:
hrefis lowercase butnamehas mixed case — this is acceptable but can cause confusion; be consistent - Not including
Hashtagin@context: sending"type": "Hashtag"without declaring it in@contextmeans strict JSON-LD parsers will reject or ignore it
8. Summary: What a Correct Implementation Looks Like
A server that correctly implements hashtags should:
- Parse incoming
tagarrays, identify entries withtype: "Hashtag", and index the post under the normalised (lowercased) tag name - When creating a post with hashtags, populate both the
tagarray (structured metadata) and thecontentHTML (linked#taganchors) - Declare
Hashtagin the@contextof outgoing objects - Expose a tag timeline page at a stable URL (typically
/tags/{name}) - Set the
hrefof eachHashtagentry to point to that tag timeline page - Optionally expose an RSS feed at
/tags/{name}.rss - Optionally expose an Atom feed at
/tags/{name}.atom - 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:
publicKeymay be a single object, a single id string, or an array- The key object's
idis thekeyIdused in theSignatureheader owner(orcontroller) 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
publicKeyin the actor; if it's an array, find the entry whoseidmatches the fullkeyIdincluding the fragment - Verify the key's
idmatches the originalkeyIdexactly
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
publicKeyPemand anowner(orcontroller) property - Follow
ownerto 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/actorhttps://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:
- Verification fails with the cached key
- Re-fetch the actor document from the source (bypass cache)
- Retry verification with the new key
- 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:
| Implementation | Interpretation of hs2019 |
|---|---|
| Mastodon | RSA-SHA256 |
| PeerTube | RSA-SHA512 |
| GoToSocial | Signs as RSA-SHA256; verifies RSA-SHA256, RSA-SHA512, Ed25519 in order |
| Lemmy | Sends 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:
| Implementation | Tolerance window |
|---|---|
| Mastodon | ±1 hour (CLOCK_SKEW_MARGIN), max 12 hours (EXPIRATION_WINDOW_LIMIT) |
| Pleroma/Akkoma | Up to 2 hours old, max 40 minutes in the future |
| SWICG recommendation | ~1 hour plus a few minutes buffer |
| Some implementations | As 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
| Implementation | keyId format | Dereferencing |
|---|---|---|
| Mastodon | Fragment URI: …/users/alice#main-key | Returns full actor; key identified by fragment |
| GoToSocial | Path URI: …/users/alice/main-key | Returns 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:
| Library | Used by |
|---|---|
@peertube/http-signature (npm) | PeerTube, Misskey |
pleroma/http_signatures (Elixir) | Pleroma, Mobilizon |
| Everyone else | Custom 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:
- Clock skew — is the
Dateheader within tolerance? Check NTP on both servers. - Trailing newline — is the signing string missing a trailing
\n, or does it have one it shouldn't? - Header name case — are all header names lowercased in the signing string?
(request-target)construction — is itmethod_lowercase + " " + path? Does path include or exclude query string? (Try both.)- Digest mismatch — does the
Digestheader match the actual body? Empty body is not the same as no body. - Base64 encoding — is the signature standard base64 with padding and no embedded newlines?
keyIdresolution — does the fetched key'sidmatch thekeyIdexactly (including fragment)?- Key rotation — is the cached key stale? Try re-fetching the actor.
- Reverse proxy — is the
Hostheader being rewritten before the application sees it? - Algorithm mismatch — if remote is PeerTube, try RSA-SHA512 in addition to RSA-SHA256.
10. Minimum Required Headers (Consensus)
| Request type | Required 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
@contextitself - An alias is defined in
@contextas"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:
- All property names become full IRIs
- All values are wrapped in arrays
- String/number values become
{"@value": ...}objects - IRI references become
{"@id": ...}objects @typevalues become full IRIs inside an array@idstays as a string (the only property that does NOT become an array)- The
@contextis 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
- Expand incoming documents to normalize them
- Process the expanded data — all values are in predictable arrays
- 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:
| Plain | Language map | Purpose |
|---|---|---|
content | contentMap | Post body (HTML) |
name | nameMap | Display name / title |
summary | summaryMap | Content 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
| Approach | Implementations | How it works |
|---|---|---|
| Full JSON-LD processing | GoToSocial | Parses JSON-LD properly; maps IRIs to struct fields |
| Partial JSON-LD | Mastodon, Pleroma/Akkoma | Uses JSON-LD library for LD Signatures / canonicalization; otherwise treats as plain JSON |
| Plain JSON | Most others | Ignores @context; looks up properties by short name |
Why most skip JSON-LD processing
- Complexity — full JSON-LD processing is hard to implement correctly. The expansion algorithm alone can take weeks.
- Remote context fetching — JSON-LD may reference remote context documents, introducing latency and security risks.
- 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.
- Mastodon compatibility — most implementations just match Mastodon's output format rather than handling arbitrary JSON-LD.
What breaks when you skip JSON-LD
- Extensions — custom properties from other implementations' own
@contextentries may not be understood, or worse, may collide if two extensions use the same short name for different things. - Value form variability — an implementation expecting a string
will crash on an array (Mastodon
inReplyTobug #25588). - 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 Type | Purpose |
|---|---|
application/ld+json; profile="https://www.w3.org/ns/activitystreams" | Full JSON-LD with ActivityStreams profile (MUST accept per spec) |
application/activity+json | ActivityStreams-specific (SHOULD accept per spec) |
application/json | Generic 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:
- Convert the JSON-LD document to canonical form using the URDNA2015 (or similar) canonicalization algorithm
- Hash the canonical form with SHA-256
- 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/activitystreamshttps://w3id.org/security/v1https://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
- If the value is a string, treat as-is (plain value or IRI depending on the property definition)
- If the value is an object with
@idorid, extract the IRI - If the value is an object with
@value, extract the literal value - If the value is an array, apply the above rules to each element
- If the value is null or missing, treat as absent
- Never assume a property will always be a specific form
Properties that commonly vary in form
| Property | May appear as |
|---|---|
inReplyTo | string, array, object, null |
to / cc | string, array |
tag | object, array of objects |
attachment | object, array of objects |
attributedTo | string, object, array |
icon / image | string, object, array |
url | string, object, array |
13. Common Implementation Mistakes
- Assuming
idand@idare different properties: they are aliases in the ActivityStreams context — identical semantically. Accept both, produceid - 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
@contextin 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
@idand@typein 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 thatcontentalone does not. PrefercontentMapwhen available - Not handling the
@contextarray form:@contextcan 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
contentandcontentMapas 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 anUndo.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 andccthe 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:
- Server checks the object exists.
- Server checks the object is not already in the actor's
likedcollection. - Server checks the actor has permission to view the object (is an
addressee of the object or its
Createactivity). - Server checks the actor is not blocked by the object's responsible actor.
- If all checks pass:
- Add the object to the actor's
likedcollection. - If the object is local: add the
Likeactivity to the object'slikescollection directly. - If the object is remote: deliver the
Likeactivity to the inbox of the actor responsible for the object (typicallyattributedTooractoron the object).
- Add the object to the actor's
4. Server-to-Server Flow (S2S)
When a remote server delivers a Like to your inbox:
- Check the
objectexists on the local server. If it doesn't (e.g. it's on a third server), theLikecan be treated as having no side effects and quietly ignored. - Check no
Likefrom this actor already exists in the object'slikescollection (deduplicate by actor id). - Check the responsible actor for the object has not blocked the liking actor.
- Check the liking actor has permission to view the object.
- If all checks pass: add the
Likeactivity to the object'slikescollection 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
Likeactivity must exist (in thelikescollection). - The actor of the
Undomust be the same as the actor of theLike. - The
objectof theLikemust 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) andlikes(object side) are treated as unique by the relevant id (object id and actor id respectively). - Originating servers should avoid sending duplicate
Likeactivities. - Receiving servers should silently ignore all but the first
Likefrom 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.
EmojiReactis distinct fromLike— a user can bothLikeandEmojiReactto the same post; they are separate.- Duplicate reactions (same actor, same emoji) MUST be silently ignored.
- Unicode emoji:
tagMAY be omitted. - Custom emoji:
contentcontains the shortcode with colons (:blobcat:);tagcontains theEmojiobject 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_reactioncontains the shortcode (:blobcat:@.for local or:blobcat:@misskey.examplefor remote); the emoji image is resolved separately.
9.3 Interoperability between the two approaches
| Pleroma/Akkoma (EmojiReact) | Misskey-lineage (Like + _misskey_reaction) | |
|---|---|---|
| Activity type | EmojiReact (new type) | Like (standard type, extended) |
| Multiple reactions per post | Yes (different emoji) | No (one per user) |
| Distinct from plain Like | Yes | No |
Custom emoji in tag | Yes | Shortcode in _misskey_reaction |
| Standard | FEP-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:
- Likes are delivered only to the post's author's server. They are not broadcast to every server that has seen the post.
- 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
totalItemscount in thelikescollection — but that count is a snapshot, not a live feed. - The receiving server typically does not subscribe to updates of the remote
likescollection. Counts only update if the server re-fetches the object. - 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
likescollection 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
likedURL 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
| Activity | Sent to | Effect |
|---|---|---|
Like | Author's inbox | Adds to object's likes collection; notification to author |
Undo{Like} | Author's inbox | Removes from likes collection |
EmojiReact (FEP-c0e0) | Author's inbox | Adds emoji reaction; ignored by non-supporting servers |
Undo{EmojiReact} | Author's inbox | Removes emoji reaction |
Like + _misskey_reaction | Author's inbox | Misskey reaction; treated as plain Like by others |
Dislike | Author's inbox | PeerTube 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 paragraphArticle— 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 &), 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
Linkobject withmediaType: "text/html"andhref - 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):
- Manual user-defined summary (preferred)
- Use full text if it is ~500 chars and a single paragraph
- Use first paragraph if it meets the rough guidelines
- 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:
| Element | Allowed 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):
dcterms:subject— Dublin Core subject string(s). Most informative and least likely to leak sensitive content.tag— Hashtag names. Less human-readable than subject.name— Title. Authors may leak sensitive material here.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) andsummary - 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
imagemay be included asattachmentin 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 Property | RSS 2.0 Equivalent |
|---|---|
id | guid |
name | title |
url | link |
summary | description |
attributedTo | author |
published | pubDate |
replies | comments |
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)
| Platform | Sends Article | Uses summary | Uses preview | Notes |
|---|---|---|---|---|
| WordPress (AP plugin) | Yes | Yes | — | Historically sent Note as workaround; now sends Article |
| Ghost | Yes | Yes | — | Active SWF participant; Ghost 6 has full AP integration |
| WriteFreely / Write.as | Yes | Yes | — | PR for FEP-b2b8 support discussed May 2025 |
| Plume | Yes | Yes | — | Early Article adopter |
| NodeBB | Yes | Yes | — | Switches between Note/Article by length; magic string for summary breaks |
| Bonfire | Yes | Yes | — | Adopted FEP-b2b8 as technical foundation |
Consuming platforms (display Article type)
| Platform | Article display | Notes |
|---|---|---|
| Mastodon | Title + link only | First-class types are Note and Question only; Article gets degraded display |
| Threads | Full display | Announced support for long-form Ghost content (2025) |
| Pleroma/Akkoma | Inline display | Supports rich text in both Note and Article |
| GoToSocial | Inline display | Treats summary as content warning (not teaser) |
| Bonfire | Full display | Dedicated "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
summaryas 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 inname, 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
previewis 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
| Property | Description |
|---|---|
software | Name, version, homepage, repository |
protocols | Supported protocols (e.g., ["activitypub"]) |
services | Inbound and outbound service integrations |
openRegistrations | Whether new accounts can be created |
usage | User counts, local post count |
metadata | Free-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
| Aspect | FEP-6481 | FEP-9fde |
|---|---|---|
| Scope | ActivityPub extensions only | Any server operation |
| Identifiers | IRIs with fragment versioning | Reverse-FQDN strings |
| Versioning | Fragment identifiers (#v1) | Semver arrays (["1.0.0"]) |
| Location | metadata.activitypub.extensions | operations property |
| Granularity | Per-extension | Per-operation |
| Status | WITHDRAWN | DRAFT |
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
| FEP | Approach | Machine-readable? | Status |
|---|---|---|---|
| FEP-6481 | IRI list in NodeInfo metadata | Yes | WITHDRAWN |
| FEP-9fde | Reverse-FQDN operations in NodeInfo | Yes | DRAFT |
| FEP-eb22 | Type lists in NodeInfo | Yes | DRAFT |
| FEP-844e | Capability URIs on AP actors | Yes | DRAFT |
| FEP-67ff | FEDERATION.md documentation | No (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:
- Send standard activities with custom types to servers that declare support
- 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
- Use FEDERATION.md (FEP-67ff, FINAL) to document your extensions in human-readable form
- Add NodeInfo metadata for machine-readable discovery — use the
FEP-9fde
operationsformat if your framework supports it, or add custom metadata keys as a stopgap - Always provide fallback content — post standard Note/Article types alongside or instead of custom types for maximum compatibility
- 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:
- Prefer extending standard types with additional properties over creating entirely new types
- If you must create custom types, also send compatibility objects (standard types with a text description) for servers that don't understand your extensions
- Define a JSON-LD context for your extensions so they are properly namespaced
- 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
- No FINAL solution — all machine-readable capability discovery proposals remain DRAFT or WITHDRAWN
- NodeInfo vs actor-based — unresolved debate about whether capability data belongs in NodeInfo (server-level, protocol-agnostic) or on ActivityPub actors (protocol-native)
- 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
- Custom types vs extended standard types — the community hasn't reached consensus on the right extensibility pattern
- Mastodon's alternative — Mastodon introduced
api_versionsas a lighter-weight capability signal, potentially diverging from FEP-based approaches - 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:
-
Private content is inaccessible — if someone on
podunk.edushares a private video only withbob@example.com, Bob cannot view it by visitingpodunk.edu. The server doesn't know he's Bob. -
Remote profiles are limited — when jumping from instance to instance, users lose their identity. They can't interact natively with content.
-
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.
-
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.socialto log intoexample.comassomeone@example.social, andexample.comdetermines whatsomeone@example.socialcan do onexample.com. Butexample.comcannot impersonatesomeone@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:
- Login form — user visits the target instance and submits their
Fediverse ID (e.g.,
alice@example.social) via a login form 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:
- Verifies the user has a valid session cookie (i.e., is logged in)
- Decodes the
bdestURL from hex - Performs a WebFinger lookup for the target's token endpoint, seeking
rel="http://purl.org/openwebauth/v1" - Sends an HTTP-Signature-signed request to the token endpoint
- Includes an
X-Open-Web-Authheader with a random string for additional entropy - 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:
- Extracts the
keyIdfrom the signed request'sAuthorizationheader - Fetches the actor record and public key via the
keyIdURL - Verifies the HTTP signature
- Generates a URL-safe random token string
- Stores the token locally (with a short expiry, typically minutes)
- Encrypts the token using the actor's public key with RSA PKCS #1 v1.5
- Encodes the encrypted result as URL-safe Base64 without padding
- 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:
- Decodes the JSON response
- Verifies
"success": true - Decrypts the Base64-encoded token using the actor's private key
- Redirects the user's browser to:
<bdest>?owt=<decrypted-token>
Step 5: Target Instance Validates Token and Logs In
The target instance:
- Extracts the
owtquery parameter - Matches it against the token stored in Step 3
- If valid, logs the user in as the remote identity
- 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:
| Relation | Purpose | Published by |
|---|---|---|
http://purl.org/openwebauth/v1#redirect | Redirect endpoint (Step 1) | Home instance |
http://purl.org/openwebauth/v1 | Token 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
| Operation | Key used | By whom |
|---|---|---|
| Sign token request (Step 2) | Private key | Home instance |
| Verify signature (Step 3) | Public key | Target instance |
| Encrypt token (Step 3) | Public key | Target instance |
| Decrypt token (Step 4) | Private key | Home 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:
- First redirect (target → home): validates that the hostname matches the claimed identity
- Second redirect (home → target): validates that the token endpoint
origin matches the
bdestorigin - 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
| Aspect | OpenWebAuth (FEP-61cf) | OAuth 2.0 / OIDC (FEP-d8c2) |
|---|---|---|
| Purpose | Authentication (identity) | Authorization (permissions) |
| Scope | Browser-based SSO only | Multi-platform (browser, mobile, API) |
| Complexity | Simple — WebFinger + HTTP Sig + token | Complex — client registration, scopes, refresh tokens |
| Client registration | None required | Required (RFC 7591) |
| Fediverse implementations | 5+ servers | Mastodon's partial OAuth (non-compliant RFC 7591) |
| Private key usage | Home instance only | Client + server |
| Target can act as user? | No — authentication only | Yes — 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)
| Implementation | Status | Since |
|---|---|---|
| Hubzilla | Implemented | 2017 (v2.8) |
| (streams) | Implemented | 2021 |
| Forte | Implemented | 2024 |
| Friendica | Partial | ~2023 |
| FedIAM | Implemented | 2024 |
| Mastodon | Proposed (issue #7643) | — |
| Pixelfed | Proof-of-concept | — |
Relying Parties (Accepting OWA)
| Implementation | Status |
|---|---|
| Hubzilla | Implemented |
| (streams) | Implemented |
| Forte | Implemented |
| FedIAM | Implemented |
| Bridgy Fed | Proposed |
| Great Ape | Proposed |
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)
- Advertise your redirect endpoint via WebFinger with
rel="http://purl.org/openwebauth/v1#redirect" - Implement the redirect endpoint (traditionally
/magic):- Check the user's session cookie
- Decode the
bdestparameter from hex - Discover the target's token endpoint via WebFinger
- Send an HTTP-Signature-signed request with
X-Open-Web-Authheader - Decrypt the returned token with the actor's private key
- Redirect the browser to
bdest?owt=<token>
- On failure at any step, return an HTTP error — never redirect
Accepting as a Relying Party (Target Instance)
- Advertise your token endpoint via WebFinger with
rel="http://purl.org/openwebauth/v1" - Implement the token endpoint:
- Extract
keyIdfrom theAuthorization: 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>"}
- Extract
- On pages that accept
owt=parameter:- Match the token against stored tokens
- Log the user in as the remote identity
- Delete the token immediately
- Implement a login form or
zid=parameter handling to trigger the flow - 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:
- Always check WebFinger first for the redirect/token endpoints
- Only fall back to
/magicfor backward compatibility with older Hubzilla/Streams instances - Consider using
/.well-known/open-web-authfor new implementations (proposed by benpate but not yet standardized)
Known Issues and Open Questions
- DRAFT status — FEP-61cf has not reached FINAL; the spec may change
- Browser-only — no support for mobile apps, API clients, or desktop applications (unlike OAuth/OIDC)
- Privacy concern — home instance learns every target the user visits; most implementations don't show consent screens
- Mastodon architectural gap — supporting accountless remote users requires fundamental changes to Mastodon's data model
- Hardcoded
/magicpath — conflicts with CMS installations; WebFinger-first discovery should become primary - Missing spec details — cookie-based login verification and activity attribution to home instance actors are implementation requirements not fully documented in the FEP
- 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
- 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
zprefix indicates base58-btc Multibase encoding - No resolution infrastructure needed — the public key IS the identifier
- Implementations MUST support
did:keywith 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— wrapsdid:keydid:ap:web— wrapsdid:webdid:ap:pkh— wrapsdid: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:
- Taking the
ap://URI - Removing the
ap://prefix - 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
- Canonicalize the ActivityPub object using JSON Canonicalization Scheme (JCS, RFC 8785) for deterministic serialization
- Hash the canonicalized output with SHA-256
- Construct a
DataIntegrityProofspecifyingeddsa-jcs-2022(EdDSA signing with SHA-256 hashing and JCS canonicalization) - Concatenate the proof hash and document hash
- Sign with EdDSA and encode the 64-byte signature as Multibase
Verification
- Extract the
prooffrom the object - Reconstruct the document hash (without the proof)
- Reconstruct the proof hash
- 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:
assertionMethodproperty (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:
| FEP | Name | Role |
|---|---|---|
| FEP-521a | Public Key Representation | Multibase key encoding on actors |
| FEP-8b32 | Object Integrity Proofs | Cryptographic signing of objects (eddsa-jcs-2022) |
| FEP-c390 | Identity Proofs | Linking HTTPS actors to DIDs via VerifiableIdentityStatement |
| FEP-fe34 | (unnamed) | Origin-based security model |
| FEP-ef61 | Portable Objects | Server-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 model | Channel-based, server-independent | DID-based, server-independent |
| Object IDs | Server-independent | ap:// URIs with DID authority |
| Multi-homing | Native (clone channels across servers) | Via gateways property |
| Integrity | Protocol-level | FEP-8b32 Data Integrity proofs |
| Migration | Seamless (nomadic) | Update gateways list |
| Adoption | Hubzilla, Streams only | Growing (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
| Platform | FEP-ef61 Support | Details |
|---|---|---|
| Streams | Full | First to implement; built by Mike Macgirvin (Zot/Nomad creator) |
| Mitra | Gateway | Gateway config (disabled by default), resolver endpoint, portable inboxes/outboxes with DID signatures, portable Like activities |
| Forte | Noted | Listed as implementation |
| tootik | Noted | Listed as implementation |
| fep-ae97-client | Client | Client-side implementation |
| Fedify | Requested | Feature request (issue #288); FEP-8b32 dependency already available |
| Hollo | Requested | Feature request (issue #211) |
| Mastodon | None | No 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:apmethod registry: Thedid:ap:keysyntax (nesting DID methods) is controversial. Whetherdid:apcan be registered as a formal DID method is debated.aliasesvsalsoKnownAs: The property naming conflict between DID and Mastodon semantics is unresolved. FEP-d2da (pre-draft) proposes extractingaliasesinto 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
inboxis where subscribing servers send activities - The
publicKeyis used for HTTP Signature verification - Most relay implementations also expose
/.well-known/webfinger,/.well-known/nodeinfo, and/nodeinfo/2.0for 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
objectfield must be exactly"https://www.w3.org/ns/activitystreams#Public"— this is what distinguishes a relay subscription from a normal user follow - The
actormust resolve to an object with bothinboxandendpoints.sharedInboxproperties - 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/Acceptflow 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
| Platform | Subscription 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(intoorcc) 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:
| Endpoint | Method | Purpose |
|---|---|---|
/actor | GET | Returns the relay's ActivityPub actor document |
/inbox | POST | Receives activities from subscribers |
/.well-known/webfinger | GET | WebFinger discovery |
/.well-known/nodeinfo | GET | NodeInfo discovery document |
/nodeinfo/2.0 | GET | NodeInfo 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
#ddcaptures#dd1302etc.) - 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:
- Serve an actor document at a stable URL with a valid
publicKey,inbox, andendpoints.sharedInbox - Accept
Followactivities where theobjectisas:Public— validate HTTP Signatures, store the subscriber, and respond withAccept - Accept
Undo{Follow}— remove the subscriber - Accept incoming activities at the inbox — validate that they are addressed to Public, then distribute to all subscribers
- Distribute activities — for each subscriber, POST the activity
(or an
Announcewrapping it) to the subscriber'ssharedInbox - Sign all outgoing requests with HTTP Signatures using the relay actor's private key
Activity types to handle
| Incoming activity | Relay action |
|---|---|
Follow (object = as:Public) | Store subscriber; send Accept |
Undo{Follow} | Remove subscriber |
Create | Wrap in Announce; deliver to all subscribers |
Announce | Wrap in Announce or forward; deliver to all subscribers |
Update | Forward directly to all subscribers |
Delete | Forward directly to all subscribers |
Like | Forward directly to all subscribers |
Undo (other than Follow) | Forward directly to all subscribers |
Move | Forward directly to all subscribers |
Add / Remove | Forward directly to all subscribers |
Delivery optimisation
- Always use
sharedInboxwhen 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
- Log in with admin credentials
- Navigate to Preferences > Administration > Relays
- Select "Setup A Relay Connection"
- Enter the relay URL with the
/inboxsuffix (e.g.https://relay.example.com/inbox) - Click "Save And Enable"
- 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
| Software | Language | Protocol Support | Key Feature |
|---|---|---|---|
| pub-relay | Crystal | Mastodon + LitePub | Rigorous HTTP Signature verification; LD-signature-aware forwarding |
| Activity-Relay | Go | Mastodon + LitePub | Redis-backed job queue; CLI admin; YAML config |
| ActivityRelay (Pleroma) | Python | LitePub | Mature (14 releases); configurable DB backends |
| aode-relay | Rust | Mastodon + LitePub | Lightweight; blocklist/allowlist; Prometheus metrics; Telegram admin bot |
| buzzrelay (FediBuzz) | Rust | Follow-only | Streaming 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
objectin theFollow: subscribing with the relay actor's id as theobjectinstead ofas:Public— the relay will treat this as a normal follow, not a relay subscription - Missing
sharedInbox: if the subscribing server's actor does not exposeendpoints.sharedInbox, the relay may not be able to deliver activities - Not handling both subscription protocols: if building a relay,
accept subscriptions at both
/inboxand/actorto support all platforms - Wrapping
DeleteinAnnounce: forwarding aDeleteasAnnounce{Delete}changes its semantics —Deleteshould 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
/actorendpoint: serving only/inboxand not an actor document at/actorbreaks 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:
- Construct the query:
https://domain/.well-known/webfinger?resource=acct:user@domain - Parse the JRD (JSON Resource Descriptor) response
- Extract the
hreffrom the link withrel="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:
-
preferredUsernameis optional — it is not a required property in the ActivityPub specification, so it may be absent entirely. -
Domain mismatch — organizations may want WebFinger addresses on a different domain than where their ActivityPub server runs. For example,
alice@company.tldwhile the AP server is atsocial.company.tld. The current approach constructsalice@social.company.tldinstead. -
Semantic overload —
preferredUsernameserves 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
preferredUsernameis 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:
- Perform a WebFinger lookup on the stated address
- The JRD response MUST contain a
selflink whosehrefmatches the actor'sidURL exactly - 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":
- Query
https://company.tld/.well-known/webfinger?resource=acct:alice@company.tld - 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" } ] } - Confirm
hrefequals the actor'sid— validation passes
Security Considerations
The webfinger property should only be trusted when:
- It comes from dereferencing the actor's
idURL 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:
- Extract
preferredUsernameand the hostname from the actor'sidURL - Construct
acct:preferredUsername@hostname - Perform a WebFinger lookup to verify the address resolves back to the same actor
- If the JRD
subjectdiffers 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
preferredUsernameis absent from the actor- The WebFinger domain differs from the actor URL domain
- The actor URL uses subdomains or non-standard paths
preferredUsernamecontains 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
webfingerfield
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
| Specification | Relationship |
|---|---|
| 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-d556 | Complementary proposal for server-level actor discovery via WebFinger (vs FEP-2c59's user-level focus) |
| W3C SWICG "ActivityPub and WebFinger" report | Acknowledges the reverse discovery problem; does not reference FEP-2c59 by name |
Implementation Guidance
If You Are Building a New ActivityPub Server
- Include the
webfingerproperty on all actor objects - Add
https://purl.archive.org/socialweb/webfingerto the@context - Set the value to the canonical
user@domainaddress (with or withoutacct:prefix) - Ensure your WebFinger endpoint returns a JRD with a
selflink pointing to the actor'sidURL
If You Are Consuming ActivityPub Actors
- Check for the
webfingerproperty first - If present, validate it by performing a forward WebFinger lookup and
confirming the
selflink matches the actor'sid - If absent, fall back to the
preferredUsername+ hostname approach - 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 expectuser@domain) - Do not assume
preferredUsernameexists — it is optional - Do not assume the WebFinger domain matches the actor URL domain
Known Issues and Open Questions
- DRAFT status — FEP-2c59 has not reached FINAL status; no implementations are listed in the FEP itself
- No-redirect controversy — the prohibition on redirects during validation conflicts with RFC 7033's mandatory redirect support
- Property naming unresolved — whether
webfinger,webfingerAcct, oracctis the best name remains debated aliasesalternative — the community has not reached consensus on whether a dedicated property or thealiasesapproach is preferable- Mastodon adoption unknown — Mastodon has not indicated plans to adopt FEP-2c59
- JSON-LD context availability — the
https://purl.archive.org/socialweb/webfingercontext 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, optionalaliases, andlinksarray - Key link relation:
rel="self"withtype="application/activity+json"(orapplication/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
| Date | Event |
|---|---|
| July 2010 | Mike Macgirvin creates Mistpark in Australia, motivated by "Quit Facebook Day" privacy concerns |
| Mid-2010 | Within first month: federation with StatusNet (OStatus), RSS, email integration |
| Late 2010 | Renamed to Friendika |
| July 2011 | Zot protocol first named (Macgirvin's next-gen protocol design) |
| Sep 2011 | Macgirvin forks as "Free-Friendika" (MIT license) |
| Oct 2011 | Name changed to Friendica |
| Jan 2012 | First "Friendica" release (v2.37) |
| 2012 | Diaspora protocol reverse-engineered from scratch (~6 months) |
| May 2012 | Macgirvin departs, forks into Red / Friendica Red (MIT) |
| 2012-2013 | Red becomes Red Matrix |
| May 2015 | Red Matrix renamed to Hubzilla |
| Dec 2018 | ActivityPub support shipped |
| May 2023 | Initial Bluesky connector |
| Dec 2023 | Bidirectional Bluesky; Circles and Channels introduced |
| Jan 2025 | v2024.12: OStatus dropped, Prometheus metrics, FEP-67ff |
| Jan 2026 | v2026.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:
- No protocol for friend connections
- No privacy support in social protocols
- No cross-server wall posting
- Private media required sending copies to all recipients
2. Technology Stack
| Layer | Technology |
|---|---|
| Backend language | PHP (7.4+, 8.x recommended, supports 8.5) |
| Database | MariaDB (recommended), MySQL, PostgreSQL 9.6+ |
| Web server | Apache (mod-rewrite) or Nginx |
| Template engine | Smarty3 |
| Dependency management | Composer |
| DI container | Dice |
| Themes | frio (default), vier, quattro |
| License | AGPL-3.0 |
| Hardware minimum | 2 GB RAM |
| Required PHP extensions | Curl, 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 legacybin/worker.php)
Configuration Hierarchy (increasing priority)
static/defaults.config.php— system defaultsstatic/settings.config.php— admin-configurable defaultsconfig/local.config.php— instance-specific overridesconfigdatabase 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
| Protocol | Purpose | Since |
|---|---|---|
| ActivityPub | Federation with Mastodon, Pleroma, Pixelfed, PeerTube, Lemmy, etc. | Dec 2018 |
| Diaspora protocol | Federation with Diaspora pods, Hubzilla | 2012 |
| DFRN | Native Friendica-to-Friendica federation | July 2010 |
| WebFinger | User discovery | — |
| HTTP Signatures | Request authentication for ActivityPub | — |
| NodeInfo | Server metadata discovery | — |
| Salmon | Message exchange for replies and mentions | — |
Dropped
| Protocol | Dropped | Reason |
|---|---|---|
| OStatus (PubSubHubbub + Atom) | v2024.12 | Too 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.pdfin 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
| Endpoint | Purpose |
|---|---|
dfrn_request | Friend/contact requests |
dfrn_notify | Delivery (push) |
dfrn_poll | Feed retrieval (pull) |
Handshake
- Remote site POSTs to
dfrn_pollwithtype=profile-check - Includes duplex direction, relationship
dfrn_id, and a random number encrypted with the site's DFRN public key - Original site decodes
dfrn_id, verifies relationship, decodes challenge, matchessecstring
Delivery Model
- Public messages: dual path — BBCode to DFRN clients + HTML conversion with PubSubHubbub notification
- Private messages: direct delivery via
dfrn_notifyto recipients only; public hubs remain uninformed - Polling:
src/Worker/OnePoll.phpwith 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/:
| Class | Role |
|---|---|
| Receiver | HTTP Signature verification, activity validation, JSON decoding |
| Processor | Activity type handling (Create, Update, Delete, Like, Announce) |
| Transmitter | JSON-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)
| Network | Protocol |
|---|---|
| Mastodon, Pleroma, Pixelfed, PeerTube, Lemmy, Kbin, Misskey | ActivityPub |
| Diaspora, Hubzilla, Socialhome | Diaspora protocol |
| Other Friendica nodes | DFRN |
| IMAP4rev1 / ESMTP (bidirectional) | |
| Any website/blog | RSS/Atom feed import |
Addon Connectors (bidirectional)
| Network | Notes |
|---|---|
| Bluesky | No API key needed; bidirectional since v2023.12 |
| pump.io | Posting, relaying, reading |
| GNU Social | Via 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
| Feature | Details |
|---|---|
| Maximum length | 200,000 characters |
| Markup | BBCode (bold, italic, headings h1-h6, code blocks, tables, spoilers, lists) |
| Media | Images (with alt text, dimensions), video (YouTube/Vimeo/generic), audio, OEmbed |
| Albums | Photo albums with tagging and per-album privacy |
| Events | Date, time, location, RSVP |
| Forums | Public and private, federated |
| Polls | Limited (not supported via Diaspora protocol) |
| Notes | Private notebook (notes to self) |
| Maps | By address, coordinates, or post location |
| Abstract/summary | Per-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
| Table | Purpose |
|---|---|
item-uri | URI registry for deduplication |
post | Protocol-agnostic metadata (author-id, owner-id, created) |
post-user | Per-user states (starred, hidden, visibility) |
post-content | Body text |
post-media | Attachments with MIME types |
post-thread / post-thread-user | Thread structure |
post-history | Edit history |
post-delivery / post-delivery-data | Delivery tracking |
post-tag / post-category | Tags and categories |
post-question / post-question-option | Polls |
delayed-post | Scheduled 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
| Table | Purpose |
|---|---|
contact | Both local and remote actors |
apcontact | ActivityPub-specific contact data |
fcontact | Diaspora-specific contact data |
contact-relation | Relationship graph |
user-contact | Per-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
- Client Layer — browsers, mobile apps (Raccoon, Fedilab), third-party clients via Mastodon API
- Frontend Layer — theme system (frio/vier/quattro), JavaScript, localization
- Application Layer — Router with 600+ routes
(
static/routes.config.php), modules, API endpoints - Business Logic Layer — Model classes:
Item,Contact,User - Content Processing Layer — BBCode formatting, media processing, URL parsing
- Federation Layer —
Friendica\Protocol\ActivityPub,Friendica\Protocol\Diaspora,Friendica\Protocol\DFRN - Data Layer — Database abstraction (
DBA), schema management (DBStructure) - Background Processing — Worker queue with priority levels
Worker Queue
| Priority | Value |
|---|---|
| CRITICAL | 10 |
| HIGH | 20 |
| MEDIUM | 30 |
| LOW | 40 |
| NEGLIGIBLE | 50 |
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
| Category | Hooks |
|---|---|
| Content | post_local, post_local_end, post_remote, display_item, prepare_body |
| Auth | authenticate, logged_in, register_post |
| Profile | profile_post, profile_edit, profile_sidebar |
| Contacts | follow, unfollow, revoke_follow, block, unblock |
| Settings | addon_settings, connector_settings |
| System | init_1, load_config, route_collection |
| Federation | probe_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
- Git clone:
git clone -b stable+composer install --no-dev+ web installer - CLI:
bin/console autoinstallwith config file or env vars - Docker:
docker pull friendica(official image) - 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
| Feature | Friendica | Mastodon |
|---|---|---|
| Post length | 200,000 chars | 500 chars |
| Protocols | AP + Diaspora + DFRN + addons | AP only |
| Contact groups | Circles with ACLs | Lists (no ACLs) |
| RSS reader | Built-in | No |
| Photo albums | Yes | No |
| Events/calendar | Yes | No |
| Quote posts | Yes (early pioneer) | Added later |
| Forums | Yes (public + private) | No |
| BBCode | Yes | No |
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
Applicationinstance actor: Friendica uses an instance-level actor for some federation tasks — verify keys fromApplicationactors, not justPerson - 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
| Component | Technology |
|---|---|
| Backend | PHP 8.2+ |
| Framework | Symfony |
| Database | PostgreSQL |
| Message queue | RabbitMQ |
| Cache | Redis / KeyDB / Valkey |
| Real-time | Mercure (optional) |
| Frontend | Twig templates, SCSS, JavaScript |
| Image processing | GD or ImageMagick |
| Web server | Nginx, Apache, or Caddy |
| Deployment | Docker / Docker Compose |
| License | AGPL-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
| Type | Description | AP Object |
|---|---|---|
| Thread (link) | External links and articles with titles | Page |
| Thread (text) | Self-text discussion posts with titles | Page |
| Microblog | Short-form posts (like Mastodon) | Note |
| Comment | Replies to threads or microblogs | Note (with inReplyTo) |
| Private message | Direct messages between users | ChatMessage (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
Likeactivity - Downvote ("Reduce") — negative engagement, local only — does NOT federate
- Boost — reshare/reblog, federated as
Announceactivity
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
| Actor | Type | Path | Purpose |
|---|---|---|---|
| Instance | Application | /i/actor | Server-level actor, signs requests, inbox/outbox |
| User | Person | /u/username | Individual accounts with followers/following |
| Magazine | Group | /m/name | Community 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
| Activity | Purpose |
|---|---|
Follow | Subscribe to user or magazine |
Accept / Reject | Follow request responses |
Create | Create threads, microblogs, comments |
Update | Edit content |
Delete | Remove content |
Like | Upvote (no Dislike — downvotes are local only) |
Announce | Boost/reshare; also magazine relay wrapping |
Undo | Reverse Like, Follow, or Announce |
Block | Ban user (optional expiration timestamp, magazine-level or instance-level) |
Flag | Report content (sent to magazine moderators' instances only) |
Add / Remove | Moderator assignment, thread pinning |
Lock | Lock 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) andAnnounce(boost) are sent. NoDislikeactivity. - 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
Servicefor bot/robot accounts. - Accepts
application/jsonheaders across all ActivityPub endpoints (not justapplication/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:
- Register client:
POST /api/client→ returns identifier and secret - Request token → returns Bearer token, expiration, refresh token
- Include
Authorization: Bearer <token>on requests
Scopes
| Scope | Access |
|---|---|
read | Retrieve threads, view favorites |
write | All modification operations |
5. Kbin vs Lemmy
| Aspect | Kbin/Mbin | Lemmy |
|---|---|---|
| Language | PHP (Symfony) | Rust (Actix-web) |
| Content types | Threads + Microblogs | Threads only |
| Communities | "Magazines" | "Communities" |
| AP object (posts) | Page (threads) + Note (microblogs) | Page only |
| Mastodon integration | Strong — microblog section shows Mastodon content | Limited |
| Downvote federation | No (local only) | Yes (Dislike activity) |
| Mention federation | Better (Mbin) | Weaker |
| PeerTube integration | Direct channel following (Mbin v1.7+) | Limited |
| Third-party apps | Very limited | Many (Jerboa, Thunder, Voyager) |
| Governance | Community-driven (Mbin) | Lemmy team (2 primary devs) |
| Maturity | Newer (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
Dislikefor downvotes; Kbin/Mbin ignores them (or had historical display issues) - Kbin/Mbin microblog
Noteposts appear as comments in Lemmy (since Lemmy only understandsPagefor top-level posts) - Mention federation works better from Mbin than from Lemmy
6. History and the Mbin Fork
Kbin Timeline
| Date | Event |
|---|---|
| Dec 2022 | NLnet grant funding begins |
| Early 2023 | Project moves to Codeberg, development accelerates |
| Apr 2023 | kbin.social launches with a few hundred users |
| Jun 2023 | Reddit API crisis — kbin.social grows from 300 to 30,000+ users in one week |
| Jun 2023 | Emergency infrastructure: Fastly caching, Cloudflare, server upgrades |
| Late 2023 | Ernest begins pattern of weeks-to-months-long absences |
| Oct 2023 | Mbin fork created on GitHub |
| 2024 | kbin.social increasingly unstable, Ernest cites medical issues |
| Jun 2024 | Ernest promises instance handover, then goes silent again |
| Sep 2024 | kbin.social effectively ceases operation |
| Present | Kbin 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:
- Federation compatibility — major fixes to interoperability issues
- Performance and scaling — database optimizations, reduced background request overhead
- Security — up-to-date dependencies, security-first patching
- Documentation — hosted at docs.joinmbin.org
- Thread/microblog locking
- Discoverability and indexability settings
- PeerTube channel following (since v1.7)
- All ActivityPub Actor Types including
Servicefor bots - 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.
| Software | Language | Status | Differentiator |
|---|---|---|---|
| Lemmy | Rust | Active | Most mature (2019), most users |
| Mbin | PHP | Active | Threads + microblogs combined |
| PieFed | Python | Active | Privacy-focused voting, rapid development |
| Sublinks | Java | In dev | Lemmy-compatible alternative backend |
| Lotide | Rust | Limited | Minimal, 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
-
Threads arrive as
Pageobjects — same as Lemmy. If your software handles Lemmy'sPageposts, Kbin/Mbin threads will work the same way. Title is inname, body incontent/source. -
Microblogs arrive as
Noteobjects — 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 understandsPagefor top-level content. -
No
Dislikeactivity — Kbin/Mbin never sends downvotes over federation. If you receive aLikefrom a Kbin/Mbin instance, it's an upvote. You will never receive aDislike. If your platform sendsDisliketo a Kbin/Mbin instance, it may be ignored or cause display issues. -
Magazines are
Groupactors — follow a magazine by sendingFollowto the Group actor at/m/name. The magazine relays all content viaAnnounce, identical to Lemmy communities. -
ChatMessagefor DMs — Kbin/Mbin uses a customChatMessagetype for private messages, not standardNotewith direct addressing. Other platforms may not understand this type. -
Accepts
application/json— Kbin/Mbin accepts bothapplication/activity+jsonand plainapplication/jsonon all ActivityPub endpoints. No need to worry about content-type strictness. -
Report routing —
Flagactivities are sent only to instances that host the magazine's moderators, not broadcast widely. -
Ban expiration —
Blockactivities can include expiration timestamps and scope (magazine-level vs instance-level). Handle the expiration field if present. -
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.
-
Mastodon content in magazines — Kbin/Mbin's microblog section displays Mastodon posts matching magazine hashtags. This means Mastodon
Noteobjects 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
| Component | Technology |
|---|---|
| Backend language | Rust |
| Web framework | Actix-web (actor-model based) |
| ORM | Diesel (type-safe) |
| Database | PostgreSQL (R2D2 connection pooling) |
| Frontend language | TypeScript + CSS |
| Frontend framework | Inferno.js (React-compatible) |
| API client | lemmy-js-client |
| Image service | pictrs |
| Deployment | Docker, Ansible, ARM64/RPi supported |
| License | AGPL-3.0 |
| Federation library | activitypub-federation-rust (standalone reusable crate) |
2. ActivityPub Object Type Mapping
| Lemmy Concept | ActivityPub Type | Notes |
|---|---|---|
| Community | Group | Automated relay actor; Announces all content to followers |
| User | Person | Creates content, moderates, sends PMs |
| Instance | Application | Instance-level actor at root path |
| Post | Page | Mandatory title (name), optional URL and body |
| Comment | Note | Tree structure via inReplyTo |
| Private Message | ChatMessage | Direct 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
| Field | Description |
|---|---|
preferredUsername | Machine-readable community name |
name | Human-readable display name |
summary | Description / rules (HTML) |
icon / image | Avatar / banner |
outbox | Limited to 20 latest posts |
followers | Count only (no individual references — privacy) |
attributedTo | Creators and moderators |
featured | Pinned posts collection |
postingRestrictedToMods | Whether 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"
}
| Field | Description |
|---|---|
name | Title (mandatory — distinguishes Post from Comment) |
content | Body text (HTML-rendered) |
source | Original markdown with mediaType: "text/markdown" |
audience | Target community (for routing) |
attachment | Links/images array |
image | Thumbnail |
commentsEnabled | Post lock status (custom extension) |
sensitive | NSFW flag |
stickied | Pinned status (custom extension) |
language | Language 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"
}
| Field | Description |
|---|---|
inReplyTo | Parent post and/or parent comment (builds tree) |
tag | Mention objects for user references |
distinguished | Mod-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
| Algorithm | Description |
|---|---|
| Active (default) | Score + latest comment time with decay |
| Hot | Score + post publication time with decay |
| Scaled | Hot with boost for less active communities |
| New / Old | Chronological |
| Most Comments | Comment count |
| New Comments | Forum-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
| Activity | Purpose |
|---|---|
Follow | Subscribe to community |
Undo{Follow} | Unsubscribe |
Create{Page} | New post |
Create{Note} | New comment |
Update{Page} | Edit post |
Update{Note} | Edit comment |
Like | Upvote |
Dislike | Downvote |
Undo{Like} / Undo{Dislike} | Remove vote |
Delete | Delete own content |
Undo{Delete} | Restore deleted content |
Flag | Report content (with summary reason) |
Community → Followers
| Activity | Purpose |
|---|---|
Accept{Follow} | Automatic response to Follow |
Announce{*} | Rebroadcast any received activity to all followers |
Moderation
| Activity | Purpose |
|---|---|
Remove | Remove content (with summary reason) |
Block | Ban user (with target scope, optional removeData, expires, summary) |
Lock | Prevent new comments on post |
Add to /moderators | Add moderator |
Remove from /moderators | Remove moderator |
Add to /featured | Pin post |
Remove from /featured | Unpin post |
User → User
| Activity | Purpose |
|---|---|
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
Deleteon user actor withremoveData: truefor 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
| Property | Namespace | Used on | Description |
|---|---|---|---|
stickied | lemmy | Page | Pinned post |
distinguished | lemmy | Note | Mod-highlighted comment |
commentsEnabled | lemmy | Page | Post lock status |
postingRestrictedToMods | lemmy | Group | Restricted posting |
moderators | lemmy | Group | Moderator collection |
language | lemmy | Page, Note | Language metadata |
sensitive | as | Page | NSFW flag |
matrixUserId | lemmy | Person | Matrix 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
| Mode | Description |
|---|---|
| Allowlist | Only connect to specified instances |
| Blocklist | Block 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
| Aspect | Details |
|---|---|
| Version | v3 (/api/v3/...) |
| Auth | JWT (cookies or Authorization header since 0.19.0) |
| Image service | pictrs — upload, resize, format conversion |
| Feeds | RSS/Atom at /feeds/ paths |
| Rate limiting | IP-based (Docker: requires X-Forwarded-For header) |
| Client library | lemmy-js-client (official TypeScript) |
| OpenAPI spec | Unofficial: 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 impliedstickiedis 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.
| Platform | Language | Terminology | Notes |
|---|---|---|---|
| Lemmy | Rust | Communities | Largest, most mature |
| Mbin | PHP (fork of Kbin) | Magazines | Also supports microblogs (Mastodon-style) |
| PieFed | Python | Topics | Rapid development, approaching feature-parity |
| Sublinks | Java | — | 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
-
Posts use
Page, notNote— if your server sendsNoteobjects to a Lemmy community, they will be treated as comments, not posts. Posts requirePagetype with aname(title). -
Community must be in recipients — activities targeting a Lemmy community must include the community in
toorcc. Sending only to the post author's inbox will not distribute the activity. -
audiencefield — Lemmy uses theaudienceproperty to route activities to the correct community. Include it for reliable delivery. -
Dislikeis real — unlike most Fediverse platforms, Lemmy usesDislikeas a distinct activity type for downvotes, notUndo{Like}. -
sourcewith markdown — Lemmy preserves original markdown in thesourcefield withmediaType: "text/markdown". Thecontentfield contains the HTML-rendered version. -
Outbox is limited — community outbox only contains the 20 most recent posts. Comments and votes are not included.
-
Followers collection is opaque — returns only a total count, not individual follower references (for privacy).
-
No JSON-LD processing — Lemmy parses JSON directly. Do not rely on JSON-LD compaction/expansion when interoperating with Lemmy.
-
ChatMessagefor PMs — Lemmy uses the non-standardChatMessagetype for private messages rather thanNotewith 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
| Component | Technology |
|---|---|
| Backend | PHP / Laravel |
| Frontend | Vue 3 + TypeScript |
| CSS | Tailwind CSS |
| Build tool | Vite |
| Mobile app | React Native (Expo) |
| Deployment | Docker / Docker Compose |
| CDN | Fastly (Fast Forward program) |
| License | AGPL-3.0 |
Repositories
| Repository | URL |
|---|---|
| Server | https://github.com/joinloops/loops-server |
| Mobile app | https://github.com/joinloops/loops-expo |
| API docs | https://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
Noteobject 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
| Approach | Used by | Pros | Cons |
|---|---|---|---|
Note + video attachment | Loops | Universal compatibility; shows up in all timelines | Less video-specific metadata |
Video object | PeerTube | Rich 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
Noteobjects from remote servers are rejected — Loops is for videos only, not microblog posts - Replies to videos create
Commentobjects - Replies to comments become
CommentReplyobjects 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
| Feature | Status |
|---|---|
| Follow any ActivityPub user | Working |
| Be followed from Mastodon/Pixelfed/etc | Working |
| Cross-platform comments | Working |
| Cross-platform likes | Working |
| Share/Announce to followers | Working |
| Federated notifications | Working |
| Multi-instance video distribution | Working |
| Account migration with follower transfer | Planned |
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)
| Quarter | Features |
|---|---|
| Q1 | Advanced moderation, push notifications, multi-account, stitches |
| Q2 | Creator analytics, AR filters, collaborative moderation, accessibility |
| Q3 | Embeddable player, account migration, live streaming, video editor |
| Q4 | Challenges, monetization options |
5. Loops vs PeerTube
| Aspect | Loops | PeerTube |
|---|---|---|
| Focus | Short-form vertical video (TikTok/Vine) | Long-form video (YouTube) |
| Video length | Up to 3 minutes | No practical limit |
| UI | Mobile-first vertical swipe | Web-first video library |
| Discovery | For You algorithmic feed + hashtags | Federated search, channels |
| AP object type | Note with video attachments | Video |
| Tech stack | Laravel (PHP) + Vue.js | Node.js + Angular |
| P2P delivery | No | Yes (WebRTC) |
| Live streaming | Planned Q3 2026 | Yes |
| Maturity | Beta (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
-
Loops videos arrive as
Noteobjects — if your software handlesNotewith video attachments, Loops content will display correctly in timelines. No specialVideotype handling needed. -
Replying to a Loop — send a standard
Notereply withinReplyTopointing to the loop'sNoteID. Loops will accept it as a Comment. -
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.
-
Like and Announce work normally — standard
LikeandAnnounceactivities targeting a loop'sNoteID work as expected. -
Video stays on origin server — when a loop federates, remote instances receive the
Notemetadata 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. -
Multiple encodings — Loops may include multiple video file attachments (different resolutions/encodings) in the
Noteobject. 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
| Prefix | URI | Notes |
|---|---|---|
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/v1 | Public keys, signatures |
Key toot: Namespace Terms
toot:Emoji-- custom emoji typetoot:featured-- pinned posts collection (@id,@type: @id)toot:featuredTags-- featured hashtags collectiontoot:discoverable-- boolean, whether to list in directorytoot:indexable-- boolean, consent for search indexing (FEP-5feb)toot:suspended-- boolean, account suspension statustoot:memorial-- boolean, memorial/deceased accounttoot:votersCount-- poll total voter counttoot:blurhash-- BlurHash string for media placeholderstoot:focalPoint--[x, y]coordinates for image croppingtoot:attributionDomains-- domains allowed to usefediverse:creator(since 4.3)
Key as: Extended Terms
as:Hashtag-- hashtag tag typeas:manuallyApprovesFollowers-- locked account flagas:movedTo-- account migration targetas:sensitive-- content warning flagas:alsoKnownAs-- account aliases for migration
Key schema: Terms
schema:PropertyValue-- profile metadata field typeschema: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+jsonapplication/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 hostnamedate-- RFC 2616 date (must be within clock skew tolerance)
For POST requests (always required):
(request-target)hostdatedigest-- 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
| Type | Mastodon Representation |
|---|---|
Note | Regular status/toot |
Question | Poll status |
Converted Types (Best-Effort)
These types are accepted but not given full treatment:
| Type | Handling |
|---|---|
Article | Uses content (or name if no content) as status text; appends url; summary becomes CW; icon becomes thumbnail |
Page | Same conversion logic as Article |
Image | Same conversion logic |
Audio | Same conversion logic |
Video | Same conversion logic |
Event | Same 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 pollsanyOf-- array of options for multiple-choice polls- Each option:
type: "Note",name: "<option text>",replies.totalItems: <vote count> - Options have no
idproperty endTime-- ISO 8601 timestamp when voting closesclosed-- 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:
nameexactly matching the poll option'snameinReplyTopointing to the Question'sidtoaddressing 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
Updateactivity is sent with the full updated object asobject - The
updatedtimestamp on the object signals that this is an edit (not a first-time creation) - Receiving instances check: if a status with that
idalready exists locally, theUpdatetriggers an edit; otherwise it is treated as a new status - Mastodon's
FetchRemoteStatusServiceautomatically converts aCreateto anUpdatewhen 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
StatusEditentity 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:
objectas a URI string (standard pattern) -- fetches the originalobjectas 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) intoorcc - No follower collection URI in
toorcc - Only specific actor URIs in
to - All actors in
to/ccmust have a correspondingMentiontag
Visibility Level Calculation
Mastodon calculates visibility from addressing, not from an explicit visibility field:
| Visibility | to | cc | Mention tags |
|---|---|---|---|
| public | as:Public | followers collection | -- |
| unlisted | followers collection | as:Public | -- |
| private | followers collection | (no as:Public) | -- |
| limited | specific actors | -- | Not all actors are Mentioned |
| direct | specific 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"(fromtoot: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, andcontentfor 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 withclass="mention"orclass="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)
| Property | Limit | Behavior if exceeded |
|---|---|---|
| JSON-LD serialization | 1 MB | Activity rejected |
| Username | 2048 chars | Actor rejected |
| Display name | 2048 chars | Truncated |
| Profile note (bio) | 20 kB | Truncated |
| Profile fields | 50 fields | List truncated |
| Field name/value | 2047 chars | Truncated |
| Poll options | 500 | List truncated |
| Custom emoji shortcode | 2048 chars | Rejected |
| Media descriptions (alt) | 1500 chars | Truncated |
| Account aliases | 256 | List truncated |
| Attribution domains | 256 | List 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
repliescollections 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/contextendpoint returns aMastodon-Async-RefreshHTTP 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:
| Platform | Mastodon API Support |
|---|---|
| Pleroma | Near-complete, with Pleroma-specific extensions |
| Akkoma | Near-complete (Pleroma fork), with additional extensions |
| GoToSocial | Well-implemented, works with major Mastodon apps |
| Firefish | Partial support (now discontinued) |
| Sharkey | Partial support (Misskey fork) |
| Pixelfed | Partial support for photo-related endpoints |
| Friendica | Partial 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: newtoot:property forfediverse:creatorauthor attribution on external articles- Like and boost counts now exposed in ActivityPub Note objects
summaryfield 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
quoteattribute 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_idAPI 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-RefreshHTTP 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
-
schema.org base URI bug: Mastodon maps
schema:tohttp://schema.org#instead ofhttps://schema.org/. Strict JSON-LD processors will fail. Workaround: accept both forms. -
Context order matters: Some implementations are sensitive to the order of items in the
@contextarray. Match Mastodon's order when possible. -
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
-
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.
-
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
-
Article objects degraded: Mastodon does not render
Articleobjects with full fidelity. Long-form content platforms should consider sendingNotefor Mastodon compatibility or accept that their content will be reduced to plain text + URL. -
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.
-
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
-
Block activity sent S2S: Mastodon sends
Blockactivities 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. -
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. -
Clock skew sensitivity: HTTP signature verification checks the
Dateheader. If your server's clock is significantly off, signatures will be rejected.
Performance
-
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.
-
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: theacct:URIlinks: array including a link withrel: "self",type: "application/activity+json", andhrefpointing 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 namesummary-- bio (HTML)url-- profile page URL (HTML)inbox-- ActivityPub inbox endpointoutbox-- ActivityPub outbox endpointfollowers-- followers collection URIfollowing-- following collection URIfeatured(toot:featured) -- pinned posts collectionfeaturedTags(toot:featuredTags) -- featured hashtagspublicKey-- RSA public key for HTTP signature verificationendpoints.sharedInbox-- shared inbox for efficient deliveryicon-- avatar imageimage-- header/banner imageattachment-- array ofschema:PropertyValuefor profile fieldsdiscoverable(toot:discoverable) -- directory listing consentindexable(toot:indexable) -- search indexing consentmemorial(toot:memorial) -- deceased account flagsuspended(toot:suspended) -- suspension flagmanuallyApprovesFollowers-- locked accountmovedTo-- migration target actor URIalsoKnownAs-- array of aliases (for migration verification)attributionDomains(toot:attributionDomains) -- fediverse:creator domains
20. Supported Activities (Inbox Processing)
| Activity | Object Type | Mastodon Behavior |
|---|---|---|
Create | Note | Creates a new status |
Create | Question | Creates a poll status |
Create | Other | Best-effort conversion to status |
Update | Note/Question | Edits status (if updated present, since 3.5) |
Update | Person | Updates remote actor profile |
Delete | Note | Deletes remote status locally |
Delete | Person | Removes remote actor and content |
Announce | Status URI | Creates a boost |
Like | Status URI | Creates a favorite |
Follow | Actor URI | Sends follow request |
Accept | Follow | Confirms follow relationship |
Reject | Follow | Rejects follow request |
Undo | Follow | Unfollows |
Undo | Like | Removes favorite |
Undo | Announce | Removes boost |
Undo | Block | Removes block |
Block | Actor URI | Records block (non-standard S2S use) |
Flag | Actor + objects | Reports content/user to moderators |
Move | Actor URI | Triggers account migration |
Add | Status to featured | Pins a status |
Remove | Status from featured | Unpins 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
| Component | Technology |
|---|---|
| Backend | PHP 8.3+ (8.4 recommended) |
| Framework | Symfony 7.4.x |
| ORM | Doctrine 2.19.6 |
| Database | PostgreSQL (14–18) |
| Message queue | RabbitMQ (with optional AMQProxy for connection pooling) |
| Cache | Redis / Valkey / KeyDB |
| Real-time | Mercure (optional, server-sent events) |
| Frontend | Twig templates (9.4%), SCSS (2.5%), JavaScript (1.6%) |
| Bundler | Webpack |
| Web server | Nginx, Apache, or Caddy |
| Image processing | GD with blurhash support |
| Object storage | Local filesystem or S3 (AWS, MinIO, Ceph) |
| Deployment | Docker (Debian Trixie base) or bare metal |
| License | AGPL-3.0 |
| Documentation | Docusaurus (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:
| Type | Description | AP Object | Entity Class |
|---|---|---|---|
| Thread (Entry) | Links, articles, discussion posts with titles | Page | Entry + EntryComment |
| Microblog (Post) | Short-form posts (like Mastodon) | Note | Post + PostComment |
| Comment | Replies to threads or microblogs | Note (with inReplyTo) | EntryComment or PostComment |
| Private message | Direct messages between users | ChatMessage | — |
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
Likeactivity (equivalent to Mastodon favourite) - Downvote — federated as
Dislikeactivity (historically had federation issues inherited from Kbin) - Boost — federated as
Announceactivity (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
| Actor | Type | Path | Purpose |
|---|---|---|---|
| Instance | Application | /i/actor and / | Server-level actor, signs requests, inbox/outbox |
| User | Person | /u/username | Individual accounts with followers/following, discoverable/indexable flags |
| Magazine | Group | /m/name | Community 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
| Protocol | Endpoint | Source File |
|---|---|---|
| WebFinger | /.well-known/webfinger | WebFingerController.php + Service/ActivityPub/Webfinger/ |
| NodeInfo | /.well-known/nodeinfo | NodeInfoController.php |
| Host-Meta | /.well-known/host-meta | HostMetaController.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
| Collection | Type | Description |
|---|---|---|
| Outbox | OrderedCollection | Create activities, paginated with first |
| Followers | OrderedCollection | Users: individual refs; Magazines: counts only |
| Following | OrderedCollection | Users only |
| Moderators | OrderedCollection | Non-paginated list of moderator URIs |
| Featured | OrderedCollection | Non-paginated pinned threads |
5. Activity Reference
Content Activities
| Activity | Purpose |
|---|---|
Create | Create threads, microblogs, comments, messages |
Update | Edit content or account profiles |
Delete | Remove content/accounts, replaced with Tombstone; optional removeData flag |
Lock | Disable comments on threads/microblogs |
Social Activities
| Activity | Purpose |
|---|---|
Follow | Subscribe to user or magazine |
Accept / Reject | Follow request responses (auto-sent on Follow receipt) |
Undo | Reverse Follow, Like, Dislike, or Announce |
Like | Upvote |
Dislike | Downvote |
Announce | Boost/reshare; also magazine relay wrapping |
Moderation Activities
| Activity | Purpose |
|---|---|
Block | Ban user from magazine or instance (optional expiration) |
Flag | Report content (distributed only to instances hosting magazine moderators) |
Add / Remove | Moderator 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/Removeto/moderatorscollection - 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
featuredcollection - 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/Removeactivities
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
Blockactivities - Federated bans — both incoming and outgoing (v1.9.0+)
CLI Admin Commands
| Command | Purpose |
|---|---|
mbin:user:create | Create users with optional admin/moderator privileges |
mbin:user:admin | Grant/revoke admin privileges |
mbin:user:delete | Delete user and notify fediverse |
mbin:user:moderator | Grant/revoke global moderator |
mbin:user:verify | Activate/deactivate users (bypasses email verification) |
mbin:user:password | Reset passwords |
mbin:user:private-keys:rotate | Rotate federation authentication keys |
mbin:magazine:create | Create/remove/purge magazines |
mbin:messages:remove_and_ban | Search DMs, ban senders, remove messages |
mbin:check:duplicates-users-magazines | Find/remove duplicate accounts |
mbin:ap:actor:update | Update remote users and avatars |
mbin:ap:import | Import 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
| Resource | Minimum | Recommended |
|---|---|---|
| vCPU | 4 cores (≥2GHz) | 12 cores |
| RAM | 6 GB | 32 GB |
| Storage | 40 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
| Aspect | Mbin | Lemmy |
|---|---|---|
| Language | PHP 8.3+ (Symfony) | Rust (Actix-web) |
| Content types | Threads + Microblogs | Threads only |
| Communities | "Magazines" (Group) | "Communities" (Group) |
| AP objects | Page (threads) + Note (microblogs) | Page only |
| Mastodon integration | Strong — microblog section shows Mastodon content | Limited |
| User following | Yes — can follow individual accounts | No — communities only |
| Boost vs vote | Separate functions | Combined (upvote = boost) |
| Downvote federation | Dislike (historical issues) | Dislike (reliable) |
| Mention federation | Strong (bidirectional with Mastodon) | Weaker |
| Third-party apps | Limited (Interstellar) | Many (Boost, Thunder, Voyager) |
| Governance | C4 collective, multiple maintainers | 2 primary developers |
| Maturity | Newer (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
Noteposts appear as comments in Lemmy (Lemmy only understandsPagefor 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
@contextincludes 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
| Version | Date | Key Changes |
|---|---|---|
| v1.0.0 | Oct 30, 2023 | First release |
| v1.7.0 | mid 2024 | PeerTube support, DMs, push notifications |
| v1.8.4 | Sep 7, 2024 | Security patch, dead instance handling |
| v1.9.0 | Dec 14, 2024 | Combined homepage, magazine banners, federated bans, Symfony 7 |
| v1.9.1 | Feb 9, 2025 | Thread/microblog locking, RSS improvements, faster search |
14. Instances and Ecosystem
~18 instances, ~8,172 total users, ~750 monthly active users.
| Instance | URL | Users | MAU |
|---|---|---|---|
| Fedia | fedia.io | 6,036 | 488 |
| kbin.earth | kbin.earth | 770 | 131 |
| the/brain/bin | thebrainbin.org | 245 | 34 |
| GehirnEimer | gehirneimer.de | 136 | 28 |
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
-
Sending
Noteobjects to a magazine expecting thread display — Mbin usesPagefor threads (entries) andNotefor microblogs. ANotesent to a magazine appears in the microblog section, not as a thread. UsePagewith aname(title) for thread-style posts. -
Ignoring the separate boost/vote model — Unlike Lemmy where upvoting boosts, Mbin treats
Like(upvote) andAnnounce(boost) as independent actions. Implement both if you want full interoperability. -
Expecting downvotes to always federate — Mbin sends
Dislikeactivities but historically had federation issues inherited from Kbin. Downvotes are not publicly visible on Mbin. Do not assume reliableDislikedelivery from older Mbin versions. -
Not including the magazine in activity recipients — Activities targeting a magazine must include the magazine Group actor in
toorcc. The magazine must receive the activity toAnnounceit to followers. -
Assuming
ChatMessageis standard — Mbin uses a customChatMessagetype for private messages, notNotewith direct addressing. Other platforms may not understand this type. -
Ignoring
sourcewith markdown — All content preserves original markdown in thesourcefield alongside HTML incontent. Prefer rendering fromsourceif you want accurate markdown. -
Not handling both
PageandNotefrom the same magazine — A single magazine may produce bothPage(threads) andNote(microblogs) objects. Consuming software must handle both types from the same Group actor. -
Expecting
Likeactivities to use followers collection into— As of v1.9.1, Like/Dislike activities use the magazine ID in thetofield instead of the followers collection. -
Treating magazine rules as a reliable field — The rules field is deprecated and cannot federate. Rules are embedded in the magazine description under a
### Rulesheader instead. -
Not accepting
application/jsoncontent type — Mbin accepts bothapplication/activity+jsonand plainapplication/jsonon all ActivityPub endpoints, and may send requests withapplication/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
| Component | Technology |
|---|---|
| Backend | Node.js with TypeScript |
| Framework | NestJS (dependency injection) |
| Database | PostgreSQL (TypeORM) |
| Cache / Queue | Redis (ioredis) / BullMQ |
| Frontend | Vue.js 3 (Composition API, TypeScript) |
| Build tool | Vite |
| License | AGPL-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
| Property | On | Description |
|---|---|---|
_misskey_content | Note | Deprecated. MFM source text (equivalent to source property) |
_misskey_summary | Actor | Actor summary in MFM format |
_misskey_quote | Note | ID of quoted note. Compatible with fedibird:quoteUri and as:quoteUrl |
_misskey_reaction | Like | Emoji reaction type. Unicode emoji or :name: custom emoji string |
_misskey_votes | Question option | Vote count (equivalent to replies.totalItems) |
_misskey_talk | Note | Boolean true marks note as a chat message |
isCat | Actor | Boolean — actor identifies as a cat (triggers visual effects) |
_misskey_followedMessage | Actor | Custom message on follow notification (since 2024.9.0-alpha.11) |
_misskey_requireSigninToViewContents | Actor | Forbids display to non-signed-in viewers |
_misskey_makeNotesFollowersOnlyBefore | Actor | Restricts past notes to followers only. Value: Unix epoch ms (negative = relative) |
_misskey_makeNotesHiddenBefore | Actor | Hides past notes from all except author. Same value format |
_misskey_license | Emoji | License 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
| Syntax | Effect |
|---|---|
$[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
| Syntax | Effect |
|---|---|
$[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
| Level | Description |
|---|---|
public | Visible to everyone, appears on all timelines |
home | Visible to everyone but only appears on home timeline |
followers | Only visible to followers |
specified | Only visible to specified users (direct message) |
Features
- Content Warning (CW):
summaryfield hides content behind a toggle - Renote: Boost/reblog (Announce activity)
- Quote Renote: Boost with added commentary (
_misskey_quote) - Polls:
Questionactivity type with_misskey_votesfor counts - Reactions: Full emoji reactions (see Section 2)
- Mentions: @-mentions across the Fediverse
- Hashtags: Standard
Hashtagtag type
Timelines
| Timeline | Content |
|---|---|
| Home | Notes from followed users |
| Local | All public notes from the instance |
| Social (Hybrid) | Home + Local combined |
| Global | All 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
/sharepath for social sharing buttons - Safe mode — disables custom CSS, plugins, themes
- Embeds — embed notes and timelines on external websites
isCatmode — 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
| Fork | Type | Key Differentiators |
|---|---|---|
| Sharkey | Soft 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 |
| Cherrypick | Soft fork | Compatible with Misskey client ecosystem |
| Meiskey | v11 fork | Based on older Misskey v11 |
Discontinued / EOL Forks
| Fork | Status | Notes |
|---|---|---|
| Firefish (was Calckey) | Discontinued 2024 | Added recommended timeline, account migration, mobile-optimized UI. Lead developer became absent |
| Iceshrimp | Transitioning | JS version: security patches only. Iceshrimp.NET: complete C# rewrite (beta), Mastodon API support |
| FoundKey | End of Life | Hard fork of v12, goal was removing bloat |
| Catodon | Discontinued Nov 2025 | Community-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
| Aspect | Misskey | Mastodon |
|---|---|---|
| Origin | Japan (2014) | Germany (2016) |
| Character limit | Configurable per instance | 500 default |
| Reactions | Full emoji reactions (custom + Unicode) | Favourites only |
| File management | Built-in Drive | No persistent storage |
| Markup | MFM (animations, colors, effects) | Limited Markdown |
| Channels | Topic-based communities | No |
| Antennas | Custom filtered feeds | No equivalent |
| Resource usage | Lighter than Mastodon | Heavier |
| Mobile apps | Limited (PWA, third-party) | Official iOS/Android + many third-party |
| Post editing | Not in core (Sharkey has it) | Supported |
| User base | ~918k (mostly Japanese) | ~7.6M total |
9. Interoperability Notes for Implementers
-
Emoji reactions arrive as
Likeactivities — check for_misskey_reactionto distinguish a specific emoji reaction from a generic favourite. If absent, treat as a standard Like. Thecontentfield also contains the reaction value. -
Custom emoji in reactions — when
_misskey_reactioncontains a:name:string, thetagarray includes anEmojiobject with the image URL. Display the custom emoji image if available, fall back to treating it as a Like. -
Quote posts — Misskey sends
_misskey_quoteandquoteUrlon Note objects. Also check forfedibird:quoteUri(Fedibird/Mastodon compatibility). Display as an embedded quote if your platform supports it. -
MFM content — notes from Misskey contain HTML in
content(with MFM effects stripped) and optionally MFM source in thesourceproperty. Use the HTML for display; the MFM source is only useful if you want to re-render with a MFM parser (library:mfm-js). -
isCatproperty 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. -
Chat messages — notes with
_misskey_talk: trueare Misskey chat messages. They federate as normal Notes to non-Misskey platforms. Display as regular posts if your platform has no chat feature. -
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.
-
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 ActivityPubto: followers, cc: Public(the inverse of Mastodon's "unlisted"). Handle carefully when federating. -
Poll vote counts — Misskey includes
_misskey_voteson poll options. This is equivalent toreplies.totalItemsbut may be more reliably present. Prefer_misskey_voteswhen available. -
Note content restrictions — the
_misskey_makeNotesFollowersOnlyBeforeand_misskey_makeNotesHiddenBeforeproperties 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
| Component | Technology |
|---|---|
| Backend | Node.js |
| Real-time | WebSockets (Socket.IO) |
| Database | MongoDB (default), Redis, or PostgreSQL |
| Frontend | Server-rendered templates + client-side JS |
| License | GPL-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:
| Type | Behavior |
|---|---|
| Filters | Take input, modify, return changed value |
| Actions | Execute side effects, return nothing |
| Static | Like actions but NodeBB waits for completion |
| Response | Return 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
| Date | Milestone |
|---|---|
| Mid-2023 | Julian conceives inter-NodeBB communication idea |
| Aug 2023 | NLNet Foundation funding approved |
| Jun 2024 | v4.0.0-alpha |
| Sep 2024 | v4.0.0-beta.1 |
| Nov 2024 | RC1 |
| Jan 20, 2025 | v4.0.0 stable |
| 2025–2026 | Continued releases through v4.9.0+ |
3. Actor Types
| Actor | Type | Path | Purpose |
|---|---|---|---|
| User | Person | /u/username | Individual user accounts |
| Category | Group | /category/<cid> | Forum categories, Group Federation |
| Instance | Application | (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
Groupactors 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 (Groupactor)context→ points to the topic (resolvable URL returning anOrderedCollectionper FEP-7888)
Object Types
| NodeBB Concept | AP Object | Notes |
|---|---|---|
| Topic | context (OrderedCollection) | Resolvable collection of posts |
| Post / Reply | Note or Article | Within a context, with inReplyTo for threading |
| Category | Group actor | Uses 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:
-
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. -
Fallback: Reply chain traversal — traverses
inReplyTochain 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
| FEP | Title |
|---|---|
| FEP-0151 | NodeInfo in Fediverse Software |
| FEP-11dd | Context Ownership and Inheritance |
| FEP-1b12 | Group Federation |
| FEP-4f05 | Soft Deletion |
| FEP-7888 | Demystifying the context property |
| FEP-9098 | Custom emojis |
| FEP-ae0c | Fediverse Relay Protocols (Mastodon and LitePub) |
| FEP-b2b8 | Long-form Text |
| FEP-f15d | Context Relocation and Removal |
| FEP-f228 | Backfilling Conversations |
| FEP-fb2a | Actor metadata |
| FEP-fe34 | Origin-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
- Follow users/categories — search for handles
(e.g.,
user@domain.social) - URL paste — paste a remote content URL into NodeBB's search bar to pull it in; content lands in Uncategorized
- 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:
| Setting | Default | Condition for removal |
|---|---|---|
| Remote content retention | 30 days | Topics with no local engagement (votes or replies) |
| Remote user retention | 7 days | Accounts with no posts and no follow relationships |
Both settings are configurable via the admin panel.
7. NodeBB vs Discourse (Federation)
| Aspect | NodeBB | Discourse |
|---|---|---|
| Language | Node.js | Ruby on Rails |
| AP integration | Core feature (v4+) | Plugin (discourse-activity-pub) |
| AP since | January 2025 | 2023 (plugin) |
| Actor model | Group (categories) | Group (categories) |
| Context support | FEP-7888 (resolvable) | Separate approach |
| FEPs implemented | 12 | Fewer |
| Real-time | Native WebSockets | Long polling / MessageBus |
| Database | MongoDB/Redis/PostgreSQL | PostgreSQL only |
| License | GPL-3.0 | GPL-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
-
Categories are
Groupactors — follow a NodeBB category by sendingFollowto the Group actor at/category/<cid>. The category relays all content viaAnnounce, identical to Lemmy communities. Category handles are slugified names (e.g.,general-discussion). -
Posts carry both
contextandaudience—contextpoints to the topic (resolvableOrderedCollection),audiencepoints to the category (Groupactor). This two-level hierarchy is NodeBB-specific and differs from Lemmy's single-level approach. -
Topics are resolvable collections — if your software encounters a NodeBB
contextURL, resolve it to get the full topic as anOrderedCollection. This is the recommended way to backfill conversations (per FEP-7888 and FEP-f228). -
NoteandArticleobjects accepted — NodeBB processes bothNoteandArticletypes when building topics. Send whichever is appropriate for your content. -
No relay federation — NodeBB will not participate in relay subscriptions. Content exchange requires explicit follow relationships.
-
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.
-
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.
-
Soft deletion (FEP-4f05) — NodeBB supports soft deletion. When content is deleted, a
Deleteactivity with aTombstoneobject is sent rather than simply disappearing. -
Custom emojis (FEP-9098) — NodeBB supports federated custom emoji. Remote emoji in posts and chats are rendered (since v4.7.0).
-
Content in Uncategorized has no
audience— manually discovered content landing in the Uncategorized pseudo-category may not have a properaudienceproperty 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
| Layer | Technology |
|---|---|
| Backend language | TypeScript (Node.js) |
| Backend framework | Express |
| Database | PostgreSQL 12+ (with pg_trgm and unaccent extensions) |
| Cache / Queue | Redis (BullMQ for job queues) |
| ORM | Sequelize |
| Video processing | FFmpeg (LTS 4.3+) |
| OAuth | Built-in OAuth 2.0 |
| Web server | Nginx (official configs provided) |
| Package manager | pnpm |
| Frontend framework | Angular (TypeScript) |
| Playback | VideoJS, hls.js, P2P Media Loader |
| Frontend build | Webpack |
| Frontend CSS | SASS / Bootstrap |
| Mobile | Official app (iOS + Android, December 2024) |
| License | AGPL-3.0 |
| Runtime | Node.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
attributedTopoints 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:
- Simulate a Group actor representing the account, or
- Put the Person actor as a Group actor in
attributedToowned by a global Person actor
Without a Group actor in attributedTo, PeerTube cannot properly
federate the video.
3. Supported Activities
| Activity | Description |
|---|---|
Accept | Approves follow requests |
Announce | Channel announces a video (primary video distribution mechanism) |
ApproveReply | Comment moderation approval (v6.2+, implements FEP-5624) |
Create | Creates Video, Note (comment), CacheFile, Playlist |
Delete | Removes Video, Note, Person, Group, Playlist, CacheFile |
Dislike | Thumbs down on a video (non-standard — most Fediverse software only has Like) |
Flag | Federated report functionality |
Follow | Subscribe to a channel or instance |
Like | Thumbs up on a video |
Reject | Denies follow requests |
Undo | Reverses Follow, Announce, Like, Dislike, CacheFile |
Update | Modifies Video, Note, Person, Group, Playlist, CacheFile |
View | View count tracking |
How Video Publishing Works
When a user uploads a video:
- The Person actor sends a
Create{Video}activity - The Group (channel) actor sends an
Announce{Video}to its followers - 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:
attributedTomust contain both a Group (channel) and a Person (account) — the Group entry is required for federationnameis the video title (notsummaryas with Mastodon posts)contentis the video description (HTML)summaryis used for content warnings (like Mastodon)durationuses ISO 8601 duration format (e.g.,PT5M30S)urlis an array with multiple entries for different formats and resolutions (HTML page, MP4 files, HLS playlists)- If
embedUrlis absent, the video has embedding restrictions sensitiveand a tag oftype: SensitiveTagindicate sensitive content
Video Object Extensions
Live streaming properties:
isLiveBroadcast— whether this is a live streamliveSaveReplay— whether to save the replay after stream endspermanentLive— persistent stream URL that can be reusedlatencyMode— latency configuration for the streamschedules— array for scheduled broadcast times
Interaction controls:
commentsPolicy— comment policy (integer value)canReply— FEP-5624; when set to the public collection, comments require approval viaApproveReplydownloadEnabled— boolean controlling whether viewers can download
State:
waitTranscoding— whether to wait for transcoding before publishingstate— 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
| Type | Purpose |
|---|---|
Playlist | Non-standard OrderedCollectionPage containing PlaylistElement items |
PlaylistElement | Individual playlist entries with start/stop timestamps |
WatchAction | Schema.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
- An admin configures a redundancy strategy (cache trending videos, recently uploaded videos, etc.)
- PeerTube periodically checks for new videos to duplicate
- When a video is selected, all resolution files are imported and stored locally
- A
Create{CacheFile}ActivityPub message is sent to federated instances - The caching instance is injected as a WebSeed by instances that receive this message — viewers can now download video chunks from the mirror
- When the cache is full, old videos are evicted and new ones selected
ActivityPub Flow
Create{CacheFile}— sent when a mirror instance begins cachingUndo{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-addedwith 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/"}
]
| Namespace | Prefix | Purpose |
|---|---|---|
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 Mastodon | Result on PeerTube |
|---|---|
| Follow a PeerTube channel | Videos appear in Mastodon home timeline |
| Reply to a PeerTube video post | Appears as a comment on the video |
| Favourite a PeerTube video | Appears as a thumbs up (Like) |
| Boost a PeerTube video | Increases reach on federated timelines |
| Action on PeerTube | Result on Mastodon |
|---|---|
| Upload a video | Appears as a post in followers' timelines |
| Like a Mastodon comment | Standard Like activity |
| Dislike | Not 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 itsregister()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 anattributedTofield 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
Videoas the object type, notNote— code that only handlesNotewill miss all PeerTube content. Implement handling fortype: "Video"in your ActivityPub processor - Ignoring the two-tier
attributedTo: PeerTube'sattributedTocontains 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
Dislikegracefully: PeerTube sendsDislikeactivities 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
urlfield is an array with multiple entries for different formats (HTML page, MP4 at various resolutions, HLS playlists) — pick the appropriate entry based onmediaType - Not handling
CacheFile: if you receive aCreate{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
embedUrlabsence: if a PeerTube Video object lacksembedUrl, 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 anApproveReply— 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
| Component | Technology |
|---|---|
| Backend language | Python (3.9+, ~70% of codebase) |
| Web framework | Flask |
| Frontend | htmx + vanilla JavaScript + Bootstrap CSS |
| Template engine | Jinja2 |
| Database | PostgreSQL 17 |
| ORM | SQLAlchemy (Flask-SQLAlchemy) |
| Migrations | Alembic (flask db upgrade) |
| Task queue | Celery with Redis broker |
| Cache | Redis 6.2 (optional) |
| Application server | Gunicorn |
| Real-time notifications | FastAPI + Uvicorn (separate service) |
| Linting | Ruff |
| i18n | Babel |
| Deployment | Docker (5-service compose), bare metal, YunoHost |
| License | AGPL-3.0 |
Design philosophy: "Clean, simple code" with "no fancy design patterns or algorithms." Only requires Python + PostgreSQL; Redis is optional. Dramatically lighter resource usage than Lemmy — one user reported server load of ~1 vs Lemmy's ~12 on identical hardware.
2. ActivityPub Object Type Mapping
| PieFed Concept | ActivityPub Type | Notes |
|---|---|---|
| Community | Group | Relay actor; Announces content to followers |
| User | Person | Creates content, moderates |
| Bot | Service | Bot accounts |
| Feed | Feed | PieFed extension (FEP-1d80); federated multi-community collection |
| Post | Page | Primary post type, mandatory title (name) |
| Article | Article | Long-form content |
| Link post | Link | URL submissions |
| Comment | Note | Tree structure via inReplyTo |
| Poll | Question | oneOf/anyOf choices, up to 15 options |
| Event | Event | startTime, endTime, timezone, participantCount |
| Video | Video | PeerTube video embeds |
| Direct message | ChatMessage | Private user-to-user |
3. Communities as Group Actors
Communities are Group actors with their own inboxes, following the
same Announce relay pattern as Lemmy — all content flows through the
community actor and is wrapped in Announce for distribution to
subscribers across instances.
Community-Specific Attributes
| Attribute | Description |
|---|---|
sensitive | NSFW flag |
nsfl | Not-safe-for-life flag (separate from NSFW) |
genAI | AI-generated content flag |
postingRestrictedToMods | Only moderators can post |
newModsWanted | Community is seeking moderators |
privateMods | Moderator list is hidden |
defaultPostType | Default content type for new posts |
questionAnswer | StackOverflow-style Q&A mode enabled |
moderators | OrderedCollection of moderators |
featured | Pinned posts collection |
tagsForPosts | Available flair/tag options (Lemmy-compatible) |
Moderator Attribution
PieFed accepts both attributedTo (Lemmy/Mbin style) and
moderators (Kbin style) for moderator lists, improving cross-platform
compatibility.
Community Types
- Federated (default): Full ActivityPub federation
- Local-only: Visible only on the home instance, no federation
- Private (v1.6+): Invitation-only, no federation, posts visible only to members
4. Voting — Like, Dislike, and Private Votes
PieFed uses Like (upvote) and Dislike (downvote) activities, same
as Lemmy. However, PieFed adds a private/anonymous voting system
that is unique in the Threadiverse.
Private Voting Mechanism
Users have two profiles: a main profile (for posting) and an anonymous proxy profile (no name, avatar, or bio) used exclusively for voting. When "Vote privately" is enabled:
- Votes sent to Lemmy/Mbin instances use the anonymous proxy profile
- New accounts have private voting enabled by default
- Votes can also be fully local (not federated at all)
Community-Level Vote Controls
- Moderators can restrict downvoting to subscribed members only
- Downvoting can be restricted to "trusted" instances (a third tier between full federation and defederation)
- Communities can disable downvotes entirely
- "Low quality" communities (e.g., memes) don't award karma for upvotes
Reputation Tracking
- "Attitude" metric: tracks ratio of downvotes to upvotes per user; flags excessive downvoters
- Comments scoring -10 or below are auto-collapsed
- Users with negative karma get red warning icons next to names (double red for severely negative)
- New accounts (first 7 days) display a special indicator
5. The Feed Actor (FEP-1d80)
PieFed introduces a custom Feed actor type — a federated equivalent
of Reddit's multi-reddits. This is defined in FEP-1d80.
A Feed is an ActivityPub actor of type Feed that aggregates multiple
communities (Group actors) into a single subscribable collection. Feeds
can include communities from any federated instance, PeerTube channels,
and Mastodon accounts.
- Feeds can be public (discoverable, subscribable) or private
- Feed actors are discoverable via WebFinger
- Users on remote PieFed instances can subscribe to a Feed like any other actor
- Feeds are managed via
Add/Removeactivities to add/remove communities
This is a PieFed-specific extension — Lemmy and Mbin do not support
the Feed actor type, though the FEP is open for adoption.
6. Full Activity Reference
Incoming Activities
| Activity | Purpose |
|---|---|
Follow | Subscribe to community/feed |
Accept / Reject | Subscription response |
Create | New post, comment, chat message, poll |
Update | Edit post/comment, update community profile |
Delete | Remove post, comment, PM, feed |
Like | Upvote |
Dislike | Downvote |
EmojiReact | Custom emoji reaction (unicode or :name: format) |
PollVote | Vote in a poll |
ChooseAnswer | Mark comment as answer (Q&A mode) |
Add | Add moderator, sticky post, add community to feed |
Remove | Remove moderator, unsticky post, remove from feed |
Lock | Lock post or comment (including children) |
Flag | Report content |
Announce | Boost/share (wraps other activities) |
Undo | Reverse any previous activity |
Community → Followers
| Activity | Purpose |
|---|---|
Accept{Follow} | Automatic response to Follow |
Announce{*} | Rebroadcast received activities to all followers |
Community outboxes serve Announce(Create(Page)) activities even for
non-local posts, functioning as content relays.
7. JSON-LD Context and Extensions
Context
[
"https://www.w3.org/ns/activitystreams",
"https://w3id.org/security/v1"
]
Lemmy-Compatible Extensions
| Property | Used on | Description |
|---|---|---|
tagsForPosts | Group | Available flair/tag options (Lemmy CommunityTag) |
postingRestrictedToMods | Group | Restricted posting |
language | Page, Note | Language metadata (identifier + name) |
PieFed-Specific Extensions
| Property | Used on | Description |
|---|---|---|
genAI | Group, Page | AI-generated content flag |
nsfl | Group, Page | Not-safe-for-life flag |
flair | Note | User flair (custom extension on comments) |
postingWarning | Group | Contextual warning above comment form |
interactionPolicy | Page | Interaction restrictions |
newModsWanted | Group | Community seeking moderators |
questionAnswer | Group | Q&A mode enabled |
8. Federation Architecture
Activity Processing Flow
- Parse JSON request body
- Check federation pause status (normal / overload / permanently closed)
- Extract actor and validate HTTP signature
- Deduplicate via Redis (activity IDs stored with 90-second TTL)
- Route to handler based on activity type
- Process asynchronously via Celery task
HTTP Signatures
| Aspect | Detail |
|---|---|
| Algorithm | RSA-SHA256 (also accepts hs2019) |
| Key size | 2048-bit RSA |
| Signed headers | (request-target), Host, Date, Digest, Content-Type, Accept |
| Date tolerance | 3,600 seconds (1 hour) |
| Fallback | LD signatures via URDNA2015 normalization |
| Key cache | Up to 1,000 entries |
Reliability
- Failed deliveries enter a retry queue with retries over several days
- Batched federation between PieFed instances reduces load
- Redis-based locking minimizes database deadlocks
- Federation can be paused during overload conditions
Key Endpoints
| Path | Purpose |
|---|---|
/.well-known/webfinger | User, community, and feed discovery |
/.well-known/nodeinfo | NodeInfo schema links |
/nodeinfo/2.0, /nodeinfo/2.1 | Server stats and protocol info |
/u/<actor> | User actor (content-negotiated JSON/HTML) |
/c/<actor> | Community actor |
/inbox | Shared inbox |
/site_inbox | Site-level inbox |
/api/v1/instance | Mastodon-compatible instance info |
9. REST API
PieFed's API is intentionally "95% the same as the Lemmy API" to enable reuse of Lemmy's mobile app ecosystem.
| Aspect | Detail |
|---|---|
| Base path | /api/alpha/ |
| Documentation | Swagger at /api/alpha/swagger |
| Total endpoints | 100+ |
| Rate limiting | Applied to creation endpoints |
Compatible Mobile Apps
Voyager, Interstellar (Android/iOS/Linux/Windows), Blorp (iOS), Summit, with Boost and Photon in development.
Endpoint Categories
- Site (5): instance info, configuration
- Communities (17): CRUD, flair, bans, moderation
- Feeds (3): create, edit, list
- Posts (18): CRUD, polls, flair, voting
- Comments (13): CRUD, answer marking
- Private messages (8): send, read, delete
- Users (20): profiles, notifications, flair, bans
- Search (4): content discovery
- Images (4): upload, manage
- Admin (2): site management
Notable Unique Endpoints (beyond Lemmy)
/post/poll_vote— poll voting/comment/mark_as_answer— Q&A answer selection/feed/*— Feed (multi-reddit) management/community/flair/*— flair management/user/set_flair— user flair
10. Moderation and Trust & Safety
PieFed was designed with safety as a first-class concern, drawing inspiration from the Mastodon Covenant and "nudge theory."
Reputation System
- Karma tracking with sortable low-karma account lists
- "Attitude" metric: percentage of downvotes vs upvotes per user
- Visual indicators: red icons for negative karma, double-red for severe, special icon for accounts < 7 days old
- Auto-collapse for comments at -10 or below
Content Filtering
- 3,000+ pre-loaded domain blocklist (disinformation, conspiracy, fake news sites)
- 4chan screenshot detection via image recognition (auto-reported)
- AI content labeling: posts/communities tagged as AI-generated; users can hide all AI content like NSFW
- NSFW and NSFL as separate flags
- Keyword filtering: user-configurable
- Bot content filter: single checkbox
Admin Tools
- Ban / Ban + Purge on user profiles
- IP-based ban evasion detection
- Username keyword filtering (blocks e.g. "1488")
- Web of trust: follow another instance's blocklist automatically
- Registration approval queue
- "Authoritarian Inoculation" feature with default blocks on known extremist instances
Community-Level Moderation
- Per-community downvote policies
- Comment and post locking
- Post approval workflow (optional pre-publication review)
- Contextual warnings above comment forms
- Searchable moderation log
- Federated community bans
newModsWantedflag for moderator recruitment
11. Content Types
| Type | Details |
|---|---|
| Link posts | URL submissions |
| Text posts | Markdown body |
| Image posts | With alt text; width control via  |
| Video posts | Direct upload (v1.5+, admin-configurable) |
| Polls | Question with oneOf/anyOf, up to 15 options, Mastodon-compatible |
| Events | Time, timezone, location, participant count |
| PeerTube videos | Embedded player, auto-import from channels |
| Cross-posts | Deduplicated with consolidated comment views |
| Scheduled posts | With timezone support |
| Wiki pages | Per-community editable wikis |
| Emoji reactions | Unicode and custom (:piefed:), federated as Likes for Lemmy compat |
| Quote posts | v1.6+, Mastodon quote-boost interop |
| StackOverflow Q&A | Comments markable as answers via ChooseAnswer |
| Spoilers | Flair-based with image blurring + inline spoiler text |
12. Interoperability
Lemmy
- Fully compatible: Group communities, Page posts, Note comments, Like/Dislike votes, Announce relay
- API is 95% Lemmy-compatible (mobile apps work)
- Shared extensions:
tagsForPosts,CommunityTag - Limitation: polls and events cannot be posted TO Lemmy communities (prevented in PieFed's code to avoid errors)
- Community outboxes follow Lemmy's
Announce(Create(Page))pattern
Mastodon
- Users follow PieFed communities by mentioning them
- First paragraph becomes post title; rest becomes body
- Works: hashtags, images, alt text, videos, NSFW, polls, markdown, mentions, comments, editing, likes, boosts
- Poll voting is bidirectional
- Quote-boost interop (v1.6+)
/api/v1/instanceMastodon-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
moderatorsproperty alongside Lemmy'sattributedTo
Known Limitations
- "Discoverability between PieFed and other parts of the Fediverse is limited"
- Markdown variants differ slightly from Lemmy's
- Remote Mastodon
Announceactivities without full inlined objects are logged but skipped
13. Installation and Deployment
Bare Metal
git clone https://codeberg.org/rimu/pyfedi.git
python -m venv venv && source venv/bin/activate
pip install wheel && pip install -r requirements.txt
cp env.sample .env # configure SECRET_KEY, DATABASE_URL, etc.
flask db upgrade && flask init-db
gunicorn -b 0.0.0.0:5000 pyfedi:app
Setup reported to take "within half an hour."
Docker (5 services)
| Service | Purpose |
|---|---|
db | PostgreSQL 17 |
redis | Redis 6.2 |
celery | Celery worker for async federation tasks |
app | Flask/Gunicorn web app (port 8030) |
piefed_notifs | FastAPI/Uvicorn real-time notifications (port 8040) |
Other Options
- YunoHost: available in app store (v1.4+)
- Managed hosting: fedihost.co (beta), Elest.io
- S3 storage: Cloudflare R2, Wasabi, Backblaze B2 for media and post archival
Scaling (piefed.social reference: 8-core, 16GB, ~1000 MAU)
- PostgreSQL:
shared_buffers=6GB,effective_cache_size=9GB,max_connections=300 - DB pool:
POOL_SIZE=30,MAX_OVERFLOW=70 - Nginx caching recommended (RAM-backed
/dev/shm/nginx) - Post archival to S3 reduces database size over time
14. Codebase Structure
pyfedi/
├── app/
│ ├── activitypub/ # Federation (routes, signatures, util, actor)
│ ├── admin/ # Admin panel
│ ├── api/alpha/ # Lemmy-compatible REST API
│ ├── auth/ # Authentication
│ ├── chat/ # Real-time chat
│ ├── community/ # Community management
│ ├── feed/ # Feed (multi-reddit) management
│ ├── post/ # Post handling
│ ├── search/ # Search
│ ├── shared/tasks/ # Celery async tasks (adds, blocks, deletes,
│ │ # flags, follows, groups, likes, locks,
│ │ # notes, pages, removes, users, maintenance)
│ ├── plugins/ # Plugin system
│ ├── tag/ # Hashtag management
│ ├── models.py # All DB models (209KB single file)
│ ├── inoculation.py # Anti-propaganda feature
│ └── constants.py
├── migrations/ # Alembic migrations
├── tests/
├── docs/ # Developer docs, AP examples, ERD
├── compose.yaml # Docker Compose (5 services)
├── pyfedi.py # Entry point
├── FEDERATION.md # Federation documentation
└── CONTRIBUTING.md
Key namespaces: app.activitypub, app.api.alpha, app.community,
app.post, app.feed, app.shared.tasks
15. PieFed vs Lemmy — Key Differences for Implementers
| Aspect | PieFed | Lemmy |
|---|---|---|
| Language | Python/Flask | Rust/Actix-web |
| Resource usage | ~1 load avg | ~12 load avg (same hardware) |
Feed actor type | Yes (FEP-1d80) | No |
| Private voting | Proxy user profiles | All votes public/federated |
| Cross-post dedup | Merged comment views | Separate posts |
| AI content flag | genAI property | No |
| NSFL flag | Separate from NSFW | No (NSFW only) |
EmojiReact | Yes (federated as Likes to Lemmy) | No |
ChooseAnswer | Yes (Q&A mode) | No |
Event objects | Yes | No |
PollVote | Yes (Mastodon-compatible) | No native polls |
| Flair federation | flair on Note + tagsForPosts | tagsForPosts only |
| API path | /api/alpha/ | /api/v3/ |
| API compatibility | 95% Lemmy-compatible | — |
| JSON-LD processing | Plain JSON (no expansion) | Plain JSON (no expansion) |
16. Common Implementation Mistakes
-
Assuming PieFed is a Lemmy fork: PieFed is a completely separate Python codebase, not a Rust fork — protocol-compatible but architecturally different
-
Not handling the
Feedactor type: PieFed federatesFeedactors via WebFinger; other software should treat unknown actor types gracefully rather than erroring -
Expecting public votes: PieFed defaults to private voting — vote activities may come from anonymous proxy profiles or not at all. Do not assume vote counts match federated Like/Dislike activities
-
Ignoring
genAIandnsflproperties: PieFed adds these to Group and Page objects — unknown properties should be ignored, not cause parsing errors -
Sending polls/events to PieFed communities hosted on Lemmy: PieFed prevents posting polls and events to remote Lemmy communities because Lemmy doesn't support them — but if you federate these object types to PieFed-hosted communities, they will work
-
Not handling
EmojiReact: PieFed sendsEmojiReactactivities for emoji reactions — these federate asLikeactivities to Lemmy for compatibility, but other implementations may receive the rawEmojiReacttype -
Assuming all communities federate: PieFed supports local-only and private communities that are invisible to federation
-
Not supporting
ChooseAnswer: In Q&A mode communities, PieFed sendsChooseAnsweractivities 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
| Layer | Technology |
|---|---|
| Backend language | PHP |
| Backend framework | Laravel (currently v12) |
| Database | MySQL 8.0 or PostgreSQL 13 |
| Cache / Queue | Redis |
| Queue management | Laravel Horizon |
| OAuth | Laravel Passport |
| Frontend framework | Vue.js 2.6.14 |
| Frontend state | Vuex |
| CSS | Bootstrap |
| Build | Webpack via Laravel Mix |
| Mobile | React Native (iOS + Android) |
| Storage | Local filesystem or S3/Object Storage |
| License | AGPL-3.0 |
| Runtime | PHP 8.3+ (supports 8.4, 8.5), Node.js for assets |
2. Actor Model
Pixelfed uses Person type actors for user accounts:
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://w3id.org/security/v1",
{"pixelfed": "http://pixelfed.org/ns#"}
],
"type": "Person",
"id": "https://pixelfed.example/users/alice",
"preferredUsername": "alice",
"name": "Alice",
"summary": "<p>Bio text</p>",
"inbox": "https://pixelfed.example/users/alice/inbox",
"outbox": "https://pixelfed.example/users/alice/outbox",
"following": "https://pixelfed.example/users/alice/following",
"followers": "https://pixelfed.example/users/alice/followers",
"manuallyApprovesFollowers": false,
"indexable": true,
"publicKey": {
"id": "https://pixelfed.example/users/alice#main-key",
"owner": "https://pixelfed.example/users/alice",
"publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
},
"icon": {
"type": "Image",
"mediaType": "image/jpeg",
"url": "https://pixelfed.example/storage/avatars/alice.jpg"
},
"endpoints": {
"sharedInbox": "https://pixelfed.example/f/inbox"
},
"alsoKnownAs": []
}
Key points:
- The shared inbox path is
/f/inbox(not/inboxas with some other implementations) manuallyApprovesFollowerscontrols locked/private account behaviourindexablesignals whether the account should appear in search indexesalsoKnownAsis present but account migration between servers is not currently supported
Instance Actor
Pixelfed uses an instance-wide actor with "type": "Application" to
sign GET requests to remote instances. This is separate from the
Person actors used by regular accounts. The instance actor is used
for authorized fetch (secure mode) — when a remote server requires
signed GET requests, Pixelfed uses this actor's key.
3. Supported Activities
| Activity | Description |
|---|---|
Accept | Approves follow requests |
Add | Federates Stories (uses Bearcap URIs for access control) |
Announce | Reblogs/boosts |
Create | Creates Note and Question objects |
Delete | Removes Person, Tombstone, and Story objects |
Flag | Federated report functionality |
Follow | Follow request |
Like | Favorites a post |
Reject | Denies follow requests |
Undo | Reverses Announce, Follow, and Like |
Update | Modifies Note (status) and Person (profile) |
View | Story view tracking |
Story:Reaction | Reaction to a Story (Pixelfed-only) |
Story:Reply | Reply to a Story (Pixelfed-only) |
Story:Reaction and Story:Reply are Pixelfed-specific activity types
that are not understood by other Fediverse software.
4. Object Types and Post Structure
Pixelfed supports three object types: Note, Image, and Document.
Posts are represented as Note objects:
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://w3id.org/security/v1",
{"pixelfed": "http://pixelfed.org/ns#"}
],
"type": "Note",
"id": "https://pixelfed.example/p/alice/123456",
"attributedTo": "https://pixelfed.example/users/alice",
"content": "<p>Caption text with #hashtag</p>",
"summary": null,
"inReplyTo": null,
"published": "2025-06-15T12:00:00Z",
"url": "https://pixelfed.example/p/alice/123456",
"sensitive": false,
"to": ["https://www.w3.org/ns/activitystreams#Public"],
"cc": ["https://pixelfed.example/users/alice/followers"],
"attachment": [
{
"type": "Image",
"mediaType": "image/jpeg",
"url": "https://pixelfed.example/storage/m/photo.jpg",
"name": "Alt text description",
"blurhash": "LEHV6nWB2yk8pyoJadR*.7kCMdnj"
}
],
"tag": [
{
"type": "Hashtag",
"href": "https://pixelfed.example/discover/tags/hashtag",
"name": "#hashtag"
}
],
"commentsEnabled": true,
"capabilities": {
"announce": "https://www.w3.org/ns/activitystreams#Public",
"like": "https://www.w3.org/ns/activitystreams#Public",
"reply": "https://www.w3.org/ns/activitystreams#Public"
}
}
Key points:
summaryis used for content warnings (null when not set)attachmentcontainsImageobjects with optionalblurhash- 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 everyonenull— 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=truein server configuration - Support activities:
Add,Delete,View,Story:Reaction,Story:Reply - Transform to
StoryReactionandStoryViewinternal models
Location Geo-tagging
Posts can include a Place object for location data:
"location": {
"type": "Place",
"name": "Paris, France",
"longitude": 2.3522,
"latitude": 48.8566,
"country": "France"
}
Blurhash
Pixelfed includes blurhash on image attachments for compact preview
placeholders. This uses the toot:blurhash property from Mastodon's
namespace (http://joinmastodon.org/ns#). The blurhash is a short
string that encodes a blurred preview of the image, useful for showing
a placeholder while the full image loads.
Federated Groups
Pixelfed supports federated Groups via FEP-400e and FEP-1b12 extensions.
Group actors use "type": "Group" with standard inbox/outbox
collections.
6. JSON-LD Context
Pixelfed uses a multi-context approach with four namespaces:
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://w3id.org/security/v1",
{"pixelfed": "http://pixelfed.org/ns#"},
{"toot": "http://joinmastodon.org/ns#"}
]
| Namespace | Purpose |
|---|---|
https://www.w3.org/ns/activitystreams | ActivityStreams 2.0 vocabulary |
https://w3id.org/security/v1 | W3C Security Vocabulary (publicKey) |
http://pixelfed.org/ns# | Pixelfed-specific properties (capabilities, commentsEnabled) |
http://joinmastodon.org/ns# | Mastodon compatibility (blurhash, indexable) |
When processing Pixelfed JSON-LD documents, unknown properties from the
pixelfed: and toot: namespaces should be ignored rather than causing
errors.
7. HTTP Signatures and WebFinger
HTTP Signatures
- Pixelfed signs every POST and GET request
- All incoming POST requests must be signed
- GET requests may require signatures (configurable — this is "authorized fetch" or "secure mode")
- The instance
Applicationactor's key is used for signing GET requests - Individual
Personactor keys are used for signing POST requests (activities from that user)
WebFinger
Pixelfed requires each ActivityPub actor to uniquely map to an acct:
URI resolvable via WebFinger at /.well-known/webfinger. Standard
WebFinger resolution applies.
8. Collections
Three primary user collections using the OrderedCollection pattern:
| Collection | Path | Content |
|---|---|---|
| Following | /users/{username}/following | Accounts this user follows |
| Followers | /users/{username}/followers | Accounts following this user |
| Outbox | /users/{username}/outbox | User's published statuses |
totalItems may return 0 if the collection is hidden per user
privacy preference. This is intentional, not a bug — do not assume an
empty collection means the user has no followers/following.
9. Mastodon API Compatibility
Pixelfed implements a subset of the Mastodon REST API, allowing Mastodon client apps to work with Pixelfed instances.
Working endpoints
- Account endpoints (verify_credentials, update_credentials, relationships, search)
- Status endpoints (create, view, delete, favourite, boost)
- Timeline endpoints (home, public, hashtag)
- Notification endpoints
- OAuth 2.0 authentication (requires
OAUTH_ENABLED=true)
Known compatibility gaps
- OOB OAuth redirect (
urn:ietf:wg:oauth:2.0:oob) is not supported — apps relying on this flow will fail - Authorization code grant type has reported issues
- Some public API endpoints incorrectly require OAuth tokens
- Pixelfed-specific features (Stories, Collections, capabilities) are not accessible via the Mastodon API — only through Pixelfed's own API
10. Federation Interoperability
Cross-platform behaviour
| Feature | Pixelfed to Mastodon | Mastodon to Pixelfed |
|---|---|---|
| Photo posts | Appear as image posts with text | Appear normally if image attached |
| Text-only posts | N/A (Pixelfed requires media) | Not displayed on Pixelfed |
| Album posts (>4 images) | Only first 4 images shown | N/A (Mastodon max 4) |
| Stories | Not visible | N/A |
| Boosts | Appear as boosts | Appear as boosts |
| Likes/Favourites | Federate normally | Federate normally |
| Replies | Federate, but display may be incomplete | Federate normally |
| Content warnings | Show as content warnings | Show as content warnings |
Known federation issues
- Pixelfed does not display older posts created before federation with a particular instance began
- Comment counts may be inaccurate (showing N comments but not all visible) due to incomplete federation of reply threads
- Nested reply threading can be incomplete across platforms
- Profile photo updates sometimes fail to federate properly
- The
capabilitiesextension is not respected by other platforms — a post with"reply": nullcan still receive replies from Mastodon users
11. Configuration Reference
Federation
| Variable | Description |
|---|---|
ACTIVITY_PUB | Enable/disable federation entirely |
AP_REMOTE_FOLLOW | Allow/prevent remote following |
Media
| Variable | Default | Description |
|---|---|---|
MAX_PHOTO_SIZE | 15000 (KB) | Per-file size limit (15 MB) |
MAX_ACCOUNT_SIZE | 1000000 (KB) | Per-user total storage (1 GB) |
MAX_ALBUM_LENGTH | 4 | Items per post |
IMAGE_QUALITY | 80 | JPEG quality 1-100 |
PF_OPTIMIZE_IMAGES | — | Automatic image optimization |
PF_OPTIMIZE_VIDEOS | — | Automatic video optimization |
PF_ENABLE_CLOUD | — | S3/Object Storage support |
Accounts
| Variable | Default | Description |
|---|---|---|
MAX_CAPTION_LENGTH | 500 | Caption character limit |
MAX_BIO_LENGTH | 125 | Bio character limit |
MAX_NAME_LENGTH | 30 | Display name limit |
OPEN_REGISTRATION | true | New account creation |
PF_MAX_USERS | 1000 | User registration cap |
ENFORCE_EMAIL_VERIFICATION | — | Email confirmation required |
Features
| Variable | Default | Description |
|---|---|---|
STORIES_ENABLED | false | Stories functionality |
OAUTH_ENABLED | — | Third-party app authentication |
INSTANCE_DISCOVER_PUBLIC | — | Public explore feature access |
INSTANCE_PUBLIC_HASHTAGS | — | Anonymous hashtag feed browsing |
12. Common Implementation Mistakes
- Ignoring the
capabilitiesextension: when federating with Pixelfed, be aware thatcapabilitiesexists — 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: 0as empty: Pixelfed returns0for hidden collections — a followers count of 0 does not mean the account has no followers - Wrong shared inbox path: Pixelfed uses
/f/inboxas the shared inbox, not/inbox— always read theendpoints.sharedInboxvalue 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
| Component | Technology |
|---|---|
| Backend | Go (golang) — 64% of codebase |
| Templates | Go Template — 24% |
| Styling | LESS — 6.5% |
| Client-side | JavaScript — 3.8% |
| Database | MySQL/MariaDB 5.6+ or SQLite |
| Rich editor | ProseMirror (WYSIWYG "classic" mode) |
| License | AGPL-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 thenameproperty.Note: Posts without paragraph breaks (single-paragraph). Can be forced for all posts vianotes_only = trueconfiguration.
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):
| Activity | Trigger |
|---|---|
Create{Article} or Create{Note} | Post published |
Update{Article} or Update{Note} | Post edited |
Delete | Post deleted |
Inbound (WriteFreely receives):
| Activity | Effect |
|---|---|
Follow | Remote user follows a blog |
Undo{Follow} | Remote user unfollows |
Like | Remote 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
| Field | Description | Default |
|---|---|---|
federation | ActivityPub federation toggle | true |
notes_only | Send all posts as Note (not Article) | false |
public_stats | NodeInfo statistics visibility | true |
Other Notable Settings
| Field | Description | Default |
|---|---|---|
single_user | Single-blog instance mode | false |
editor | Editor template: pad, bare, classic | pad |
open_registration | Public signup (multi-user) | true |
max_blogs | Blogs per account (multi-user) | 5 |
default_visibility | New blog visibility | unlisted |
local_timeline | Instance reader (multi-user) | true |
monetization | Web Monetization support | true |
gopher_port | Gopher 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:
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| POST | /api/posts | Optional | Create post |
| GET | /api/posts/{id} | No | Retrieve post |
| POST | /api/posts/{id} | Optional | Update post |
| DELETE | /api/posts/{id} | Optional | Delete post |
| POST | /api/posts/claim | Required | Claim anonymous posts |
Collections (Blogs):
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| POST | /api/collections | Required | Create collection |
| GET | /api/collections/{alias} | No | Get metadata |
| POST | /api/collections/{alias}/posts | Required | Publish to blog |
| GET | /api/collections/{alias}/posts | No | List posts |
| GET | /api/collections/{alias}/posts/{slug} | No | Get single post |
Users:
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| POST | /api/auth/login | No | Authenticate |
| GET | /api/me | Required | Get user info |
| GET | /api/me/posts | Required | List user's posts |
| GET | /api/me/collections | Required | List 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.instancein 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:
| Service | Purpose |
|---|---|
| Write.as | Hosted blogging platform ($1-10/month) |
| WriteFreely | Open-source software (self-hosted) |
| WriteFreely.host | Managed WriteFreely community hosting |
| Snap.as | Minimalist photo sharing |
| Remark.as | Commenting system for Write.as blogs |
| Submit.as | Accept writing submissions |
| Read.as / ReadFreely | ActivityPub 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
| Aspect | WriteFreely | Plume |
|---|---|---|
| Language | Go | Rust |
| Federation model | Write-only (broadcast) | Bidirectional (shows replies) |
| Customization | Custom CSS only | Themes, fonts, layouts |
| Maintenance | Actively maintained | Not actively maintained |
| Object types | Article + Note | Article |
WriteFreely vs Ghost
| Aspect | WriteFreely | Ghost |
|---|---|---|
| Language | Go | Node.js |
| AP integration | Since 2018 (core) | Since 2024 (core) |
| Focus | Minimalist writing | Full-featured CMS |
| Image hosting | None (external only) | Built-in |
| Newsletters | Mailgun integration | Built-in |
| Themes | Custom CSS | Full theme system |
| Resources | 256 MB RAM | 1 GB+ RAM |
9. Interoperability Notes for Implementers
-
Blogs are
Personactors — each WriteFreely blog (collection) presents itself as aPersonactor with a fediverse handle of@alias@instance.com. Follow a blog by sendingFollowto this actor. -
Write-only federation — WriteFreely will never send
Follow,Announce,Like, or reply activities. It only sendsCreate,Update, andDeletefor its own posts. If your software expects bidirectional interaction, WriteFreely will not reciprocate. -
Article vs Note distinction — multi-paragraph posts arrive as
Articleobjects (withnamecontaining the title), single-paragraph posts arrive asNoteobjects (noname). If an instance hasnotes_only = true, all posts arrive asNote. Your software should handle both types from WriteFreely. -
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.
-
Like tracking — since v0.16, WriteFreely tracks
Likeactivities and shows a count to the blog author. SendingLiketo a WriteFreely blog will be acknowledged, butUndo{Like}handling may vary. -
No shared inbox optimization — WriteFreely stores shared inbox URLs from remote actors but primarily uses individual inboxes. Verify delivery works with both paths.
-
Post excerpts on microblogging platforms — since v0.16, WriteFreely includes
preview/summaryfields onArticleobjects. Mastodon and Threads will show an excerpt with a link rather than just a bare link. Older WriteFreely versions may send Articles without summaries. -
NodeInfo identifies the software — look for
"name": "writefreely"in the NodeInfo software block to identify WriteFreely instances. The metadata includes WriteFreely-specific fields likemaxBlogs,publicReader, andinvites. -
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.
-
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