WuKongIM: a self-hosted messaging server that keeps its own storage

What WuKongIM takes off your plate, and what it leaves with you

WuKongIM is a messaging server for personal chats, groups and application notifications. It handles message storage, synchronization, presence and online delivery. The README is explicit about the boundary: your application supplies the user interface, the account system and the business rules.

That division matters more than the feature list. Most teams building chat do not struggle with rendering a message list. They struggle with the parts that only show up under load: keeping per-channel order, delivering to a user who has three devices open, and letting a client that was offline for a day catch up without replaying the whole history. WuKongIM takes those on. It does not take on identity. The quickstart says the Demo registers test tokens directly through `/user/token`, and then states that in your application a trusted backend must own identity checks and token issuance, and that clients must not register or reset their own tokens. That is a design stance, not an oversight: the server trusts whoever issues credentials.

The target reader is a backend team that already has accounts and a UI, and wants a messaging core it can run itself. The README's own framing is "Self-hosted messaging for your app, with built-in storage and clustering." If you want a hosted API where someone else runs the servers, this is the wrong shape of product.

One cluster model from one node to many, with 256 hash slots

The README states that WuKongIM keeps message, metadata and replication storage built in, and that the core needs no external database, cache or message queue. That single sentence drives most of the architecture. There is no Redis to provision for presence, no Kafka for fan-out, no MySQL for history. The repository layout reflects it: `internal/`, `pkg/` and `cmd/` sit alongside `configs/` and `packaging/`, with a `docker-compose.yml` that runs three nodes plus an optional simulator profile.

The clustering story is deliberately uniform. According to the README, you start with a single-node cluster and use the same messaging model in a multi-node cluster, with 256 hash slots by default. A single node is not a special case with a different code path; it is a cluster of one. That reduces the amount of retesting needed when you outgrow one machine, which is the practical benefit.

The development compose file is worth reading before you copy it. It builds a local image `wukongim-dev:local`, mounts each node's config read-only from `./docker/conf/node1.toml` and similar, and maps node1's internal ports outward as 15001, 15100, 15200, 18080 and 17100. It also sets `user: "0:0"` with a comment that this is development-only for root compatibility, that the published image defaults to UID/GID 10001, and that production examples must not copy the override. The compose file also notes you should point `WK_NODE{1,2,3}_DATA_MOUNT` at independent disks when measuring durable QPS. Both comments are the kind of detail that is usually missing from a project's sample config.

Installing WuKongIM on Linux and sending a first message

The README gives a Linux quick start that needs no Go installation. The package repository supports amd64/x86_64 on Ubuntu 24.04, Debian 13, Rocky Linux 9, AlmaLinux 9 and RHEL 9, and requires systemd, sudo, curl and SSH access. Run the following on the Linux server, not your laptop. On Ubuntu or Debian:

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

The same repository script is used on the RPM family, followed by a dnf install limited to the preview repo:

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

Check which build you actually got, then initialize the configuration. The README says the Manager administrator password is printed during initialization and shown only once, and that configuration lives at `/etc/wukongim/wukongim.toml`:

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

Start the service and wait for readiness. The README says to wait for `{"ready":true}` before continuing:

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

The generated configuration binds services to loopback, so from your own computer you open an SSH tunnel 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

The English Chat Demo is at `http://127.0.0.1:5001/demo/?lang=en` and the Manager at `http://127.0.0.1:5301`, where you log in as `admin` with the password saved during initialization. For the message test, open the Demo in two separate browser sessions, keep the API base URL at `http://127.0.0.1:5001`, and log in as `quickstart-alice` with `alice-local-token` in one and `quickstart-bob` with `bob-local-token` in the other. Both Account and Password fields must be filled; the password is a test connection token and no registration is needed. Once both pages show Connected, start a direct chat from each side, send `hello from alice`, and confirm it arrives on Bob's page. The README notes that the English UI and `?lang=en` are in the current development build, and that older packages and the hosted demo may still show Chinese until updated.

Beta status is the first thing to price in

The project's own status badge reads v3 beta, and the README adds a note that APIs, configuration and durable formats may change, pointing readers at the upgrade-and-migration guidance before changing versions. The release list backs this up: v3.0.0-beta.13, v3.0.0-beta.12 and v3.0.0-beta.9 all landed within a few days of each other in early September 2026. Rapid beta iteration is normal, but it means the durable formats on disk are the thing you cannot casually roll back.

