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:**
```bash
nix build '.#nixosConfigurations.testvm-x86_64.config.system.build.toplevel' -o testvm
```

**2. Run the VM:**
```bash
nix run '.#munix' -- testvm
```

This will start an interactive bash session inside the microVM.

**Run a specific command:**
```bash
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:

```nix
{
  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:
```bash
nix run '.#munix' -- --no-gpu --ro-expose /home/user/data testvm htop
```

## Development

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

```bash
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