# cnk3x/xunlei: running the Synology Xunlei NAS download package on standard Linux via Docker

> cnk3x/xunlei repackages the Xunlei remote download service extracted from Synology DSM into a Docker container, downloading the official SPK from Synology's servers on first start and exposing a web dashboard on port 2345. The current published image is a beta and the project is explicitly limited to research, learning and testing.

**cnk3x/xunlei** — A Xunlei download suite extracted from Synology, for running Xunlei's remote download service on other Linux machines.

- Repository: https://github.com/cnk3x/xunlei
- Stars: 2,052 · Forks: 218
- Language: Go
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/cnk3x-xunlei

## Running the Synology Xunlei package on Linux hardware it was not designed for

Xunlei's NAS package is distributed as a Synology Package Center add-on, designed to run inside the Synology DSM operating environment and expose a browser-accessible remote download panel. cnk3x/xunlei provides a Linux compatibility layer and Docker container that runs that same package on any Linux machine, without Synology hardware. The container downloads the official SPK file from Synology's servers on first start, unpacks it, and runs the enclosed Xunlei binary under a simulated NAS environment. This approach is explicitly described as being for research, learning and testing only.

Two image registries are available: cnk3x/xunlei:beta on Docker Hub and ghcr.io/cnk3x/xunlei:beta on GitHub Container Registry. A version-pinned form is also provided: cnk3x/xunlei:4.0.0-beta and ghcr.io/cnk3x/xunlei:4.0.0-beta. The current active image is 4.0.0-beta, which has not been validated at scale. The previous stable release was v3.20.2, published on 2024-08-30.

Anyone treating this as a production download node is operating beyond the documented scope. The Xunlei NAS package is designed for Synology DSM, and cnk3x/xunlei is a compatibility wrapper that adapts it for general Linux without modifying the original binary.

## SPK downloaded on first start, busybox:1.37 base and the move from 50MB to 5MB

Version 4 changed how the SPK is handled. Earlier releases embedded the Synology package directly inside the Docker image, producing an image around 50MB in size. Starting with this architecture, the image is based on busybox:1.37 and carries only the Go launcher binary xlp; the SPK is downloaded from the network on first startup. Image size dropped to 5MB as a result of removing the embedded package.

The default SPK download URL is https://down.sandai.net/nas/nasxunlei-DSM7-x86_64.spk, which is Synology's official server. XL_SPK accepts a replacement URL if that address becomes inaccessible. The file:/// scheme is accepted for local files, with three slashes required for absolute paths: file:///path/to/nasxunlei.spk. Using two slashes would not produce an absolute path.

To avoid downloading the SPK on every container recreation, a cache volume at /xunlei/var/packages/pan-xunlei-com should be mounted. Without that volume, each container started from a clean state will re-fetch the package from the remote URL, which adds startup latency and depends on the Synology server remaining accessible.

A multi-stage Dockerfile handles the build: ubuntu:focal installs ca-certificates, tzdata, and the libdl, libgcc_s and libstdc++ libraries needed by the Xunlei binary, copies those artifacts into a staging area, then the final stage starts from busybox:1.37 and copies them in. The container timezone is set to Asia/Chongqing in the Dockerfile, which affects any timestamps shown by the Xunlei interface for download scheduling.

## Deploy with docker-compose and the required SYS_ADMIN capability

The docker-compose.yaml in the repository shows the minimum working deployment. SYS_ADMIN capability or privileged: true is required; the compose file uses cap_add: [SYS_ADMIN] as the documented choice. Port 2345 is the default dashboard port and must be published to the host.

```yaml
services:
  xunlei:
    container_name: xunlei
    image: cnk3x/xunlei:beta
    restart: unless-stopped
    hostname: r66s
    cap_add: [SYS_ADMIN]
    ports: [2345:2345/tcp]
    network_mode: bridge
    environment:
      - XL_UID=1000
      - XL_GID=1000
    volumes:
      - /vol1/1000/下载:/xunlei/downloads
      - ./data:/xunlei/data
      - ./cache:/xunlei/var/packages/pan-xunlei-com
```

With hostname: r66s set in the compose file, the Xunlei remote control interface labels the device using that hostname value. The data volume at ./data:/xunlei/data is required: it stores login credentials, download progress and plugin data, and losing this volume loses the logged-in account state. The cache volume at ./cache:/xunlei/var/packages/pan-xunlei-com is optional but prevents the SPK from being re-downloaded on every container recreate.

## Port 2345, dashboard credentials and the XL_UID and XL_GID file permission pair

XL_DASHBOARD_PORT controls which port the dashboard listens on, with 2345 as the default. XL_DASHBOARD_IP restricts which network interface the service binds to; leaving it empty binds to all interfaces. XL_DASHBOARD_USERNAME and XL_DASHBOARD_PASSWORD set basic authentication on the dashboard. Both default to empty, which means the dashboard is open to anyone who can reach the port unless those variables are explicitly set.

File ownership on downloaded files depends on XL_UID and XL_GID, both defaulting to 0, which means the Xunlei process runs as root and files are created with root ownership. Setting both to 1000, which is the typical first non-root user on a Linux system, aligns file ownership with that user. If XL_UID and XL_GID do not match the owner of the directories mounted as XL_DIR_DOWNLOAD, the download process may fail to write files without surfacing a clear error.

