sockudo

Sockudo

A self-hosted realtime platform: Pusher-compatible at the edge, Sockudo-native where you need recovery, history, mutable messages, push, AI Transport, and first-party SDKs.

What Sockudo Is

Sockudo is a high-performance Rust realtime server for WebSocket and HTTP publish workloads. It keeps strict Protocol V1 compatibility with the Pusher protocol, then adds Protocol V2 features for teams that need stronger delivery semantics and product-level control.

This repository is now the Sockudo monorepo. It contains the server, Rust workspace crates, dashboard, deployment assets, docs, official realtime client SDKs, HTTP server SDKs, and the TypeScript AI Transport SDK.

Highlights

• Pusher-compatible WebSocket and HTTP APIs for Protocol V1 clients.
• Protocol V2 with sockudo: events, serials, message IDs, recovery, rewind, tags, deltas, and mutable message events.
• Horizontal fanout through Redis, Redis Cluster, NATS, RabbitMQ, Google Pub/Sub, Kafka, Pulsar, and Apache Iggy.
• Durable history, hot replay buffers, two-tier recovery, until_attach history reads, and degraded/reset-required continuity state.
• Versioned mutable messages with create, update, delete, append, summary, latest-visible reads, and version history.
• Presence membership plus retained presence-history transitions and snapshots.
• Message annotations for reactions, receipts, moderation, summary projection, and raw annotation streams.
• Push notification pipeline for FCM, APNs, Web Push, HMS, and WNS.
• Prometheus metrics, webhook delivery, rate limiting, app managers, TLS, Docker Compose, and Helm.
• Optional AI Transport built on the same versioned-message, history, recovery, push, and presence primitives instead of a parallel streaming path.
• Optional ably-compat facade exposing a reduced Ably AI Transport compatibility surface for tested AI Transport workloads.

Monorepo Layout

…

The SDK directories preserve their original repository names so package metadata, release scripts, and issue references remain recognizable.

Protocols

Use Protocol V1 when you need drop-in Pusher behavior. Use Protocol V2 when clients and server SDKs can rely on Sockudo-native recovery, history, mutation, annotation, filtering, and AI Transport semantics. Protocol defaults vary by SDK; check each package README before assuming V2 is enabled.

Quick Start

Docker Compose

git clone https://github.com/sockudo/sockudo.git
cd sockudo
make up

Default local services:

Linux Binary

Install the latest verified x86_64 or ARM64 release into ~/.local/bin:

curl --proto '=https' --tlsv1.2 -sSfL \
  https://sockudo.io/install.sh | sh

The installer detects GNU libc or musl and verifies the archive's SHA-256 checksum. See the installation guide for version pinning and custom installation paths.

From Source

rustup toolchain install stable
git clone https://github.com/sockudo/sockudo.git
cd sockudo

cargo run -p sockudo

Build with a production-oriented feature set:

cargo build -p sockudo --release --features "v2,redis,postgres,push"

Build everything the server can expose:

cargo build -p sockudo --release --features full

Kubernetes

helm install sockudo oci://ghcr.io/sockudo/charts/sockudo --version 4.7.0

Or from a checkout, when developing the chart itself:

helm install sockudo ./charts/sockudo

Example production shape with Redis, ingress, autoscaling, and monitoring:

helm install sockudo oci://ghcr.io/sockudo/charts/sockudo --version 4.7.0 \
  --set config.adapterDriver=redis \
  --set redis.host=redis-master \
  --set redis.existingSecret=my-redis-secret \
  --set defaultApp.existingSecret=my-default-app-secret \
  --set autoscaling.enabled=true \
  --set pdb.enabled=true \
  --set ingress.enabled=true \
  --set serviceMonitor.enabled=true

When defaultApp.existingSecret is set, the Secret must contain default-app-secret and can also include default-app-id and default-app-key.

Client SDKs

Realtime clients live under client-sdks/.

SDK CI and publishing are managed from root workflows. See the 2026 SDK publishing runbook before releasing packages or changing registry setup. Registry-native packages publish through protected workflows where supported. SwiftPM packages are mirrored to standalone package repositories.

JavaScript example:

import Sockudo from "@sockudo/client";

const sockudo = new Sockudo("app-key", {
  wsHost: "127.0.0.1",
  wsPort: 6001,
  wssPort: 6001,
  forceTLS: false,
  enabledTransports: ["ws"],
  protocolVersion: 2,
});

const channel = sockudo.subscribe("public-updates");
channel.bind("price-updated", (payload) => {
  console.log(payload);
});

AI Transport example:

import { ClientSessionProvider, useView } from "@sockudo/ai-transport/react";

See client-sdks/sockudo-ai-transport-js/README.md for React, Vue, Svelte, Vercel AI SDK, and direct provider helpers.

Server SDKs

HTTP/server SDKs live under server-sdks/. They publish events, sign private and presence channel auth, authenticate users, validate webhooks, query state, and expose Sockudo-native APIs such as idempotent publishing, history, mutable messages, annotations, and push where implemented.

SDK CI and publishing are managed from root workflows. See the 2026 SDK publishing runbook before releasing packages or changing registry setup. Registry-native packages publish through protected workflows where supported. Go modules and SwiftPM publish from this monorepo with package-manager-native tags and manifests. The PHP SDK is mirrored to sockudo/sockudo-http-php for Packagist.

Node.js example:

import { Sockudo } from "sockudo";

const sockudo = new Sockudo({
  appId: "app-id",
  key: "app-key",
  secret: "app-secret",
  host: "127.0.0.1",
  port: 6001,
  useTLS: false,
});

await sockudo.trigger("orders", "order.created", { id: "ord_123" });

Python example:

from sockudo_http import Config, Sockudo

sockudo = Sockudo(
    Config(
        app_id="app-id",
        key="app-key",
        secret="app-secret",
        host="127.0.0.1",
        port=6001,
    )
)

sockudo.trigger("orders", "order.created", {"id": "ord_123"})

Server Workspace

The Rust workspace is split by responsibility:

The Rust SDK at server-sdks/sockudo-http-rust is intentionally excluded from the root Cargo workspace so it can keep its own package and release lifecycle.

Feature Flags

Common server features:

Examples:

cargo build
cargo build --no-default-features
cargo build --features "redis,postgres"
cargo build --features "v2,ai-transport,redis,postgres,push"
cargo build --release --features full

Configuration

Sockudo prefers TOML and falls back to JSON. The default local config is config/config.toml.

Minimal local shape:

port = 6001
host = "0.0.0.0"
debug = false

[app_manager]
driver = "memory"

[app_manager.array]
[[app_manager.array.apps]]
id = "app-id"
key = "app-key"
secret = "app-secret"
enabled = true

[adapter]
driver = "local"

[cache]
driver = "memory"

[queue]
driver = "memory"

Major runtime sections:

Reference docs:

• Deployment guide
• Static configuration
• [