Host setup

In order to use nix-mariner, you need to import mariner.nixosModules.host module and configure the network options in your nixos system configuration.

You can use the microvm cli tool to create and manage VMs imperatively, instead of declaring them in your NixOS config.

See Preparing a NixOS host for declarative MicroVMs for more information

NixOS microvm.nix module

Add mariner to your host NixOS flake inputs:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    mariner.url = "github:mksafavi/nix-mariner";
    mariner.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs =
    {
      nixpkgs,
      mariner,
    }:
    {
      nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          mariner.nixosModules.host # Also imports the microvm host module
        ];
      };
    };
}

Alternatively, you could declare microvm directly in your inputs:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    microvm.url = "github:microvm-nix/microvm.nix";
    microvm.inputs.nixpkgs.follows = "nixpkgs";

    mariner.url = "github:mksafavi/nix-mariner";
    mariner.inputs.microvm.follows = "microvm";
    mariner.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs =
    {
      nixpkgs,
      mariner,
    }:
    {
      nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          mariner.nixosModules.host # also imports the microvm host module
        ];
      };
    };
}

Mariner host module additions

mariner.host enables the microvm.nix microvm.host module and adds its own host-side options. You can enable optional features with:

  mariner.host = {
    enable = true;
    # Optional features:
    graphics.enable = true; # runs waypipe client to open windows on host compositor
    network.enable = true; # creates br-microvm bridge
    network.exposeDNS = true; # allows VMs to reach host DNS
  };

• mariner.host.graphics runs a waypipe client so VMs can render windows on the host Wayland compositor.

• mariner.host.network sets up a bridge that each VM connects to. It’s a default that might not match your setup. Keep it disabled and configure networking yourself if it doesn’t fit. See microvm.nix’s a simple network setup.

• By default VMs resolve DNS themselves. mariner.host.network.exposeDNS allows the VM to use the host’s DNS server instead.

See host options for more information.

Verify

After a nixos-rebuild switch you should have the following:

ls /dev/kvm                        # exists
ip addr show br-microvm            # has 10.0.0.1/24
ss -lntp | grep ':53'              # listening on 10.0.0.1:53
lsmod | grep vhost_vsock           # module loaded