clan-munix/README.md

munix

WIP: A microVM runner for NixOS systems with desktop integration, powered by muvm/libkrun.

Quick Start

1. Build a test VM:

nix build '.#nixosConfigurations.testvm-x86_64.config.system.build.toplevel' -o testvm

2. Run the VM:

nix run '.#munix' -- testvm

This will start an interactive bash session inside the microVM.

Run a specific command:

nix run '.#munix' -- testvm fastfetch

Create a custom VM:

Create a flake.nix in a new directory using this flake as an input providing the necessary NixOS module:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    munix.url = "git+https://git.clan.lol/clan/munix?shallow=1&ref=main";
    munix.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, nixpkgs, munix, ... }: {
    # First, define system configuration in a module:
    nixosModules.musictest = { pkgs, ... }: {
      system.stateVersion = "26.05";
      programs.dconf.enable = true;
      fonts.packages = with pkgs; [ adwaita-fonts ];
      environment.systemPackages = with pkgs; [ euphonica ];
      # Local background service as a demo that doesn't require network creds :)
      services.mpd = {
        enable = true;
        startWhenNeeded = true;
        musicDirectory = "/etc/demo-music";
        user = "appvm";
        group = "appvm";
        extraConfig = ''
          audio_output {
            type "pipewire"
            name "Pipewire Output"
          }
        '';
      };
      environment.etc."demo-music/0101GhostsI.ogg".source = pkgs.fetchurl {
        # just a CC-BY-SA licensed example
        url = "https://archive.org/download/NineInchNailsGhostsI-Iv24bit48khz/0101GhostsI.ogg";
        sha256 = "0iijm1c191aqkxybl4a4gvlpnf72hk4896lwvp0xixkhds88qzxi";
      };
    };

    # And then define system closures per arch using the module above:
    nixosConfigurations.musictest-aarch64 = nixpkgs.lib.nixosSystem {
      system = "aarch64-linux";
      modules = [
        munix.nixosModules.default
        self.nixosModules.musictest
      ];
    };
    nixosConfigurations.musictest-x86_64 = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        munix.nixosModules.default
        self.nixosModules.musictest
      ];
    };

    apps.aarch64-linux.default = {
      type = "app";
      program = "${nixpkgs.legacyPackages.aarch64-linux.symlinkJoin {
        name = "munix";
        paths = [ munix.packages.aarch64-linux.munix ];
        buildInputs = [ nixpkgs.legacyPackages.aarch64-linux.makeWrapper ];
        postBuild = ''
          wrapProgram $out/bin/munix --add-flags ${self.nixosConfigurations.musictest-aarch64.config.system.build.toplevel} --set MICROVM_DEFAULT_COMMAND euphonica
        '';
      }}/bin/munix";
      meta.description = "Run Music Demo App";
    };
    apps.x86_64-linux.default = {
      type = "app";
      program = "${nixpkgs.legacyPackages.x86_64-linux.symlinkJoin {
        name = "munix";
        paths = [ munix.packages.x86_64-linux.munix ];
        buildInputs = [ nixpkgs.legacyPackages.x86_64-linux.makeWrapper ];
        postBuild = ''
          wrapProgram $out/bin/munix --add-flags ${self.nixosConfigurations.musictest-x86_64.config.system.build.toplevel} --set MICROVM_DEFAULT_COMMAND euphonica
        '';
      }}/bin/munix";
      meta.description = "Run Music Demo App";
    };
  };
} 

And nix run!

(TODO: helpers will be provided to reduce the necessary boilerplate)

munix Options

• --uid UID, -u UID - Set microVM UID (default: 1337)
• --gid GID, -g GID - Set microVM GID (default: 1337)
• --no-gpu - Disable GPU acceleration
• --no-wayland - Disable Wayland support
• --no-pipewire - Disable PipeWire audio
• --x11 - Enable X11 support
• --bind SRC DST - Bind mount SRC to DST in the VM
• --ro-bind SRC DST - Read-only bind mount
• --expose PATH - Expose PATH in the VM at the same location
• --ro-expose PATH - Expose PATH read-only

Example with options:

nix run '.#munix' -- --no-gpu --ro-expose /home/user/data testvm htop

Development

Working on muvm & munix locally (not built into the nix store):

cd muvm && cargo build --locked --release
PATH=$PWD/muvm/target/release:$PATH ./munix testvm

Requirements

• Linux system with KVM support (/dev/kvm)
• For GPU acceleration: Kernel 6.13+ with compatible drivers (amdgpu, msm)
• For Wayland: XDG_RUNTIME_DIR and WAYLAND_DISPLAY set

Known Issues