Windows (manual)

On Windows, SnowLuma runs natively — no Docker, no WSL2 needed. Install the desktop QQ client, download and unpack the matching SnowLuma release, and run it. SnowLuma discovers QQ.exe and injects the hook automatically.

Want to run it in a container instead? See Windows · Docker Desktop (note: the image is Linux and runs Linux QQ).

Prerequisites

1. Install the desktop QQ client (NTQQ)

Download and install the Windows desktop QQ client (the NT architecture) from Tencent's official site. Make sure QQ.exe launches normally. SnowLuma injects into this running NTQQ process.

2. Download a SnowLuma release

Go to GitHub Releases, pick win-x64, and choose one of two flavors:

Replace <TAG> with the version you want (e.g. v1.10.0).

3. (Lite only) Install Node.js

SnowLuma needs Node.js ≥ 22. As of 2026, Node 24 ("Krypton") is Active LTS and 22 ("Jod") is Maintenance LTS. For the lite package, install Node 24 LTS (22 still works).

Download the Windows installer from nodejs.org, then verify in PowerShell:

node -v
# should print v24.x.x (or v22.x.x)

The full package ships its own runtime — skip this step.

Unpack and run

Unpack the tarball into a fixed directory, e.g. C:\SnowLuma\. After unpacking you'll find index.mjs, launcher.bat, webui/, native/, etc.

tar -xzf SnowLuma-<TAG>-win-x64.tar.gz -C C:\SnowLuma

From the unpacked directory, double-click launcher.bat (it just runs node ./index.mjs then pause so you can read the output). Or run it manually from a terminal:

cd C:\SnowLuma
node ./index.mjs

If the full package uses its bundled Node, follow the README's launch instructions (usually launcher.bat is enough); see WebUI / README for specifics.

Launch order of QQ and SnowLuma

SnowLuma has hook auto-load on by default: it continuously probes the system for QQ main processes, and when it finds QQ.exe it injects the hook automatically (starting in passive observation). After you finish the QR login, the hook switches from passive observation to working mode.

So either order works:

• QQ first, then SnowLuma: SnowLuma finds the already-running QQ.exe and injects on startup.
• SnowLuma first, then QQ: SnowLuma waits until QQ.exe appears, then injects.

Login

Login is QR-scan only: scan the QR in the QQ window on your desktop with the QQ mobile app. On native Windows you can see the QQ window directly — no VNC/noVNC needed (that's only for Linux headless setups).

Disable auto-injection (optional)

To keep the traditional "Load from the WebUI" flow, set hookAutoLoad to false in runtime.json, or set the env var SNOWLUMA_HOOK_AUTOLOAD=0. Env vars take precedence.

Accessing the WebUI and OneBot

Once running, SnowLuma listens on these ports by default:

Open the WebUI in a browser:

http://127.0.0.1:5099/

Finding the WebUI temporary password

On the first start with a fresh data dir, a one-time admin password is printed to the console / logs. Scroll through the console window that launcher.bat opens (look for the line containing "临时密码 / initial credentials").

Where config lands

The first run auto-creates config files under the data dir:

Env vars take precedence over runtime.json. Multi-account needs no manual config: each UIN you log in spins up its own OneBot instance. Full details in the Configuration reference.

Firewall

On first start, the Windows Firewall may prompt whether to allow node / SnowLuma network access.

• For local-only access (127.0.0.1), you don't need to allow public access.
• To let other devices on your LAN reach the WebUI / OneBot, allow the corresponding ports (5099 / 3000 / 3001) through the firewall.

Next steps

• Configuration reference — OneBot / runtime options explained.
• Quickstart — connect your first OneBot client.
• MCP / SDK — building on top of SnowLuma.
• Other platforms: Docker (Linux), WSL2, deployment overview.