WuKongIM: a messaging core that stores, replicates and clusters itself
More than just IM.
At a glance
- What is it?
- WuKongIM is a Go messaging server that owns connections, storage, synchronization, presence and online delivery, and leaves the UI, accounts and business rules to your application. The v3 line is a beta that says durable formats may still change.
- Who is it for?
- WuKongIM fits teams that want connections, storage, synchronization, presence and online delivery without standing up a database, a cache and a queue, and that can absorb a beta whose durable formats may still change. It does not fit a team that needs a stable 3.x contract or that wants authentication answered for it, since the demo issues tokens straight from the client and the file hands that job to you.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- WuKongIM/WuKongIM5,001 ★ · +61
| Repository | 2026-09-13 | 2026-11-15 |
|---|---|---|
| WuKongIM/WuKongIM | 4.9k | 5k |
61 Stars in the last 63 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Storage and replication inside the server, not beside it
The pitch is one binary that owns the messaging plumbing. WuKongIM handles connections, message storage, synchronization, presence and online delivery, and built-in storage and clustering mean no external database, cache or message queue is required. It draws a hard boundary at the same time: your application owns the UI, accounts and business rules, and the experience (personal and group chat, customer support, application notifications, streaming AI replies) is built on top. The dependency list backs the self-contained claim without naming the engine. go.mod pulls github.com/cockroachdb/pebble at v1.0.0 and again under /v2 at v2.1.4, beside prometheus client_golang, robfig/cron, gopsutil, minio-go and bwmarrin/snowflake. The top level file attributes metrics, diagnostics and backup tools to the server itself. One showcase project is named: TangSengDaoDao, a self-hosted messaging application for iOS, Android, Web, Windows, macOS and Ubuntu Linux, where WuKongIM powers persistent connections, delivery and storage while the product layer owns chat interfaces, contacts and groups.
256 hash slots at one node and at three
There is one cluster model at two sizes. You start with a single-node cluster and deploy extra nodes using the same messaging model, and 256 hash slots are the default; the demo launcher uses that same 256 for its single-node run. The compose file is the multi-node form of the same idea. wk-node1, wk-node2 and wk-node3 all build wukongim-dev:local from one Dockerfile, and their container ports stay identical (5001, 5100, 5200) while only the host side moves: 15001/15002/15003, 15100/15101/15102, 15200/15201/15202. Node1 also exposes 5301 as 18080 and 7000 as 17100, where node2 and node3 expose 7000 as 17001 and 17002. A fourth service, wk-sim, sits behind profiles: ["dev-sim"] and depends on all three nodes, so it stays out of a plain compose run.
The compose file runs as root, the published image does not
Two comments in the compose file warn the reader, and both change a deployment. The first sits above user: "0:0" on every node: development-only bind mounts retain root compatibility, the published image defaults to UID/GID 10001, and production examples must not copy this override. So the file you get by default is not the shape the image expects. The second sits above the data volume: WK_NODE1_DATA_MOUNT, WK_NODE2_DATA_MOUNT and WK_NODE3_DATA_MOUNT fall back to ./docker/dev-cluster/nodeN and can be pointed at independent disks when measuring durable QPS. That tells you which measurement the project has an opinion about, and it also means leaving the default puts three nodes on one disk. Configuration arrives as ./docker/conf/node1.toml mounted at /etc/wukongim/wukongim.toml with :ro, so edits happen on the host. Each node also gets a tmpfs at /run/wukongim for runtime writes, which is gone on every restart. A wukongim.toml.example sits at the repository root next to docker/ and configs/.
One Node script builds the server and opens six demos
The shortest path to a running server is a script, not a Makefile or a compose command:
git clone https://github.com/WuKongIM/WuKongIM.git
cd WuKongIM
node demo/start.mjsRequirements are pinned: Go 1.25+, Node.js 22.12+ or 20.19+, and npm. The launcher builds the server, prepares the demo backends and opens the demo home page when ready, and every service listens on loopback, so nothing is exposed on your network while you look at it. The default model is simulated, which is why no model API key is needed, and the first run downloads Go and npm dependencies. Six demos come up behind it: chat, streaming replies, customer support, Agent, MQTT smart store and live product launch. On a box without a browser to open, the same script skips the page:
node demo/start.mjs --no-openThe rest of the options live in ./demo/README.md, not in the top level file.
The demo hands out tokens from the client side
Signing in to the Chat demo is not a security model, and the walkthrough says so in one line: test credential registration calls /user/token directly, and in your product your trusted backend must verify identity and issue tokens. The demo therefore leaves out the part you cannot leave out later. What you get for the walkthrough is two identities, quickstart-alice with alice-local-token and quickstart-bob with bob-local-token, both created by choosing Create or update demo credentials (test accounts only), clicking Log in and waiting for both sessions to read Connected. Messages go out through Demo tools, then Start a chat, then Direct chat, with hello from alice and hello from bob confirming delivery in both directions. What the walkthrough never shows is another endpoint, a token format, or a refresh and revocation rule. go.mod does carry golang-jwt/jwt/v5, but the quick start never shows how a token reaches a client, so identity stays on your side of the API.
Every launcher run starts from a clean demo/.runs/
State does not survive a relaunch. Each run keeps its configuration, logs, data and run.json under demo/.runs/, and the next launch creates a fresh run, so the next launch does not start from what you did in an earlier run. That is the right default for a demo and a poor one to inherit: the same pattern means a day of local experiments tells you nothing about how the server behaves after a week of accumulated channels. Ctrl+C is the documented way to stop, and the launcher is expected to keep running while you explore, so the demos are a foreground process rather than something you leave running in a terminal you closed. The interfaces use Chinese, and the Chat Demo is the one that also supports English. Anything you want to read in a browser beyond those demos is your own UI, which is exactly the split the file insists on when it says your application owns the interface, the accounts and the business rules.
v3 is a beta, and the image builds its own Prometheus
The version policy is a warning rather than a promise: v3 is in beta, and APIs, configuration and durable formats may change. Before you change versions the file points you at upgrade and migration guidance, and to check what is actually installed with:
wukongim versionThe release list matches that posture, with three tags in two days: v3.0.0-beta.22 on 2026-10-02, v3.0.0-beta.23 later the same day, and v3.0.0-beta.24 on 2026-10-03. The build side is far more fixed than the API side. The Dockerfile pins golang:1.26.7-bookworm and alpine:3.24.1 by digest, defaults GOPROXY to https://goproxy.cn,direct, and builds Prometheus from a pinned commit: it downloads the tarball, checks it against a sha256 recorded in docker/prometheus/toolchain.env, injects the version and commit through ldflags, and refuses any platform outside linux/amd64 and linux/arm64 with an unsupported Prometheus platform error. So the artifact is reproducible and narrow, while the storage formats underneath a beta are the part that can cost you a migration.
go.mod is the feature map, and two versions disagree
The dependency list is where the shape of the server shows. go.mod declares module github.com/WuKongIM/WuKongIM, go 1.25.0 and toolchain go1.25.11, and the Dockerfile builds with golang:1.26.7, so the compile target and the declared language level are not the same number. Inside the require block sit cobra for the command line, gizak/termui/v3 and mattn/go-isatty for a terminal surface, panjf2000/gnet/v2 and panjf2000/ants, gorilla/websocket, golang-jwt/jwt/v5, golang/protobuf, google/uuid and klauspost/compress, gin, fsnotify, google/pprof, google/jsonschema-go, modelcontextprotocol/go-sdk and paho.golang, the MQTT client library that fits the smart store demo. Alongside go.mod the root carries AGENTS.md, CONTEXT.md, CHANGELOG.md, docs/, docs-site/, packaging/, scripts/, web/, test/ and wukongim.toml.example, and the quick start explains none of them.
Editorial conclusion
WuKongIM fits teams that want connections, storage, synchronization, presence and online delivery without standing up a database, a cache and a queue, and that can absorb a beta whose durable formats may still change. It does not fit a team that needs a stable 3.x contract or that wants authentication answered for it, since the demo issues tokens straight from the client and the file hands that job to you. Verify three things before committing: whether 256 hash slots matches how you expect to grow, whether any v3 storage format already sits in your data, and whether the published image's UID/GID 10001 default survives your own deployment scripts.
Frequently asked questions
Does WuKongIM need a separate database, cache or message queue?
Not according to the top level file, which claims built-in message, metadata and replication storage so that no external database, cache or queue is required. The dependency list includes github.com/cockroachdb/pebble at v1.0.0 and v2.1.4.
How do I start WuKongIM on my own machine?
Install Go 1.25+, Node.js 22.12+ or 20.19+ and npm, clone the repository, then run `node demo/start.mjs` from its root. The launcher builds the server, prepares the demo backends, listens on loopback only and opens the demo home page, or use `--no-open` on a headless box.
What are the 256 hash slots in WuKongIM?
They are the default shard count of the cluster model: you begin with a single node and add nodes with the same messaging model, and the demo launcher starts its single-node cluster with 256 slots.
Is the WuKongIM v3 line safe to build on?
The file states that v3 is in beta and that APIs, configuration and durable formats may change, and it points at upgrade and migration guidance plus `wukongim version`. The three most recent tags are v3.0.0-beta.22, beta.23 and beta.24, published on 2026-10-02 and 2026-10-03.
How does WuKongIM handle user authentication?
The demo does not: test credential registration calls /user/token directly, and the file says your trusted backend must verify identity and issue tokens. Test accounts quickstart-alice and quickstart-bob ship with alice-local-token and bob-local-token, and go.mod includes golang-jwt/jwt/v5.
What does the WuKongIM docker-compose file set up?
Three nodes, wk-node1 through wk-node3, all built from the Dockerfile as wukongim-dev:local, each running as user "0:0", an override the compose file marks as development-only, while the published image defaults to UID/GID 10001. Config is mounted read-only from docker/conf, data from WK_NODE1_DATA_MOUNT and its siblings, and wk-sim waits behind profiles: ["dev-sim"].
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/wukongim-wukongim)Star history chart for your README
[](https://hysenlabs.com/projects/wukongim-wukongim)Was this useful?