WuKongIM

Real-time messaging. Your infrastructure. Your product.
Open-source messaging for chat, notifications, and AI conversations.
Built-in storage and clustering. No external database, cache, or message queue required.

Quick start · Demo home · Showcase · Documentation · 简体中文

WuKongIM handles connections, message storage, synchronization, presence, and online delivery. Build your own experience on top: personal and group chat, customer support, application notifications, or streaming AI replies. Your application owns the UI, accounts, and business rules.

Why WuKongIM?

| Capability | What it gives you | | --- | --- | | Self-contained messaging core | Built-in message, metadata, and replication storage; fewer services to deploy and operate. | | One cluster model | Start with a single-node cluster, then deploy multiple nodes using the same messaging model. 256 hash slots by default. | | Messaging building blocks | Per-channel ordering, offline synchronization, multi-device sessions, and personal, group, or custom channels. | | Tools you can use immediately | Six runnable demos, an embedded Manager, metrics, diagnostics, and backup tools. |

[!NOTE]

v3 is in beta. APIs, configuration, and durable formats may change. Review the upgrade guidance before changing versions; check installed packages with wukongim version.

Built with WuKongIM

TangSengDaoDao · 唐僧叨叨

An open-source, self-hosted messaging application. TangSengDaoDao provides chat applications for iOS, Android, Web, Windows, macOS, and Ubuntu Linux, helping enterprises run their own messaging service.

WuKongIM powers its persistent connections, message delivery, and storage. TangSengDaoDao builds the product experience on top, including chat interfaces, contacts, groups, and other business features—a concrete example of using WuKongIM as the messaging core of a complete application.

Website · Source code and architecture

Quick start

Open the Demo home page to try all six demos in your browser: chat, streaming replies, customer support, Agent, MQTT smart store, and live product launch. To run them on your own computer, follow the steps below.

1. Run the demos on your computer

Requires Go 1.25+, Node.js 22.12+ or 20.19+, and npm. From a fresh checkout:

git clone https://github.com/WuKongIM/WuKongIM.git
cd WuKongIM
node demo/start.mjs

Already have the repository? Run node demo/start.mjs from its root.

The launcher builds the server, prepares the demo backends, and opens the demo home page when ready. It starts a single-node cluster with 256 hash slots; all services listen on loopback. The default model is simulated, so no model API key is needed. The first run downloads Go and npm dependencies.

| Demo | Explore | Source and guide | | --- | --- | --- | | Chat | Direct and group conversations, message editing, and history recovery | Chat Demo | | Streaming replies | Incremental replies, model integration, cancellation, and failures | Streaming Demo | | Customer support | AI reception, human takeover, and multiple visitor conversations | Support Demo | | Agent | Tool calls, task confirmation, pause, and cancellation | Agent Demo | | MQTT smart store | Freezer alarms, remote cooling, device receipts, offline alerts, and IM collaboration | MQTT Demo | | Live product launch | Real-time barrage, likes, pinned announcements, per-room moderation, and reconnect recovery | Live Demo |

Keep the launcher running while exploring. Press Ctrl+C to stop its processes. Each run keeps its configuration, logs, data, and run.json under demo/.runs/; the next launch creates a fresh run. For terminal-only startup, use node demo/start.mjs --no-open. See the launcher guide for options.

2. Exchange your first messages

Open Chat from the demo home page in two independent browser sessions, such as a normal window and a private window. Keep the supplied API base URL and use these test credentials:

| Session | Account (UID) | Token | | --- | --- | --- | | Alice | quickstart-alice | alice-local-token | | Bob | quickstart-bob | bob-local-token |

1. On both pages, select Create or update demo credentials (test accounts only) and click Log in. Wait for both to show Connected.
2. On Alice's page, open Demo tools → Start a chat → Direct chat, enter quickstart-bob, and confirm. On Bob's page, start a direct chat with quickstart-alice.
3. Send hello from alice and confirm it appears on Bob's page. Reply with hello from bob and confirm Alice receives it.

Prefer a server deployment?

