Zero to Fediverse in 60 seconds.
Fedbox is the fastest way to get your own identity on the Fediverse. Run your own ActivityPub server, federate with Mastodon, and own your social presence.
# Install
npm install -g fedbox
# Set up your identity
fedbox init
# Start your server
fedbox start
# Post something!
fedbox post "Hello, Fediverse!"That's it. You're on the Fediverse.
# Setup
fedbox init # Set up your identity
fedbox start # Start full ActivityPub server
fedbox profile [port] # Start profile-only server (for editing)
fedbox status # Show your profile info
# Social
fedbox post "text" # Post a message to followers
fedbox follow @user@domain # Follow someone
fedbox timeline # View posts from people you follow
fedbox reply <url> "text" # Reply to a post
fedbox posts # View your own posts
# Maintenance
fedbox clean # Remove database
fedbox clean --all # Remove database and config
fedbox help # Show all commandsVisit your profile page and click Edit to change:
- Display name
- Bio
- Avatar (upload image)
- Nostr pubkey (64-char hex)
fedbox profile
# Visit http://localhost:3000/
# Click "Edit" to modify your profileLink your Nostr identity by adding your pubkey (64-char hex):
{
"nostrPubkey": "124c0fa99407182ece5a24fad9b7f6674902fc422843d3128d38a0afbee0fdd2"
}Your actor will include:
{
"alsoKnownAs": ["did:nostr:124c0fa99407182ece5a24fad9b7f6674902fc422843d3128d38a0afbee0fdd2"]
}This follows the did:nostr spec.
Fedbox uses Solid-style WebID URIs:
/alice— Profile document (HTML + JSON-LD)/alice#me— WebID (the Person/Actor)
This makes profiles compatible with both ActivityPub and Solid ecosystems.
Fedbox supports separating identity (profile) from federation (AP server):
Profile Server (static host) AP Server (fedbox)
─────────────────────────── ─────────────────
https://me.example.com https://fedbox.example.com
/alice /alice/inbox
/alice#me ──points to──► /alice/outbox
/alice/followers
Profile-only config (fedbox.json):
{
"username": "alice",
"displayName": "Alice",
"summary": "My bio",
"apServer": "https://fedbox.example.com",
"nostrPubkey": "124c0fa9..."
}The profile can be hosted anywhere (GitHub Pages, S3, any static server). The AP server handles federation.
Fedbox can fetch your identity from a remote static HTML page containing a JSON-LD data island:
Static HTML profile (hosted anywhere):
<!DOCTYPE html>
<html>
<head>
<script type="application/ld+json">
{
"@context": ["https://www.w3.org/ns/activitystreams", "https://w3id.org/security/v1"],
"type": "Person",
"id": "https://me.example.com/alice#me",
"preferredUsername": "alice",
"name": "Alice",
"publicKey": {
"id": "https://me.example.com/alice#main-key",
"publicKeyPem": "-----BEGIN PUBLIC KEY-----..."
}
}
</script>
</head>
<body>...</body>
</html>Fedbox config (fedbox.json):
{
"username": "alice",
"profileUrl": "https://me.example.com/alice",
"domain": "fedbox.example.com"
}Fedbox extracts the JSON-LD, merges it with local AP endpoints (inbox, outbox, etc.), and serves with proper content negotiation. This allows your identity to live on a static homepage while fedbox handles ActivityPub federation.
To federate with the wider Fediverse, you need a public HTTPS URL:
# In another terminal
ngrok http 3000Copy your ngrok URL and add it to fedbox.json:
{
"domain": "abc123.ngrok.io"
}Restart your server. Search for @yourname@abc123.ngrok.io on Mastodon.
- Your own identity —
@you@yourdomain.com - Web UI editing — Edit profile in browser
- Nostr identity — Link via
did:nostr - Solid-compatible — WebID at
/username#me - Separated architecture — Profile and AP server can be separate
- Post from CLI —
fedbox post "Hello world" - Follow anyone —
fedbox follow @user@mastodon.social - View timeline —
fedbox timeline - Reply to posts —
fedbox reply <url> "Nice!" - ActivityPub compatible — Works with Mastodon, Pleroma, Pixelfed, etc.
- HTTP Signature verification — Secure federation
- Rate limiting — Protection against abuse
- Persistent storage — SQLite database
After fedbox init, you'll have a fedbox.json:
{
"username": "alice",
"displayName": "Alice",
"summary": "Hello, Fediverse!",
"port": 3000,
"domain": null,
"apServer": null,
"profileUrl": null,
"nostrPubkey": null,
"avatar": null,
"publicKey": "...",
"privateKey": "..."
}| Field | Description |
|---|---|
domain |
Your public domain (for federation) |
apServer |
External AP server URL (for separated mode) |
profileUrl |
Remote HTML profile URL (extracts JSON-LD data island) |
nostrPubkey |
64-char hex Nostr pubkey |
avatar |
Avatar filename in public/ |
Fedbox uses microfed for ActivityPub primitives:
- Profile — Your actor/identity with JSON-LD
- Inbox — Receive follows, likes, boosts, posts
- Outbox — Your posts
- WebFinger — So others can find you
- HTTP Signatures — Secure signed requests
- Nodeinfo — Server discovery
Data is stored in SQLite (data/fedbox.db).
- Node.js 18+
- For federation: ngrok or a public server with HTTPS
MIT
Built with microfed. Happy federating! 📦