diff --git a/modules/outputs.nix b/modules/outputs.nix
index f55567b4..2d513314 100644
--- a/modules/outputs.nix
+++ b/modules/outputs.nix
@@ -11,6 +11,7 @@ in
 {
   imports = [
     ./squashfs.nix
+    ./outputs/vmroot.nix
   ];
   options = {
     system.outputs = {
@@ -32,13 +33,6 @@ in
           Combined kernel and FDT in uImage (U-Boot compatible) format
         '';
       };
-      vmroot = mkOption {
-        type = types.package;
-        description = ''
-          Directory containing separate kernel and rootfs image for
-          use with QEMU
-        '';
-      };
       manifest = mkOption {
         type = types.package;
         description = ''
@@ -76,30 +70,6 @@ in
         inherit kernel;
         inherit dtb;
       };
-      # could use trivial-builders.linkFarmFromDrvs here?
-      vmroot =
-        let
-          cmdline = builtins.toJSON (concatStringsSep " " config.boot.commandLine);
-          makeBootableImage = pkgs.runCommandCC "objcopy" {}
-            (if pkgs.stdenv.hostPlatform.isAarch
-             then "${pkgs.stdenv.cc.targetPrefix}objcopy -O binary -R .comment -S ${kernel} $out"
-             else "cp ${kernel} $out");
-          phram_address = lib.toHexString (config.hardware.ram.startAddress + 256 * 1024 * 1024);
-        in pkgs.runCommandCC "vmroot" {} ''
-          mkdir $out
-          cd $out
-          ln -s ${config.system.outputs.rootfs} rootfs
-          ln -s ${kernel} vmlinux
-          ln -s ${manifest} manifest
-          ln -s ${kernel.headers} build
-          echo ${cmdline} > commandline
-          cat > run.sh << EOF
-          #!${pkgs.runtimeShell}
-          CMDLINE=${cmdline} PHRAM_ADDRESS=0x${phram_address} ${pkgs.pkgsBuildBuild.run-liminix-vm}/bin/run-liminix-vm --arch ${pkgs.stdenv.hostPlatform.qemuArch} \$* ${makeBootableImage} ${config.system.outputs.rootfs}
-          EOF
-          chmod +x run.sh
-       '';
-
       manifest = writeText "manifest.json" (builtins.toJSON config.filesystem.contents);
     };
   };
diff --git a/modules/outputs/vmroot.nix b/modules/outputs/vmroot.nix
new file mode 100644
index 00000000..83b379bc
--- /dev/null
+++ b/modules/outputs/vmroot.nix
@@ -0,0 +1,73 @@
+{
+  config
+, pkgs
+, lib
+, ...
+}:
+let
+  inherit (lib) mkOption types concatStringsSep;
+in
+{
+  options = {
+    system.outputs = {
+      vmroot = mkOption {
+        type = types.package;
+        description = ''
+          vmroot
+          ******
+
+          This target is for use with the qemu, qemu-aarch64, qemu-armv7l
+          devices. It generates an executable :file:`run.sh` which
+          invokes QEMU. It connects the Liminix
+          serial console and the `QEMU monitor  <https://www.qemu.org/docs/master/system/monitor.html>`_
+          to stdin/stdout. Use ^P (not ^A) to switch between monitor and
+          stdio.
+
+          If you call :command:`run.sh` with ``--background
+          /path/to/some/directory`` as the first parameter, it will
+          fork into the background and open Unix sockets in that
+          directory for console and monitor.  Use :command:`nix-shell
+          --run connect-vm` to connect to either of these sockets, and
+          ^O to disconnect.
+
+          Liminix VMs are networked using QEMU socket networking. The
+          default behaviour is to connect
+
+          * multicast 230.0.0.1:1234 ("access") to eth0
+          * multicast 230.0.0.1:1235 ("lan") to eth1
+
+          Refer to :ref:`border-network-gateway` for details of how to
+          start an emulated upstream on the "access" network that
+          your Liminix device can talk to.
+        '';
+      };
+    };
+  };
+  config = {
+    system.outputs = rec {
+      vmroot =
+        let
+          inherit (config.system.outputs) rootfs kernel manifest;
+          cmdline = builtins.toJSON (concatStringsSep " " config.boot.commandLine);
+          makeBootableImage = pkgs.runCommandCC "objcopy" {}
+            (if pkgs.stdenv.hostPlatform.isAarch
+             then "${pkgs.stdenv.cc.targetPrefix}objcopy -O binary -R .comment -S ${kernel} $out"
+             else "cp ${kernel} $out");
+          phram_address = lib.toHexString (config.hardware.ram.startAddress + 256 * 1024 * 1024);
+        in pkgs.runCommandCC "vmroot" {} ''
+          mkdir $out
+          cd $out
+          ln -s ${rootfs} rootfs
+          ln -s ${kernel} vmlinux
+          ln -s ${manifest} manifest
+          ln -s ${kernel.headers} build
+          echo ${cmdline} > commandline
+          cat > run.sh << EOF
+          #!${pkgs.runtimeShell}
+          CMDLINE=${cmdline} PHRAM_ADDRESS=0x${phram_address} ${pkgs.pkgsBuildBuild.run-liminix-vm}/bin/run-liminix-vm --arch ${pkgs.stdenv.hostPlatform.qemuArch} \$* ${makeBootableImage} ${config.system.outputs.rootfs}
+          EOF
+          chmod +x run.sh
+       '';
+    };
+  };
+}