feat: Add Rosetta support for vfkit on Apple Silicon

Enables running x86_64 (Intel) binaries in ARM64 Linux VMs on Apple
Silicon Macs using Apple's Rosetta translation layer.

Changes:
- Add microvm.vfkit.rosetta.enable option to enable Rosetta
- Add microvm.vfkit.rosetta.install option to auto-install Rosetta
- Add microvm.vfkit.rosetta.ignoreIfMissing for compatibility
- Add rosetta device to vfkit runner when enabled
- Add NixOS module to automatically configure guest (mount + binfmt)
- Validate that Rosetta is only used on aarch64-darwin systems
- Create comprehensive documentation with setup instructions

Author: luizribeiro

doc/src/SUMMARY.md

@@ -8,6 +8,7 @@
   - [Device pass-through](./devices.md)
   - [CPU emulation](./cpu-emulation.md)
   - [Output options](./output-options.md)
+  - [Using Rosetta with vfkit (macOS)](./vfkit-rosetta.md)
   - [MicroVM options reference ⚙️](./microvm-options.md)
 - [Running a MicroVM as a package](./packages.md)
 - [Preparing a host for declarative MicroVMs](./host.md)

doc/src/options.md

@@ -17,6 +17,7 @@ available for customization. These are the most important ones:
 | `microvm.forwardPorts`         | (qemu user-networking only) TCP/UDP port forwarding                                                 |
 | `microvm.vfkit.extraArgs`      | (vfkit only) Extra arguments to pass to vfkit                                                       |
 | `microvm.vfkit.logLevel`       | (vfkit only) Log level: "debug", "info", or "error" (default: "info")                              |
+| `microvm.vfkit.rosetta.enable` | (vfkit only) Enable Rosetta for running x86_64 binaries on ARM64 (Apple Silicon only)              |
 | `microvm.kernelParams`         | Like `boot.kernelParams` but will not end up in `system.build.toplevel`, saving you rebuilds        |
 | `microvm.storeOnDisk`          | Enables the store on the boot squashfs even in the presence of a share with the host's `/nix/store` |
 | `microvm.writableStoreOverlay` | Optional string of the path where all writes to `/nix/store` should go to.                          |

doc/src/vfkit-rosetta.md

@@ -0,0 +1,74 @@
+# Using Rosetta with vfkit on Apple Silicon
+
+Rosetta support enables running x86_64 (Intel) binaries in your ARM64 Linux VM on Apple Silicon Macs. This is useful for running legacy applications or development tools that haven't been ported to ARM yet.
+
+## Requirements
+
+- Apple Silicon (M1/M2/M3/etc.) Mac
+- macOS with Rosetta installed
+- vfkit hypervisor
+
+## Configuration
+
+Enable Rosetta in your MicroVM configuration:
+
+```nix
+{
+  microvm = {
+    hypervisor = "vfkit";
+
+    vfkit.rosetta = {
+      enable = true;
+      # Optional: install Rosetta automatically if missing
+      install = true;
+    };
+  };
+}
+```
+
+The NixOS module automatically handles mounting the Rosetta virtiofs share and configuring binfmt to use Rosetta for x86_64 binaries. No additional guest configuration is required.
+
+## Usage
+
+Once configured, you can run any x86_64 binary in your ARM64 VM. To verify Rosetta is working:
+
+```nix
+# Add an x86_64 package to your configuration
+environment.systemPackages = with pkgs; [
+  file  # to verify binary architecture
+  (pkgsCross.gnu64.hello)  # x86_64 version of hello
+];
+```
+
+Then in the VM:
+
+```bash
+# Verify you're running on ARM64
+uname -m
+# Output: aarch64
+
+# Check the binary architecture
+file $(which hello)
+# Output: ELF 64-bit LSB executable, x86-64, ...
+
+# Run the x86_64 binary via Rosetta
+hello
+# Output: Hello, world!
+```
+
+You can use `pkgsCross.gnu64.<package>` to cross-compile any package from nixpkgs to x86_64 and run it via Rosetta.
+
+## Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `microvm.vfkit.rosetta.enable` | bool | `false` | Enable Rosetta support |
+| `microvm.vfkit.rosetta.install` | bool | `false` | Auto-install Rosetta if missing |
+| `microvm.vfkit.rosetta.ignoreIfMissing` | bool | `false` | Continue if Rosetta unavailable |
+
+## Limitations
+
+- Only works on Apple Silicon Macs (M-series chips)
+- vfkit will fail to start on Intel Macs if Rosetta is enabled
+- Performance is slower than native ARM64 execution
+- Not all x86_64 binaries may work perfectly