XL_DEBUG enables debug logging when set to a non-empty value. XL_PREVENT_UPDATE blocks automatic updates from the Xunlei service when set, which is useful for keeping a tested version stable without outside interference.

The compose file also shows two network_mode options. Using bridge mode requires the ports entry for external access. Switching to network_mode: host removes the port mapping from compose, and the port is then controlled entirely by XL_DASHBOARD_PORT.

## The /xunlei path prefix requirement and how to configure multiple download directories

Every path in XL_DIR_DOWNLOAD must begin with /xunlei. When selecting a save location inside the Xunlei panel, the display removes the /xunlei prefix, so a volume mounted at /vol1/1000/downloads:/xunlei/downloads appears in the panel as just downloads. This indirection makes the host path and the in-panel path different, which matters when creating download jobs from the interface.

Multiple download directories are configured by listing paths separated by colons, for example /xunlei/downloads:/xunlei/media. Each path must be separately mounted as a volume entry in the compose file, mapping the container-side /xunlei/... path to the actual host directory. Chinese characters are valid in path segments after the /xunlei/ prefix. The first directory in XL_DIR_DOWNLOAD is used as the cache location for Xunlei cloud storage, and that assignment is not configurable separately.

Before adding multiple directories, confirm that all host-side paths exist and that the user identified by XL_UID has write permission on each.

## XL_SPK_FORCE_DOWNLOAD and the rollback process the README does not detail

By default, the launcher skips the SPK download if a cached copy already exists. Setting XL_SPK_FORCE_DOWNLOAD to 1 overrides that behavior and downloads regardless of the cache state. Setting it to 0, or leaving it at the default, preserves the cached version.

Version 4 includes a more complete rollback process than earlier releases, but what triggers a rollback and whether it is automatic or manual is not documented. If the launched Xunlei binary fails to start correctly, this rollback path is present in the design, but there is no documented procedure for invoking or monitoring it.

For teams that need a Linux download service without these constraints, the alternative is a natively Linux-supported download manager. cnk3x/xunlei's architecture specifically repackages software designed for Synology DSM; a project that starts from a Linux-native download daemon would not depend on Synology's SPK distribution infrastructure or require the SYS_ADMIN capability.

## MIT license, Go 1.25.4, and what the 4.0.0-beta status means in practice

The repository carries an MIT license, confirmed by both the LICENSE file and the Dockerfile org.opencontainers.image.licenses label. MIT imposes no restrictions on commercial use and requires retaining the license notice in distributions.

The Go module requires Go 1.25.4, as stated in go.mod. Three direct dependencies are listed: go-chi/chi/v5 v5.2.4 for routing, spf13/pflag v1.0.10 for flag parsing, and ulikunitz/xz v0.5.15 for XZ decompression. The binary is built with CGO_ENABLED=0, producing a statically linked binary with no C library dependency at runtime. Builds target linux/amd64 and linux/arm64 according to the Makefile, with artifacts named xlp-amd64 and xlp-arm64.

The last repository push was on 2026-09-12. The repository is not archived. However, the 4.0.0-beta image is the current published version, and the previous stable tag v3.20.2 dates from 2024-08-30 with no subsequent stable release published. Anyone tracking the stable branch rather than beta should check whether v3.20.2 covers their use case before assuming the newer beta is ready for regular use.

## Conclusion

Use cnk3x/xunlei if you need the Xunlei remote download service on a Linux server or non-Synology NAS and accept the explicit beta and research-only status. Skip it if you require a production-tested release, since the current image is 4.0.0-beta and has not been validated at scale. Before deploying, verify that XL_UID and XL_GID match the owner of your download target directories, and confirm that the SPK download URL at https://down.sandai.net/nas/nasxunlei-DSM7-x86_64.spk is reachable from your network.

## FAQ

### What is cnk3x/xunlei?

cnk3x/xunlei is a Docker container that runs the Xunlei remote download service on standard Linux machines by downloading the official Synology NAS package on first start and providing a simulated runtime environment for it. The project is described as being for research, learning and testing.

### What port does the cnk3x/xunlei dashboard use?

The dashboard binds to port 2345 by default, controlled by XL_DASHBOARD_PORT. No authentication is required unless XL_DASHBOARD_USERNAME and XL_DASHBOARD_PASSWORD are set.

### Does the xunlei Docker container require root or elevated privileges?

The container requires either cap_add: [SYS_ADMIN] or privileged: true. The Xunlei process itself runs as the user specified by XL_UID and XL_GID, which default to 0 unless overridden.

### How do I prevent cnk3x/xunlei from re-downloading the SPK on every restart?

Mount a volume at /xunlei/var/packages/pan-xunlei-com to cache the downloaded SPK. Without this volume, a container created without an existing cache will re-download the SPK from the default URL at https://down.sandai.net/nas/nasxunlei-DSM7-x86_64.spk each time.

### What Linux architectures does cnk3x/xunlei support?

The Makefile builds binaries for linux/amd64 and linux/arm64. The Docker image is built for both platforms using docker buildx.

## Sources

- [cnk3x/xunlei on GitHub](https://github.com/cnk3x/xunlei)
- [Issues](https://github.com/cnk3x/xunlei/issues)
- [License: MIT](https://github.com/cnk3x/xunlei/blob/main/LICENSE)
- [README](https://github.com/cnk3x/xunlei/blob/main/README.md)
- [Releases](https://github.com/cnk3x/xunlei/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cnk3x-xunlei