WuKongIM

Self-hosted messaging for your app, with built-in storage and clustering.

Quick start · Live demo · Documentation · 简体中文

WuKongIM is a messaging server for personal chats, groups, and application notifications. It handles message storage, synchronization, presence, and online delivery. Your application supplies the user interface, account system, and business rules.

Why WuKongIM?

• Fewer deployment dependencies. Message, metadata, and replication storage are built in; the core needs no external database, cache, or message queue.
• One cluster model. Start with a single-node cluster and use the same messaging model in a multi-node cluster, with 256 hash slots by default.
• Messaging building blocks. Per-channel ordering, offline synchronization, multi-device sessions, and personal, group, or custom channels.
• Tools included. The embedded Chat Demo, Manager, metrics, diagnostics, and backup tools help you try and operate the service.

[!NOTE] v3 is in beta. The Linux quick start uses the Preview package repository; check the installed version with wukongim version. APIs, configuration, and durable formats may change, so review upgrade guidance before changing versions.

Quick start

To deploy with Docker, follow the Docker deployment guide.

Install a single-node WuKongIM cluster on a Linux server and exchange messages between two test users. The package repository supports amd64/x86_64: Ubuntu 24.04, Debian 13, Rocky Linux 9, AlmaLinux 9, and RHEL 9. You need systemd, sudo, curl, and SSH access from your computer. No Go installation is required.

Run steps 1–3 on the Linux server. The generated configuration binds services to loopback; use SSH forwarding to open the Demo and Manager from your computer.

1. Install the package

On Ubuntu / Debian:

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

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

Check the installed version:

wukongim version

2. Initialize configuration

sudo wukongim init
sudo wukongim config validate --config /etc/wukongim/wukongim.toml

Save the Manager administrator password printed during initialization; it is shown only once. Configuration is stored at /etc/wukongim/wukongim.toml.

3. Start and check readiness

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} before continuing.

4. Open the Demo and Manager

For 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

If your browser runs on the Linux server itself, skip the tunnel. Open:

5. Send and receive the first message

The English UI and ?lang=en are included in the current development build. Older packages and the hosted demo may still show Chinese until they are updated. The steps and screenshot below use the English UI.

1. Open Chat Demo in two separate browser sessions, such as a normal window and a private window. Keep API base URL at http://127.0.0.1:5001.

2. Enter the following credentials. Fill in both Account and Password; the password is a test connection token, and no account registration is needed.

   Session	Account (UID)	Password / test token
   Alice	quickstart-alice	alice-local-token
   Bob	quickstart-bob	bob-local-token

3. Click Log in and wait for both pages to show Connected. On Alice's page, click Start a chat, select Direct chat, enter quickstart-bob, and click OK. On Bob's page, select quickstart-alice the same way.

4. On Alice's page, enter hello from alice and click Send. Confirm it appears on Bob's page, then have Bob reply with hello from bob.

5. Confirm Alice receives the reply. You have verified connection, sending, and online delivery in both directions.

The Demo registers test tokens directly through /user/token. In your application, a trusted backend must own identity checks and token issuance; clients must not register or reset their own tokens.

sudo journalctl -u wukongim -n 100 --no-pager
sudo systemctl stop wukongim
sudo systemctl start 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 development 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 Product HTTP API"]
    Gateway --> Core["WuKongIM cluster<br/>+ built-in storage"]
    API --> Core

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

Choose an SDK

Use the SDK selector for the maintained versions and platform guides. The old standalone UniApp SDK is no longer maintained; use the JavaScript / UniApp migration guide.

Operate and evaluate

The embedded Manager shows cluster state, connections, channels, messages, diagnostics, and backups.

• Deploy: Linux packages, Docker, and multi-node clusters.
• Prepare for production: replace example credentials, configure security and network access, and exercise backup and restore.
• Understand the system: architecture and operations tools.

To evaluate performance, read the conversation and messaging performance report for workloads, revisions, latency, and limits. Its results apply to the historical three-process, single-host setup documented there. Measure your own version and workload with wkcli bench and the performance runbook.

Development and community

For source development, clone this repository and follow the configuration and startup guide. The repository uses Go 1.25.11.

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

See repository conventions and CI. For frontend changes, follow the Manager and Chat Demo build guides; their generated assets are embedded in the Go binary and must be rebuilt and committed when changed.

Website · Documentation · Issues · Releases

WeChat: wukongimgo — ask to join the WuKongIM community group.

Licensed under the Apache License 2.0.