Kb Pixelfed

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

# Pixelfed — Complete Reference

## Overview

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

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

---

## 1. Technical Stack

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

---

## 2. Actor Model

Pixelfed uses `Person` type actors for user accounts:

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

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

### Instance Actor

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

---

## 3. Supported Activities

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

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

---

## 4. Object Types and Post Structure

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

Posts are represented as `Note` objects:

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

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

---

## 5. Pixelfed-Specific Extensions

### Capabilities

Per-post access control added to `Note` objects:

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

Each capability value is either:
- `"https://www.w3.org/ns/activitystreams#Public"` — allowed for everyone
- `null` — disabled

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

### commentsEnabled

A boolean property on `Note` objects:

```json
"commentsEnabled": true
```

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

### Stories

Ephemeral 24-hour content, similar to Instagram Stories:

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

### Location Geo-tagging

Posts can include a `Place` object for location data:

```json
"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:

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

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

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

---

## 7. HTTP Signatures and WebFinger

### HTTP Signatures

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

### WebFinger

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

---

## 8. Collections

Three primary user collections using the `OrderedCollection` pattern:

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

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

---

## 9. Mastodon API Compatibility

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

### Working endpoints

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

### Known compatibility gaps

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

---

## 10. Federation Interoperability

### Cross-platform behaviour

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

### Known federation issues

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

---

## 11. Configuration Reference

### Federation

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

### Media

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

### Accounts

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

### Features

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

---

## 12. Common Implementation Mistakes

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