The README does not document rollback. It documents an upgrade path and tells you to review it, which is not the same. If your deployment cannot tolerate a format migration, that gap is the risk to resolve before you put real message history on a beta build.

A second limitation is platform scope. The packaged quick start is amd64/x86_64 on a named list of Linux distributions with systemd. The Docker deployment guide is referenced separately, and the repository does ship a Dockerfile and `docker-compose.yml`, so containers are a supported direction. But the README does not present the package path as a general Linux story, and it does not describe Windows or macOS server installs at all.

Third, the built-in storage that removes your external dependencies also removes your escape hatch. You cannot point WuKongIM at the Postgres cluster your team already operates and back up nightly. The README's position is that storage is built in and the core needs nothing external; the trade is that your operational tooling now has to learn WuKongIM's own backup and diagnostics tools, which the README lists as included but does not detail.

How WuKongIM differs from OpenIM, Tinode and the rest

The obvious comparison set is other self-hosted chat servers: OpenIM, Tinode, WildfireChat, JuggleIM. The repository itself does not benchmark against any of them, so the honest difference to draw is architectural rather than numeric.

The clearest contrast is with servers that expect you to bring a database. A typical self-hosted IM stack asks you to run MySQL or MongoDB, Redis for presence and routing, and often a message queue, then wires the chat server to all of them. WuKongIM's stated position is the opposite: message, metadata and replication storage are built in, and the core needs no external database, cache or message queue. That is a real difference in what your first day of deployment looks like, and in what breaks at 3 a.m.

It also changes where the hard problems live. With an external-database design, scaling reads and backups are problems you already know how to solve with tools you already run. With built-in storage, those problems move inside the server, and you depend on the project's own replication, backup and diagnostics tooling. The README lists a Manager, metrics, diagnostics and backup tools as included, which suggests the project takes that responsibility seriously, but the README does not describe how they work.

The second contrast is the cluster model. A single-node cluster that uses the same messaging model as a multi-node one, with 256 hash slots by default, is a specific commitment to avoiding a rewrite at scale. Projects that treat single-node and clustered deployments as separate modes force a migration project on you later. WuKongIM's README claims you avoid that, and that claim is testable: stand up one node, then three, and check whether your client logic changes.

There is also an agent angle in the repository metadata, where `agent` and `chat` are listed among the topics, and `go.mod` pulls in `github.com/modelcontextprotocol/go-sdk`. The README does not explain what that dependency is used for, so treat it as something to investigate in the source rather than a documented feature.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-09. The most recent release, v3.0.0-beta.13, was published the same day. That is a project moving quickly, and the practical consequence is that you should expect to upgrade often or to pin a version and accept the drift.

The upgrade cost is concentrated in two places the README names: configuration and durable formats. Configuration lives at `/etc/wukongim/wukongim.toml`, and the README gives you `wukongim config validate --config /etc/wukongim/wukongim.toml` to check it before starting. That command is the cheap half of an upgrade: validate the new config, then start. The expensive half is the on-disk data. The README points at the upgrade-and-migration guidance and states plainly that durable formats may change. It does not describe a downgrade procedure.

On licensing, WuKongIM is Apache-2.0, and the repository carries a `LICENSE` file at the top level. Apache-2.0 is a permissive licence that permits commercial use and modification, and it includes a patent grant and a notice requirement. That is a summary of the licence's general character, not legal advice: if you are embedding WuKongIM in a product, have your own counsel read the actual `LICENSE` file rather than a review of it.

The repository also ships packaging under `packaging/` and a `goreleaser.packages.yaml`, which is consistent with the package-repository install path the README documents. If you plan to build your own packages, that is where to look.

Editorial conclusion

Adopt WuKongIM if you need a self-hosted messaging core with no external database, cache or message queue, and you can absorb beta churn: v3.0.0-beta.13 landed on 2026-09-09 and the README warns that APIs, configuration and durable formats may change. Do not adopt it if you need a stable long-term protocol contract or if you want a hosted service with no operational surface. Before committing, verify three things on your own hardware: that `wukongim version` reports the build you intended, that `/etc/wukongim/wukongim.toml` passes `wukongim config validate`, and that your upgrade path is covered by the project's upgrade-and-migration guidance rather than assumed.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. WuKongIM/WuKongIM on GitHub