lib/runners/vfkit.nix

@@ -17,7 +17,7 @@ let
     storeOnDisk kernel initrdPath storeDisk kernelParams
     balloon devices credentialFiles vsock graphics;
 
-  inherit (microvmConfig.vfkit) extraArgs logLevel;
+  inherit (microvmConfig.vfkit) extraArgs logLevel rosetta;
 
   volumesWithLetters = withDriveLetters microvmConfig;
 
@@ -61,8 +61,18 @@ let
       else if type == "bridge" then
         throw "vfkit bridge networking requires vmnet-helper which is not yet implemented. Use type = \"user\" for NAT networking."
       else
-        throw "Unknown network interface type: ${type}"
-    ) interfaces);
+        throw "vfkit does not support ${type} networking on macOS. Use type = \"user\" for NAT networking."
+    ) interfaces)
+    ++ lib.optionals rosetta.enable (
+      let
+        rosettaArgs = builtins.concatStringsSep "," (
+          [ "rosetta" "mountTag=rosetta" ]
+          ++ lib.optional rosetta.install "install"
+          ++ lib.optional rosetta.ignoreIfMissing "ignoreIfMissing"
+        );
+      in
+      [ "--device" rosettaArgs ]
+    );
 
   allArgsWithoutSocket = [
     "${lib.getExe vfkit}"
@@ -96,6 +106,8 @@ in
     then throw "vfkit does not support changing user"
     else if balloon
     then throw "vfkit does not support memory ballooning"
+    else if rosetta.enable && !vmHostPackages.stdenv.hostPlatform.isAarch64
+    then throw "Rosetta requires Apple Silicon (aarch64-darwin). Current host: ${system}"
     else if devices != []
     then throw "vfkit does not support device passthrough"
     else if credentialFiles != {}

nixos-modules/microvm/default.nix

@@ -19,6 +19,7 @@ in
     ./pci-devices.nix
     ./virtiofsd
     ./graphics.nix
+    ./rosetta.nix
     ./optimization.nix
     ./ssh-deploy.nix
   ];

nixos-modules/microvm/options.nix

@@ -608,6 +608,38 @@ in
       description = "vfkit log level.";
     };
 
+    vfkit.rosetta = {
+      enable = mkOption {
+        type = types.bool;
+        default = false;
+        description = ''
+          Enable Rosetta support for running x86_64 binaries in ARM64 Linux VMs.
+          Only works on Apple Silicon (ARM) Macs.
+
+          When enabled, the Rosetta virtiofs share will be automatically mounted
+          and binfmt will be configured to use Rosetta for x86_64 binaries.
+        '';
+      };
+
+      install = mkOption {
+        type = types.bool;
+        default = false;
+        description = ''
+          Automatically install Rosetta if missing.
+          If false and Rosetta is not installed, vfkit will fail to start.
+        '';
+      };
+
+      ignoreIfMissing = mkOption {
+        type = types.bool;
+        default = false;
+        description = ''
+          Continue execution even if Rosetta installation fails or is unavailable.
+          Useful for configurations that should work on both ARM and Intel Macs.
+        '';
+      };
+    };
+
     prettyProcnames = mkOption {
       type = types.bool;
       default = true;

nixos-modules/microvm/rosetta.nix

@@ -0,0 +1,19 @@
+{ config, lib, pkgs, ... }:
+
+let
+  cfg = config.microvm.vfkit.rosetta;
+  mountPoint = "/run/rosetta";
+  mountTag = "rosetta";
+in
+lib.mkIf (config.microvm.hypervisor == "vfkit" && cfg.enable) {
+  fileSystems.${mountPoint} = {
+    device = mountTag;
+    fsType = "virtiofs";
+  };
+
+  boot.binfmt.registrations.rosetta = {
+    interpreter = "${mountPoint}/rosetta";
+    magicOrExtension = ''\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x3e\x00'';
+    mask = ''\xff\xff\xff\xff\xff\xfe\xfe\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff'';
+  };
+}