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.

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

• 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

bun test                    # Run unit tests
bun run integration         # Run integration tests (requires Redis + Docker)
bun run lint                # Check code style
bun run lint:fix           # Auto-fix linting issues

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

Project created and maintained by Nick Jennings

Logo design by Jan-Christoph Borchardt

Sponsored by NLNET