wechat-selkies: run the WeChat and QQ Linux clients in a browser tab

The problem wechat-selkies solves, and who actually needs it

The official WeChat Linux client assumes a desktop session: a display server, a window manager, a tray, and an input method. If you keep a headless box in a rack, or you want your chat history on a machine that stays on while your laptop sleeps, that assumption is the obstacle. wechat-selkies removes it by putting the client inside a container that already provides all four, then streaming the resulting desktop to a browser.

The README frames the target audience plainly: server deployment and remote work. The practical version of that is a person with a home server or a VPS who wants one persistent WeChat session, reachable from any browser, without installing the client on each machine they use. It is not a mobile replacement and it is not a headless API. You still get the real client, with its real login flow and its real scanning requirement.

Two details shape who benefits most. The image supports AMD64 and ARM64, so an ARM board or an ARM VPS is a legitimate host. And the repository states that GitHub Actions periodically checks the official .deb package version and updates versions/upstream.env to trigger a rebuild, which means the WeChat version inside the image tracks upstream without you watching it.

How the container is put together: Selkies, X, and a persistent /config

The Dockerfile starts from ghcr.io/linuxserver/baseimage-selkies:ubuntunoble. That base image supplies the Selkies WebRTC stack, which is what turns an X session into a browser-viewable stream. wechat-selkies does not implement the streaming itself; it layers the WeChat and QQ clients, fonts, XCB and GTK libraries, and a set of desktop conveniences on top.

Inside the container, the WeChat client runs as an ordinary Linux GUI application on the base image's virtual display. Selkies encodes that display and serves it over HTTP on port 3000 and HTTPS on port 3001. The README recommends HTTPS, and the compose file maps both. Your browser is the thin client; nothing about WeChat runs locally.

State lives in one place. The compose file mounts ./config to /config, and that directory holds the WeChat configuration and chat history. That mount is the difference between a disposable container and a session you can recreate after an image pull. It is also the source of the project's most repeated upgrade warning: if right-click menu entries or WeChat options go missing after an upgrade, the fix the README gives is to clear the openbox directory under the mounted config, for example ./config/.config/openbox.

The desktop layer is where the project adds value beyond the base image. A window switcher in the upper-left corner moves between background windows. A sidebar panel handles image copying and file transfer. PCManFM is included as a lightweight file manager, and .desktop files found in ~/Desktop/ are scanned and added to the right-click menu, which is how applications installed through proot-apps become launchable.

Installing wechat-selkies and reaching the desktop for the first time

The fastest path is the prebuilt image. The README gives a single docker run command for each registry, mapping the HTTPS port and the config volume, and passing the DRI device for hardware acceleration. The --device /dev/dri:/dev/dri flag is optional; without it the container still starts, but you lose GPU acceleration.

docker run -it -p 3001:3001 -v ./config:/config --device /dev/dri:/dev/dri ghcr.io/nickrunning/wechat-selkies:latest

After the container starts, open https://localhost:3001 or https://<server-ip>:3001 in a browser that supports WebRTC. The README notes that port 3000 serves HTTP and 3001 serves HTTPS, and recommends the HTTPS one. Expect a certificate warning on first visit, since the certificate is generated locally.

If you want QQ and PCManFM excluded, the README documents a minimal tag with a smaller image, and version-suffixed variants such as :1.2.3-minimal for pinning.

docker run -it -p 3001:3001 -v ./config:/config --device /dev/dri:/dev/dri ghcr.io/nickrunning/wechat-selkies:minimal

For a compose deployment, the repository ships a docker-compose.yml that builds from the local context and reads most settings from environment variables. The environment block is where the useful switches live: PUID and PGID for file ownership, CUSTOM_USER and PASSWORD for Web UI access, AUTO_START_WECHAT and AUTO_START_QQ for what launches on boot, and the nightly restart pair.

environment:
  - PUID=${PUID:-1000}
  - PGID=${PGID:-100}
  - CUSTOM_USER=${CUSTOM_USER:-}
  - PASSWORD=${PASSWORD:-}
  - ENABLE_WECHAT_NIGHTLY_RESTART=${ENABLE_WECHAT_NIGHTLY_RESTART:-false}
  - WECHAT_NIGHTLY_STOP_TIME=${WECHAT_NIGHTLY_STOP_TIME:-23:30}
  - WECHAT_NIGHTLY_START_TIME=${WECHAT_NIGHTLY_START_TIME:-01:30}

The repository also ships .env.example, and the README's compose example reads defaults from a .env file with ${VAR:-default} syntax. Copying it is a one-liner, and unset variables fall back to the defaults shown in the table.

cp .env.example .env

One setting deserves attention before you expose the container. CUSTOM_USER and PASSWORD are both empty by default in the compose file, and the README marks them as recommended. Leaving them empty means anyone who can reach port 3001 can reach your logged-in WeChat session. The repository's own compose file carries the same comment on the PASSWORD line. Set both.

Third-party applications such as Telegram are installed from inside the session rather than from the host: open the sidebar, choose Applications, find the entry, and click Install. The README states that the shortcut then appears in ~/Desktop/ and the right-click menu refreshes without a container restart. Uninstalling follows the same path.

