A protocol gateway for the web.

Sockethub is a translation layer for web applications to communicate with other protocols and services that are traditionally either inaccessible or impractical to use from in-browser JavaScript.

Built with modern TypeScript and powered by Bun, Sockethub is organized as a monorepo containing multiple packages that work together to provide a robust, extensible platform gateway.

Using ActivityStreams (AS) objects to pass messages to and from the web app, Sockethub acts as a smart proxy server/agent, which can maintain state, and connect to sockets, endpoints, and networks that would otherwise, be restricted from an application running in the browser.

Originally inspired as a sister project to RemoteStorage, and assisting in the development of unhosted and noBackend applications, Sockethub's functionality can also fit into a more traditional development stack, removing the need for custom code to handle various protocol specifics at the application layer.

Example uses of Sockethub include:

• Chat protocols: XMPP, IRC

• Feed processing: RSS, Atom feeds

• Metadata discovery: Link preview generation, metadata extraction

• Protocol translation: Converting between web-friendly ActivityStreams and traditional protocols

Additional protocols like SMTP, IMAP, Nostr, and others can be implemented as custom platforms.

The architecture of Sockethub is extensible and supports easy implementation of additional 'platforms' to carry out tasks.

Sockethub uses a multi-process architecture for stability and isolation:

• Main Server (packages/server/) - Socket.IO connections, middleware pipeline for validation and routing
• Platform Processes - Each protocol (IRC, XMPP, Feeds) runs as an isolated child process
• Job Queue - Redis-backed BullMQ ensures reliable message delivery between server and platforms
• Data Layer - Encrypted credential storage and session management in Redis
• ActivityStreams - Uniform message format for all platform communication

Request Flow:

1. Client connects via Socket.IO
2. Messages validated through middleware pipeline
3. Credentials encrypted and stored per-session in Redis
4. Messages queued to appropriate platform instance
5. Platform processes handle protocol-specific logic
6. Responses sent back through Socket.IO

For detailed architecture documentation, see Architecture Overview.

• Documentation Hub - Complete documentation index and guides
• Getting Started - Installation and quick start
• Client Library - Browser client library usage
• Platform Development - Creating custom platforms
• Architecture - Technical architecture overview
• Deployment - Production deployment guides

We use ActivityStreams to map the various actions of a platform to a set of AS '@type's which identify the underlying action. For example, using the XMPP platform, a friend request/accept cycle would use the activity stream types 'request-friend', 'remove-friend', 'make-friend'.

Making a platform is as simple as creating a platform module that defines a schema and a series of functions that map to ActivityStream verbs. Each platform can be enabled/disabled in the config.json.

• Feeds - RSS and Atom feed processing
• IRC - Internet Relay Chat protocol support
• XMPP - Extensible Messaging and Presence Protocol
• Metadata - Link preview and metadata extraction

• Dummy - Example platform implementation for developers

For platform development guidance, see the Platform Development documentation.

Note: This is a monorepo using Bun workspaces managed by Lerna Lite.

• Bun v1.2+ (Node.js runtime and package manager)
• Redis server (for data layer and job queue)

# Install dependencies
bun install

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

# Build and start development server with examples
bun run dev

Browse to http://localhost:10550 to try the interactive examples.

# Build for production
bun run build

# Start production server (examples disabled)
bun run start

# Testing
bun test                    # Run unit tests across all packages
bun run integration         # Run both Redis and browser integration tests
bun run integration:redis   # Run Redis integration tests with Docker
bun run integration:browser # Run browser integration tests with Docker

# Code Quality
bun run lint                # Run Biome linter and markdown lint
bun run lint:fix           # Auto-fix linting issues

# Maintenance
bun run clean              # Clean build artifacts
bun run clean:deps         # Clean dependencies and node_modules

# Docker
bun run docker:start       # Start Prosody and Sockethub services
bun run docker:start:redis # Start only Redis service
bun run docker:stop        # Stop all Docker services

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

Debug logging:

DEBUG=sockethub* bun run dev

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

• @sockethub/examples - Interactive web examples and demos

• @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

• @sockethub/activity-streams - ActivityStreams object utilities
• @sockethub/crypto - Cryptographic utilities for secure storage
• @sockethub/irc2as - IRC to ActivityStreams translation

• packages/sockethub/sockethub.config.json - Main configuration file
• packages/server/src/sockethub.ts - Main server class handling Socket.IO connections
• packages/server/src/platform-instance.ts - Platform process management
• packages/server/src/middleware/ - Request processing pipeline
• packages/data-layer/src/job-queue.ts - Redis-based job queue (BullMQ)
• packages/data-layer/src/credentials-store.ts - Encrypted credential storage
• packages/platform-*/ - Individual protocol implementations

Each platform must:

1. Implement the PlatformInterface from @sockethub/schemas
2. Define a schema with supported message types and credential requirements
3. Run as an isolated child process (managed by the server)
4. Translate between protocol-specific messages and ActivityStreams objects

See the Platform Development documentation and Dummy platform for a complete reference implementation.

• Process Isolation: Platforms run as separate child processes for stability
• Job Queue: All platform communication goes through Redis-backed BullMQ
• Middleware Pipeline: Requests flow through validation, credential storage, and routing
• Session Management: Credentials are encrypted per-session and isolated per connection
• ActivityStreams: Use ActivityStreams objects as the uniform message format

Project created and maintained by Nick Jennings

Logo design by Jan-Christoph Borchardt

Sponsored by NLNET