box-im is a self-hosted chat stack split by transport

A WeChat lookalike with no paid third party components

box-im is an instant messaging system with an effect similar to WeChat, and the project states that it does not depend on any third party paid component. The feature list covers private chat, group chat, offline messages, voice, images and files, read and unread state, and group mentions. Audio and video calls are supported on native WebRTC with no paid third party SDK. The uniapp client is compatible with apps, H5 and the WeChat mini program, can be online at the same time as the web client, and synchronises messages between them. The stack is described plainly, with Spring Boot and Netty on the backend, Vue for the web and uniapp for mobile. The server supports clustered deployment with what the description calls good horizontal scalability, and there is a hosted site at boxim.online. The primary language of the repository is Vue, and the licence is MIT, with the README stating that the open source edition is allowed for commercial use and is free, while making clear it must not be used for anything illegal.

The modules split by responsibility, not by feature

The project structure is the clearest statement of the design, because the modules are cut along transport lines rather than business lines. im-platform is the business platform service, handling user facing business requests over HTTP. im-server is the message push service, which does not depend on business logic and pushes messages to users over WebSocket. im-client is the message push SDK, which other services can integrate to talk to im-server. im-common is the shared package that the backend services all depend on. im-web is the web front end, and im-uniapp is the uniapp front end that can be packaged as an app, as H5 or as a WeChat mini program. Separating the push service from the business service is the decision that makes clustering possible, since the business logic can scale and fail independently of the long lived connections. The separate admin console lives in its own repository, with the README recommending you get the business service running first and then follow the admin repository documentation, and the admin side provides user, group, message and sensitive word management.

Cross node delivery runs through Redis queues

The message push design section explains the problem the architecture has to solve. When the sender and the receiver are not connected to the same server, the message cannot be pushed directly, so the project designed a scheme for cross node pushing. It uses a Redis List to carry the push, with the key being im:message:private:${serverId}, where each key can be seen as a queue and each im-server consumes only the queue belonging to its own id. Redis also records which im-server holds each user's WebSocket connection, and when a user sends a message, im-platform looks at the im-server id that user is connected to and decides which queue the message should be pushed into. That is a conventional and unglamorous answer to the problem, and it has a practical consequence for an operator, since the push path depends on Redis being up and the queues being drained by a healthy im-server.

Running the whole stack locally takes four services

The local start section lists the runtime requirements, and they are specific enough to plan around. Node v18.19.0, JDK 17, Maven 3.9.6, MySQL 8.0 with the account and password both set to root and a database named im_platform created with the db/im_platfrom.sql script executed, Redis 6.2, and MinIO at the RELEASE.2024-xx release with default account, password and port. Then the backend is built and started as two jars:

mvn clean package
java -jar ./im-platform/target/im-platform.jar
java -jar ./im-server/target/im-server.jar

and the web front end is installed and served separately:

cd im-web
npm install
npm run serve

which is then reachable at http://localhost:8080. The uniapp H5 build is done in a different way, since the im-uniapp directory is imported into HBuilderX and run from the menu, and it is reachable at http://localhost:5173. That the web client runs on 8080 while the backend also has to be somewhere is a detail to confirm rather than assume, since only the two front end ports are stated.

What the open source edition leaves out, and how contributions work

Two notes in the README change how you should treat the project. The first is about the deployment on the public demo. Registration on the demo is closed to prevent the environment being used for illegal purposes, the demo runs the commercial version, and there are differences in functionality between it and the open source version, with a documentation link explaining them. The screenshots carry the same marker, since the group call screenshot is labelled as belonging to the commercial version, so the open source edition appears to cover private and group chat, the media types, read state and group mentions, while the multi party call feature sits in the paid tier. The second note is about contributions. Projects derived from this system and open sourced again should cite the original, and contributors who want a pull request are asked to submit to the v_4.0.0 branch, with the author merging into master when the feature ships. The project also asks for a star before joining the community chat, and the QQ group has been replaced by a WeCom group as of 2026-01-01.

Editorial conclusion

Adopt box-im when you want to run a chat service on your own infrastructure with a backend and clients you can modify, and when the feature set of the open source edition covers your use. Do not adopt it expecting everything in the open source edition, since the group call feature is listed as belonging to the commercial version and the demo environment runs that build. Verify first which features you need are in the open source release, that you can supply the full runtime stack of MySQL, Redis and MinIO, and that you read the branching rule, since contributions go to a separate branch and are merged by the author.

Frequently asked questions

Official sources

1. bluexsx/box-im on GitHub
2. Issues
3. License: MIT
4. Project website
5. README