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

Preview the current demos — streaming replies, customer support, Agent, and mobile chat

Captured from the running repository demos on October 2, 2026. These interfaces use Chinese; the Chat Demo supports Chinese and English. Click any screenshot to view it at full size.

Streaming replies — a completed reply from the simulated model, delivered through the real messaging service.

Customer support — a visitor hands off to a human agent, who replies from the support workspace.

Agent — document retrieval completes; creating a test to-do awaits confirmation.

Mobile chat — the same conversation, with history synchronized on a phone-sized viewport.

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.

You have now verified connection, sending, and online delivery in both directions. Test credential registration calls /user/token directly; in your product, your trusted backend must verify identity and issue tokens.

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

Linux package quick start — install, initialize, and open Chat Demo

The Preview package repository supports amd64/x86_64 on Ubuntu 24.04, Debian 13, Rocky Linux 9, AlmaLinux 9, and RHEL 9. Requires systemd, sudo, and curl; Go is not required.

On the Linux server, install using your package manager:

# 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

Initialize configuration, save the Manager administrator password printed once, then start the service:

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

Wait for {"ready":true}. The generated configuration listens on loopback. To use a remote server, run this on your computer, replacing user@server-ip with your SSH login, and keep the terminal open:

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

Skip the tunnel if your browser runs on the server itself.

Application	Address	Login
Chat Demo	http://127.0.0.1:5001/demo/?lang=en	Follow the two-user exchange above; use API base URL http://127.0.0.1:5001
Manager	http://127.0.0.1:5301	admin / the password saved during initialization

Older packages may have a different Demo UI. If readiness or connections fail, inspect sudo journalctl -u wukongim -n 100 --no-pager and confirm the tunnel forwards port 5200.

Stop with sudo systemctl stop wukongim; resume with sudo systemctl start wukongim. Package data remains in /var/lib/wukongim.

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

Loading

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.