Virtual DSM in Docker: Running Synology's DSM as a Containerized VM

What Virtual DSM Solves and Who It Is For

vdsm/virtual-dsm runs Synology's DiskStation Manager (DSM) inside a Docker container. It solves the problem of wanting a Synology NAS experience without buying the hardware. Engineers and homelab operators can turn an existing Linux server into a NAS appliance. The project is for people who already run Docker or Podman and want to test DSM, run a secondary backup target, or consolidate storage on one machine. It is not for users who need a turnkey NAS with vendor support. The README is clear that this is a practical engineering project, not a commercial product. The target audience is comfortable with compose files, device passthrough, and kernel modules.

The Mechanism: KVM Inside a Container

The container does not emulate DSM in software. It uses KVM acceleration to run a virtual machine with near-native performance. The README lists KVM as a requirement and shows that the container needs /dev/kvm passed through as a device. The container also needs /dev/net/tun for networking and NET_ADMIN capability to configure it. The actual DSM system runs as a guest OS, while the container provides the management layer. The storage is a virtual disk file, sized by DISK_SIZE, stored in the /storage volume. The container automatically downloads the installation files, so you do not need to source a DSM image yourself. The default version is 7.2, but you can point to a specific .pat file via the URL environment variable. This is a standard virtualization pattern, but wrapping it in Docker makes deployment reproducible.

Getting It Running: Compose, CLI, and Kubernetes

The quickest path is Docker Compose. The README gives a minimal service definition that sets DISK_SIZE to 256G, mounts /dev/kvm and /dev/net/tun, adds NET_ADMIN, maps port 5000, and binds ./dsm to /storage. The container name is dsm and restart is set to always, with a stop_grace_period of 2m. The CLI equivalent is a single docker run command with the same flags. For Kubernetes, there is a manifest at kubernetes.yml in the repository, applied with kubectl apply -f. GitHub Codespaces is also listed as an option, though the README does not explain how it works. The requirements are specific: Linux with KVM, Windows 11 with nested virtualization, at least 1 GB of RAM, and 16 GB of disk. Docker Desktop on Linux, macOS, and Windows 10 is explicitly unsupported because it does not expose KVM to containers. That is a hard constraint, not a minor caveat.

Configuration Options: Disks, CPUs, RAM, and Networking

The environment variables control the virtual hardware. RAM_SIZE and CPU_CORES set the guest resources, with defaults of 2 GB and 2 cores. DISK_SIZE sets the primary disk and can be increased later without data loss, according to the README tip. Additional disks are added with DISK2_SIZE and DISK3_SIZE, each requiring a matching volume mount like /storage2 and /storage3. Physical disks or partitions can be passed through directly by adding devices such as /dev/sdb:/disk1, but the device must be completely empty or DSM may refuse to format it. Networking defaults to bridge mode, sharing the host IP. For an individual IP, you create a macvlan network and attach the container to it, which also removes the need for port mapping. The README warns that macvlan does not allow communication between the host and the container, so if you need host access, you must create a second macvlan as a workaround. That is a real operational gotcha.

Advanced Features: DHCP, GPU, and Memory Ballooning

The DHCP mode lets DSM request an IP directly from your router, making the container and DSM appear as separate devices on your network. This requires adding /dev/vhost-net and a device_cgroup_rules entry of 'c *:* rwm', which is a broad permission that may raise security concerns. GPU acceleration is available for Intel, AMD, and NVIDIA GPUs. For Intel and AMD, you pass /dev/dri and set GPU=Y. For NVIDIA, you need the NVIDIA Container Toolkit and a deploy section with resource reservations. The README is honest about the limitation: GPU acceleration helps with facial recognition in Synology Photos but does not provide hardware video transcoding. Memory ballooning is another option, enabled by an environment variable, which lets the host reclaim unused guest RAM under pressure. The README links to QEMU's ballooning documentation, indicating the feature is inherited from the underlying hypervisor.

Limitations and Failure Modes

The most obvious limitation is the KVM requirement. Without /dev/kvm, the container will not run. That excludes a large portion of Docker users, especially those on macOS or Windows 10. The README also notes that Docker Desktop on Linux does not provide KVM access, so the project is effectively limited to native Linux hosts or Windows 11 with nested virtualization. The macvlan networking restriction is another failure mode: if you assign a separate IP, the host cannot reach the container, which can break backup or management workflows. The passthrough disk requirement that the device be completely empty is a data-loss risk if you accidentally point it at a populated disk. The README warns that DSM may not format it, but the warning is easy to miss. Finally, the project does not provide hardware transcoding, so if you plan to use it as a media server with Plex or similar, you will be limited to software transcoding.

Alternatives and How They Differ

The main alternative is running DSM on actual Synology hardware, which gives you official support, hardware transcoding, and a polished user interface. The difference is that you pay for the hardware and are locked into Synology's ecosystem. Another alternative is running a different NAS operating system directly on the host, such as TrueNAS or OpenMediaVault, which do not require KVM and can use the host's storage directly. Those systems are not containerized, so they manage the whole server, not just a virtual disk. A third option is using QEMU directly, which is what virtual-dsm wraps, but you would have to manage the VM configuration, disk images, and networking yourself. Virtual-dsm abstracts that away, but it also adds a layer of indirection. The trade-off is convenience versus control.

Maintenance, Release Cadence, and License

The project is under active development. The last push was in August 2026, with releases v7.65, v7.64, and v7.63 within a two-week period. That suggests a regular update cycle, likely tied to DSM releases or bug fixes. The license is MIT, which means you can use, modify, and distribute it freely, provided you include the copyright notice. There is no warranty, so you are responsible for your data. The maintenance cost is moderate: you need to update the container image periodically to get fixes, and you should monitor the repository for changes to the installation process. The README is the primary documentation, and it is well organized but not exhaustive. For example, the Kubernetes manifest is referenced but not explained. If you rely on this project for production storage, you should test upgrades in a non-critical environment first.

Editorial conclusion

Adopt vdsm/virtual-dsm if you run Linux with KVM support and want a self-hosted NAS without buying Synology hardware. It is also useful for testing DSM features or consolidating storage on existing servers. Do not use it if your host cannot expose /dev/kvm, such as Docker Desktop on macOS or Windows 10, or if you need production-grade hardware transcoding, which is not supported. Before deploying, verify that your kernel supports KVM and that you have at least 16 GB of free disk space. Also confirm that your router can handle macvlan traffic if you plan to assign a separate IP. The project is under active development with frequent releases, so check the latest release notes for changes.

Official sources

1. Official README
2. Project repository
3. Release notes