Sockethub
A protocol gateway for the web.
Sockethub lets browser apps talk to IRC, XMPP, feeds, and other protocols using
one ActivityStreams JSON format. Your app sends a single message shape, and
Sockethub handles connections, credentials, and protocol translation.
What You Can Do
- Send and receive chat messages (IRC, XMPP)
- Fetch and parse feeds (RSS, Atom)
- Generate link previews and metadata
- Add new protocols as custom platforms
ActivityStreams In/Out
Sockethub uses ActivityStreams JSON for all platforms. Your app sends the same
shape for IRC, XMPP, feeds, and more, and receives the same shape back. Only
the @context changes.
Side-by-side Examples
The @context selects a platform; the rest stays consistent.
About
Sockethub is a translation layer for web applications to communicate with
protocols and services that are impractical to use from in-browser JavaScript.
It runs server-side, keeps long-lived connections, and exposes everything as
ActivityStreams JSON.
Built with modern TypeScript and running on Node.js, Sockethub is organized as a
monorepo with packages for the server, client, schemas, and platforms.
(Development uses Bun as the toolchain; see
Contributing.)
Originally inspired as a sister project to
RemoteStorage, and assisting in the development of
unhosted and noBackend,
Sockethub also fits into traditional stacks by removing protocol-specific code
from the application layer.
Architecture
Sockethub runs each protocol in its own process and moves messages through
Redis so browsers can talk to long-lived connections safely.
- Main Server (
packages/server/) - Socket.IO, validation, routing
- Platform Processes - One process per protocol
- Job Queue - Redis-backed BullMQ between server and platforms
- Data Layer - Encrypted credentials and session state in Redis
Request Flow:
- Client connects via Socket.IO
- Message validated and routed
- Credentials are encrypted and stored per session in Redis
- Message queued to platform
- Platform responds via Socket.IO
For detailed architecture documentation, see Architecture.
Documentation
Capabilities
Sockethub standardizes platform actions as ActivityStreams type values. For
example, an XMPP friend request can be modeled as request-friend,
remove-friend, and make-friend in a consistent format.
Included Platforms
- CardDAV - Address-book and contact synchronization
- CalDAV - Calendar and task synchronization
- Feeds - RSS and Atom feed processing
- IRC - Internet Relay Chat protocol support
- XMPP - Extensible Messaging and Presence Protocol
- Metadata - Link preview and metadata extraction
Build Your Own
Create a platform module that defines a schema and maps ActivityStreams verbs.
Enable or disable platforms in config.json.
Quick Start
Requirements
- Node.js v20+ (Sockethub runs on Node.js)
- Redis (data layer and job queue)
Install & Run
# Start Redis (required for data layer)
# - Docker: docker run -d -p 6379:6379 redis:alpine
# - Homebrew: brew install redis && brew services start redis
# Install and run the server (Node.js)
npm install -g sockethub
sockethub --help
sockethub --host 0.0.0.0
Or run with Docker (docker compose up sockethub), which builds and runs the
server on Node.js.
Develop from source
Contributors use Bun as the toolchain. See Contributing
for the full workflow.
bun install # install workspace dependencies
bun run dev # dev server with examples, HTTP actions, and hot reload
Open http://localhost:10550/examples for the interactive examples. The root
URL serves a server info page.
Environment Variables
For debugging and configuration options, see the Server package documentation.
Packages
Core Infrastructure
Libraries
Platform Implementations
Example Package
Credits
Project created and maintained by Nick Jennings
Logo design by Jan-Christoph Borchardt
Sponsored by NLNET
