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 (single node or replicated VSR cluster).
• 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

crates/              Rust server crates and libraries
benches/ai/          Permanent Criterion benchmarks for AI hot paths
benches/presence/    Presence performance budgets
client-sdks/         Realtime client SDKs and AI Transport SDK
server-sdks/         HTTP/server SDKs for backend publishers
dashboard/           Operator API and Vue UI
docs/                Documentation site content
config/              Local configuration examples
ops/                 Migrations and operational assets
charts/              Helm chart
tests/               Conformance, dashboard, load, and binary fixtures
tools/               Probes, chaos tooling, and helper utilities

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
• Kubernetes and Helm
• Cloud platforms
• Capacity planning
• Configuration
• Environment variables
• HTTP endpoints

AI Transport

AI Transport is default-off and Protocol V2-only. Enable it with both Cargo and runtime config:

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

[versioned_messages]
enabled = true

[history]
enabled = true

[ai_transport]
enabled = true

[[ai_transport.channels]]
prefix = "ai:"

Operational rule: append rollup only changes WebSocket egress. Persistence, version storage, history, recovery, push, and webhooks still see every original mutation.

Useful docs:

• AI Transport overview
• Ably AI Transport compatibility
• AI Transport conventions
• Token streaming rollup
• Production checklist

MCP for AI Agents

Sockudo exposes a Model Context Protocol (MCP) server so agents can inspect channels, read history and presence, publish events, mutate versioned messages, manage push, and triage incidents through scoped, audited tools. Build with --features mcp and enable [mcp] with bearer tokens, or run the standalone sockudo-mcp binary over stdio against any deployment:

cargo install --path crates/sockudo-mcp --features cli
claude mcp add sockudo -- sockudo-mcp --url https://rt.example.com --app app-1:key:secret

See MCP server.

Development

Server checks:

cargo fmt --all
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Focused server checks:

cargo test -p sockudo-core
cargo test -p sockudo-adapter
cargo test -p sockudo-ai-transport
cargo test -p sockudo-push

Presence correctness and performance gate:

scripts/presence-bench-guard.sh

The gate compares authoritative enter/leave against the former facade-map cycle in the same Criterion run. It fails if either the single-worker or eight-worker disjoint-client confidence interval is slower.

AI Transport checks:

scripts/ai-transport-bench-guard.sh
AIT_CONFORMANCE_OFFLINE=1 scripts/ai-conformance-node.sh
make ably-compat-test
make ably-ai-transport-test
make ably-ai-demo

Pinned cross-SDK and released-binary evidence:

cd sockudo-compatibility
make conformance strict-completeness browser-conformance browser-strict
make go-conformance ait-conformance
# After publishing a tag with detached checksum assets:
SOCKUDO_RELEASE_TAG=vX.Y.Z make release-verify

The opt-in Ably targets exercise the pinned Ably REST and WebSocket surface, excluding Live Objects and all non-WebSocket realtime transports, using local Sockudo as the endpoint. The compatibility runtime lives in crates/sockudo-ably-compat and reuses native Sockudo auth, publish, history, recovery, presence, annotation, stats, and push services. Node defaults, browser, strict-pending, and AI Transport are independent evidence lanes; a pass in one is not a pass in another. The dated release status and scope limits are in the compatibility scorecard under docs/ably-compat/ and the reports under sockudo-compatibility/. Do not use these targets to claim full Ably platform compatibility.

Sockudo and this compatibility layer are community-built and community-maintained. They are not Ably products, and Ably does not provide support for them. Use Sockudo's issue tracker, discussions, Discord, or other support channels listed below for help.

Docs checks:

cd docs
npm run types:check
npm run build

SDK checks are covered by SDK CI and are also package-local when iterating. Start from the 2026 SDK publishing runbook, then use the native package manager: bun, pnpm, npm, pytest, cargo, go test, gradle, swift test, dotnet test, composer, or bundle.

Deployment Profiles

For horizontal adapters, do not assume memory history, memory version stores, or process-local cache are safe. AI Transport startup intentionally rejects invalid horizontal/shared-state combinations.

Documentation

• Docs site source
• Getting started
• Realtime clients
• Server SDKs
• Server configuration
• Scaling
• Security
• Observability

Sponsors

Contributing

1. Fork the repository.
2. Create a focused branch.
3. Make the smallest coherent change.
4. Run the relevant checks.
5. Open a pull request with the behavior change, verification, and any follow-up risk.

For coding-agent work, read AGENTS.md. For a compact technical map of the repo, read CLAUDE.md.

License

Sockudo is licensed under the MIT License. Individual SDK packages may also carry their own package metadata and notices; check the SDK directory before publishing.

Support

• GitHub Issues
• GitHub Discussions
• Documentation
• Discord
• X / Twitter
• Email