Where wechat-selkies is the wrong tool

The most important limitation is not in the code. It is that this is an unofficial wrapper around a proprietary client, and the README does not describe any support arrangement, compatibility guarantee, or account-safety policy. If WeChat changes its login flow, the image can break, and the repository's automatic version detection only tells you that a new .deb exists, not that the client still behaves well inside the container.

Resource use is the second constraint. A full desktop session, a browser stream, and the WeChat client run on the host simultaneously. The compose file sets shm_size to 1gb by default and comments that it is recommended and improves performance, which is a hint about how sensitive the session is to shared memory. On a small VPS with limited RAM, this is not a light service.

Hardware acceleration is optional and conditional. The /dev/dri mapping only helps if the host has a usable DRI device and the container can access it. The README does not document a software-rendering fallback or a way to confirm acceleration is active, so on a machine without a GPU you are relying on the base image's defaults.

Finally, the upgrade path has a manual step. The README repeats the openbox warning twice: after an upgrade, missing WeChat entries in the right-click menu are fixed by clearing ./config/.config/openbox. That is a documented workaround, not an automated migration, and it sits in the same directory tree as your persisted chat data, so it needs care.

If you need WeChat on a desktop you sit in front of, install the official client. This project's value comes entirely from the case where no such desktop exists.

wechat-selkies versus Selkies webtop and the LinuxServer base image

The closest comparison is not another WeChat wrapper. It is ghcr.io/linuxserver/baseimage-selkies itself, which wechat-selkies uses as its FROM line. The base image gives you a Selkies WebRTC desktop with no applications installed. wechat-selkies adds the WeChat and QQ .deb packages, CJK fonts, the XCB and GTK library set the clients need, PCManFM, the window switcher, the sidebar panels, and the proot-apps integration that makes third-party shortcuts appear in the right-click menu.

That difference matters in both directions. Choosing the base image directly means you control exactly which packages land in the image and you are not waiting on someone else's release cadence. Choosing wechat-selkies means the library list, the font setup, and the desktop glue are already solved, which is a real amount of work if you have ever tried to get a Chromium-based Linux client to render inside a virtual display.

The second comparison is a Selkies webtop-style image with a general-purpose desktop. Those give you a full environment for arbitrary work; wechat-selkies gives you a narrower one tuned for two chat clients. If your goal is a remote Linux desktop you happen to run WeChat on, a webtop image is the more general answer. If your goal is WeChat specifically, the narrower image is smaller and its defaults are already correct for Chinese input and fonts.

The third option is running the client under a plain VNC server. That works, but VNC streams pixels without the WebRTC path Selkies uses, and the browser experience differs accordingly. The project's own topic list includes vnc alongside docker and web, which reflects the lineage rather than the current transport.

Maintenance, image tags, and what the licences actually say

The repository is not archived, and the last push was on 2026-09-22, two days before this writing. Releases have been frequent: v0.0.14 on 2026-07-22, v0.0.15 on 2026-07-23, and v0.0.16 on 2026-08-06. The version numbers are still in the 0.0.x range, which is worth reading as a signal about API and configuration stability rather than as a judgement on the code.

Upgrade cost is mostly an image pull plus the openbox cleanup. The nightly restart feature, controlled by ENABLE_WECHAT_NIGHTLY_RESTART with WECHAT_NIGHTLY_STOP_TIME defaulting to 23:30 and WECHAT_NIGHTLY_START_TIME to 01:30, exists because long-running sessions apparently need periodic recycling. If you enable it, you are accepting that the client stops and restarts on a schedule, and ENABLE_WECHAT_AUTO_LOGIN with AUTO_LOGIN_DELAY (default 3 seconds) exists to click the login button again afterward. Those two features are coupled in practice.

On licensing, the picture is mixed and worth stating precisely. The repository's LICENSE is MIT, and the README's badge points at it. The Dockerfile, however, carries LABEL org.opencontainers.image.licenses="GPL-3.0-only", inherited from the LinuxServer base image lineage. The WeChat and QQ clients themselves are proprietary software redistributed inside the image. If you plan to redistribute a modified image or embed it in a product, those three layers need separate review. This is a description of what the files say, not legal advice.

One maintenance task falls on you rather than the project: pinning a tag. The README documents both latest and version-suffixed tags, including minimal variants. Using latest means an unattended pull can change the client version under a running session.

Editorial conclusion

Adopt wechat-selkies if you want the official Linux WeChat client running on a machine you already keep on, with chat history persisted under ./config and a browser as the only client requirement. Skip it if you need a supported desktop experience, if you cannot expose a service over HTTPS, or if the image's GPL-3.0-only base image is incompatible with how you distribute your own stack. Before committing, verify that hardware acceleration actually engages on your host (the /dev/dri mapping is optional and the README does not document a fallback path), that your chosen tag is the one you want, and that you have set CUSTOM_USER and PASSWORD rather than leaving the Web UI open.

Frequently asked questions

Official sources

1. License: MIT
2. nickrunning/wechat-selkies on GitHub
3. Project website
4. README
5. Releases