| Deployment | Start here | | --- | --- | | Linux packages | APT / RPM installation — systemd service, configuration initialization, and readiness checks | | Docker | Docker deployment — run a single-node cluster in a container | | Multiple nodes | Multi-node deployment — cluster configuration and network setup |

# Ubuntu / Debian
curl -fsSL https://packages.githubim.com/repo | sudo sh
sudo apt update
sudo apt install -y wukongim

# Rocky Linux / AlmaLinux / RHEL 9
curl -fsSL https://packages.githubim.com/repo | sudo sh
sudo dnf -y --disablerepo='*' --enablerepo=wukongim-preview makecache --refresh
sudo dnf install -y wukongim

wukongim version
sudo wukongim init
sudo wukongim config validate --config /etc/wukongim/wukongim.toml
sudo systemctl enable --now wukongim
curl --retry 30 --retry-delay 2 --retry-all-errors --max-time 5 --fail \
  http://127.0.0.1:5001/readyz

ssh -N \
  -L 127.0.0.1:5001:127.0.0.1:5001 \
  -L 127.0.0.1:5200:127.0.0.1:5200 \
  -L 127.0.0.1:5301:127.0.0.1:5301 \
  user@server-ip

Connect your application

Start with the JavaScript / Web quickstart. Its runnable example includes a development backend, two client sessions, and offline recovery. Then replace the example backend with your own authenticated application backend.

flowchart TB
    Client["Your app<br/>+ client SDK"] -->|"Login / credentials"| Backend["Your application backend"]
    Client <-->|"Authenticated messaging"| Gateway["WuKongIM Gateway"]
    Backend -->|"Trusted HTTP calls"| API["WuKongIM HTTP API"]
    Gateway --> Core["WuKongIM cluster<br/>+ built-in storage"]
    API --> Core

| WuKongIM provides | Your application owns | | --- | --- | | Connections, channel message storage, replication, and online delivery | Account login, token issuance, and WuKongIM HTTP API access control | | Channel, subscriber, and synchronization APIs | Business permissions, friend/group workflows, and SDK synchronization providers | | Client SDKs, webhooks, and plugin interfaces | Product UI, media storage, and application-specific behavior |

Keep the WuKongIM HTTP API behind a trusted backend or an authenticated API gateway: it has no built-in business caller authentication. Manager login protects Manager only. A successful send confirms the server send result; recipient delivery and processing are separate events. Offline recovery requires client synchronization.

Choose your SDK

| SDK | Best for | Platforms | | --- | --- | --- | | WuKongIMSDK | Chat state, conversations, unread counts, and offline recovery | Android, iOS, JavaScript/Web, Flutter, HarmonyOS | | WuKongEasySDK | Lightweight online connections, messaging, and events | Android, iOS, JavaScript/Web, Flutter, Rust, C#, C++, Python |

See SDK selection for maintained versions and platform guides. For the discontinued standalone UniApp SDK, follow the JavaScript / UniApp migration guide.

Operate with visibility

The embedded Manager brings cluster state, connections, channels, messages, diagnostics, and backups into one interface.

| Task | Guide | | --- | --- | | Configure credentials and network access | Security and access | | Protect data and rehearse recovery | Backup and restore | | Understand the cluster and its tools | Architecture · Operations tools | | Measure your workload | wkcli bench · Performance runbook |

For published measurements, see the conversation and messaging performance report. Its results describe the historical revision and three-process, single-host setup recorded there; measure your own version, hardware, and workload.

Build and contribute

The repository pins Go 1.25.11. Follow the configuration and startup guide for source development.

GOWORK=off go build ./cmd/wukongim ./cmd/wkcli
GOWORK=off go test ./cmd/... ./internal/... ./pkg/... ./scripts/... ./docker/... -count=1

Read the repository conventions and CI guide. For frontend work, follow the Manager and Chat Demo build guides; rebuild and commit their generated assets, which are embedded in the Go binary.

Report an issue · Browse releases · Read the changelog

For the community group, add wukongimgo on WeChat and mention WuKongIM.

Website · Documentation · 简体中文
Licensed under the Apache License 2.0.