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)#

The most common path is the official image on Linux. 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 \
  -e VNC_PASSWD=change-me \
  -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) in a browser and enter the VNC_PASSWD you set. QQ is already running on the remote desktop — scan the QR with your QQ mobile app. After login, the hook auto-switches from passive observation to working mode.

3. Open the WebUI

Open http://<server-ip>:5099/ to reach the SnowLuma WebUI.

For the full Compose template, multi-account, and ops commands, see Docker deployment.

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:

• 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.