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 powered by Bun, Sockethub is organized as a monorepo with packages for the server, client, schemas, and platforms.

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

Documentation Hub - Complete documentation index and guides
Getting Started - Installation and quick start
Client Guide - Browser client library usage
Platform Development - Creating custom platforms
Architecture - Technical architecture overview
Configuration - Server configuration options
Contributing - Developer workflow and commands
Performance Testing - Load testing and benchmarking

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

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.

Dummy - Example platform for developers
Platform Development docs - Full guide

Quick Start

Requirements

Bun v1.2+
Redis (data layer and job queue)

CLI Install

npm install -g sockethub
sockethub --help

# Install dependencies
bun install

# Start Redis (required for data layer)
# - Docker: docker run -d -p 6379:6379 redis:alpine
# - Homebrew: brew install redis && brew services start redis

# Start dev server with examples
bun run dev

Open http://localhost:10550 for the interactive examples.

Production

bun run build
bun run start

Environment Variables

For debugging and configuration options, see the Server package documentation.

Debug logging:

DEBUG=sockethub* bun run dev

Packages

Core Infrastructure

sockethub - Main meta-package for installing Sockethub
@sockethub/client - Browser client library for connecting to Sockethub
@sockethub/data-layer - Redis-based job queue and credential storage
@sockethub/schemas - ActivityStreams validation and TypeScript types
@sockethub/server - Core server implementation with Socket.IO interface

Libraries

@sockethub/activity-streams - ActivityStreams object utilities
@sockethub/crypto - Cryptographic utilities for secure storage
@sockethub/irc2as - IRC to ActivityStreams translation
@sockethub/logger - Winston-based logger with global configuration

Platform Implementations

@sockethub/platform-dummy - Example platform for development reference
@sockethub/platform-feeds - RSS and Atom feed processing
@sockethub/platform-irc - IRC protocol support
@sockethub/platform-metadata - Link preview and metadata extraction
@sockethub/platform-xmpp - XMPP protocol support

Example Package

@sockethub/examples - Example client app (served with sockethub --examples)

Credits

Project created and maintained by Nick Jennings

Logo design by Jan-Christoph Borchardt

Name	sockethub
Description	Bridges web applications to messaging protocols (IRC, XMPP, RSS/Atom) via ActivityStreams. Use when building chat clients, connecting to IRC channels, sending XMPP messages, fetching RSS feeds, or creating protocol-agnostic messaging applications.

sockethub

SKILL.md