Quick Start

The first step isn't installing anything — it's deciding which path to take. SnowLuma's core injects a hook into a real QQ process, so you need an environment that can run QQ, inject into it, and let you scan a login QR. The table below maps your situation straight to a recommended path — pick the row that matches and follow the link.

Which path should I take?

When in doubt, choose Docker on Linux — it's the official, easiest path to a working setup. Full comparison at Choose a deployment.

Fastest path (Docker)

On Linux the recommended path is the official image. Three steps:

1. Start the container

docker run -d \
  --name snowluma \
  --restart unless-stopped \
  --shm-size=1g \
  --cap-add=SYS_PTRACE \
  --security-opt seccomp=unconfined \
  -p 6081:6081 -p 5099:5099 -p 3000:3000 -p 3001:3001 \
  -v qq-gateway-data:/app/data \
  -v qq-client-config:/app/.config \
  -v qq-client-data:/app/.local/share \
  motricseven7/snowluma:latest

2. Scan the login QR

Open http://<server-ip>:6081/ (noVNC). Password:

docker logs snowluma 2>&1 | grep -E "远程桌面密码:|remote desktop password:" | tail -n 1

QQ is already running on the remote desktop — scan with the QQ mobile app.

3. Open the WebUI

Open http://<server-ip>:5099/. Full Compose and multi-account notes: Docker deployment.

Experimental: one-click installer (Alpha)

curl -fsSL https://raw.githubusercontent.com/SnowLuma/SnowLuma.Docker.Framework/main/install.sh | bash

curl -fsSL https://raw.githubusercontent.com/SnowLuma/SnowLuma.Docker.Framework/main/install.sh | bash -s -- --mode docker --yes

Interactive mode asks which path; --yes without --mode defaults to docker. Details: One-click install (experimental).

Login and first access

Whichever path you take, first-time setup always involves these:

• QR login: SnowLuma is QR-scan login only — there's no CLI login. On headless setups you must see the QQ window via VNC / noVNC to scan.

• Find the WebUI temp password: on the first start with a fresh data dir, a one-time admin password is printed to the logs. Docker:

  docker logs snowluma 2>&1 | grep -E "临时密码|initial credentials" | tail -n 1

  Info

  The temp password is printed only on the first start with a fresh data dir. Restarting or reusing an existing data dir will not regenerate it.

• Open ports: to reach it from outside, allow the WebUI (5099) and whichever OneBot ports you use (3000 / 3001).

Password-free login (URL token)

Tired of typing the password every visit? The WebUI can sign in directly from a password carried in the URL:

http://<server-ip>:5099/?token=<your WebUI login password>

• The query key is token, and its value is your normal WebUI login password. SnowLuma runs it through the login endpoint; a correct password lands you straight on the home page.
• Consumed once: the password is stripped from the address bar immediately after load (history.replaceState) so it can't leak via browser history / access logs / the Referer header.
• The server still verifies it as usual — a wrong password just drops back to the login page, there's no bypass.

Next

• Choose a deployment — detailed comparison of every path.
• Configuration reference — ports, access tokens, adapters.
• Updating — upgrade without losing your login.