Introduction

What SnowLuma is, what you can do with it, and its three usage shapes and release layout

SnowLuma is a remote-protocol framework for NTQQ (the QQ desktop client). It bridges QQ into the OneBot v11 ecosystem: a native addon injects a hook into the running QQ process via ptrace-class injection (Linux process qq, Windows QQ.exe), decodes its internal packets, and exposes them as OneBot v11 over HTTP / WebSocket / reverse-WS / HTTP-POST.

Around that core, SnowLuma also ships:

OneBot v11 adapters — HTTP API server, WebSocket server, reverse WebSocket, and HTTP event reporting, in any combination.
NTQQ bridge — talks to the real QQ client directly; no protocol account, no separate login.
Multi-account — one OneBot instance per UIN, auto-detected and auto-attached, no manual config.
Built-in WebUI — manage accounts, config, and status from the browser.
TypeScript SDK — @snowluma/sdk, for writing fully typed OneBot clients.
MCP server — @snowluma/mcp, so MCP-capable AI clients can query and invoke OneBot actions.

Three usage shapes

Your goal	Shape	Start here
Run a bot long-term on a server	Docker (recommended)	Docker deployment
Let an AI client drive QQ	MCP	MCP integration
Try it quickly on a local machine	Prebuilt tarball	Choose a deployment

To write client code, see the TypeScript SDK.

Release layout

Each platform ships two tarball flavors on GitHub Releases:

Filename	Bundles Node.js?	When to use
`SnowLuma-<TAG>-<platform>-<arch>.tar.gz` (full)	Yes, bundles a Node runtime	No Node installed; runs out of the box
`SnowLuma-<TAG>-<platform>-<arch>-lite.tar.gz` (lite)	No (much smaller)	Node.js ≥ 22 already installed (Node 24 LTS recommended)

Published platforms / arches: linux-x64, linux-arm64, win-x64.

Info

SnowLuma requires Node.js ≥ 22. As of 2026, Node 24 ("Krypton") is Active LTS and 22 ("Jod") is Maintenance LTS, so for the lite tarball install Node 24 LTS (22 still works). The full tarball bundles its own runtime — no install needed. Source: nodejs.org.

After unpacking, the dist/ tree looks roughly like:

dist/
├── index.mjs          # entry point: node ./index.mjs
├── launcher.bat       # Windows launcher (node ./index.mjs + pause)
├── webui/             # built-in WebUI static assets
└── native/            # native addon + websocket native modules
    ├── snowluma-win32-x64.{node,dll}
    ├── snowluma-linux-x64.{node,so}
    ├── snowluma-linux-arm64.{node,so}
    └── websocket-<platform>-<arch>.node

To run: unpack, then node ./index.mjs. On Windows you can also double-click launcher.bat.

Default services

Service	Default listen	Notes
OneBot HTTP	`0.0.0.0:3000`	OneBot v11 HTTP API
OneBot WS	`0.0.0.0:3001`	OneBot v11 WebSocket
WebUI	`0.0.0.0:5099`	Built-in management UI
VNC	`5900`	Docker internal only: native remote desktop. Official templates do not publish it
noVNC	`6081`	Docker only: browser remote desktop for QR login

Ports and listen addresses are configurable — see the Configuration reference.

Warning

Do not expose noVNC / WebUI / OneBot ports raw on the public internet. Docker has no shared default remote-desktop password — the first start generates a random one and prints it once in the container logs.

Project status