Writing Nix Flakes

mvmctl uses Nix flakes to produce reproducible microVM images. You run mvmctl build from the host, and mvm runs Nix evaluation and nix build inside the Linux builder VM. The result is a kernel and rootfs that can boot on any supported runtime backend, including Firecracker, Apple Virtualization, and libkrun.

You do not need to enter a dev shell to build a flake. The dev shell is only for manually debugging the Linux build environment. See Builder VM for the full host-vs-builder model.

Minimal Flake

{
  inputs = {
    mvm.url = "github:tinylabscom/mvm?dir=nix";
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
  };

  outputs = { mvm, nixpkgs, ... }:
    let
      system = "aarch64-linux";
      pkgs = import nixpkgs { inherit system; };
    in {
      packages.${system}.default = mvm.lib.${system}.mkGuest {
        name = "my-app";
        packages = [ pkgs.curl ];

        services.my-app = {
          command = "${pkgs.python3}/bin/python3 -m http.server 8080";
        };

        healthChecks.my-app = {
          healthCmd = "${pkgs.curl}/bin/curl -sf http://localhost:8080/";
          healthIntervalSecs = 5;
        };
      };
    };
}

mkGuest API

Parameter	Description
name	VM name (used in image filename)
packages	Nix packages to include in the rootfs
hostname	Guest hostname (default: same as name)
serviceGroup	Default service user/group name (default: "mvm"). Services run as this user; secrets are readable by this group.
users.<name>.uid	User ID (optional, auto-assigned from 1000)
users.<name>.group	Group name (optional, defaults to user name)
users.<name>.home	Home directory (optional, defaults to /home/<name>)
services.<name>.command	Long-running service command (supervised with respawn)
services.<name>.preStart	Optional setup script (runs as root before the service)
services.<name>.env	Optional environment variables ({ KEY = "value"; })
services.<name>.user	User to run as (default: serviceGroup)
services.<name>.logFile	Optional log file path (default: /dev/console)
healthChecks.<name>.healthCmd	Health check command (exit 0 = healthy)
healthChecks.<name>.healthIntervalSecs	How often to run the check (default: 30)
healthChecks.<name>.healthTimeoutSecs	Timeout for each check (default: 10)
volumeMounts."<guest-path>"	Plan 45 — declarative virtio-fs volume mount declarations. See “Volume Mounts” below.

Volume Mounts

volumeMounts declares which virtio-fs volumes the guest expects at boot. Each entry maps an absolute guest path to a volume name and read-only flag:

mkGuest {
  name = "worker";
  packages = with pkgs; [ python311 ];
  volumeMounts = {
    "/mnt/work"   = { volume = "workspace"; readOnly = false; };
    "/mnt/inputs" = { volume = "fixtures"; readOnly = true; };
  };
}

The host (mvmctl up or mvmd) reads these declarations via passthru.volumeMounts:

nix eval .#mvm-worker.passthru.volumeMounts --json
# → [
#     {"guestPath":"/mnt/inputs","volumeName":"fixtures","readOnly":true},
#     {"guestPath":"/mnt/work","volumeName":"workspace","readOnly":false}
#   ]

At boot the host attaches a virtio-fs device per declaration and the guest agent runs the matching MountVolume vsock verb. Validation:

• Guest paths must be absolute and outside /nix*, /run/booted-system, /run/current-system — Nix-immutable paths are off-limits per plan 45 §“Nix semantics alignment”.
• Volume names must be non-empty strings ≤32 chars (used as the virtio-fs tag).
• The host’s mvm_security::policy::MountPathPolicy re-validates at runtime (defence-in-depth) — the eval-time checks fail fast for malformed flakes.

Reproducibility boundary: volume contents do not influence the image hash. The flake hash captures the declaration of the mounts, not the data behind them. Volumes are the explicit mutable layer; the rootfs stays immutable + verity-protected.

volumeMounts is optional; the default is {}.

What mkGuest Provides

mkGuest handles everything automatically:

• Firecracker kernel (vmlinux) — tuned for microVM workloads
• Busybox init — sub-5s boot, no systemd overhead
• Guest agent — vsock-based health checks, status reporting, snapshot coordination
• Networking — eth0 configured via kernel boot args, NAT to host network
• Drive mounting — /mnt/config (ro), /mnt/secrets (ro), /mnt/data (rw)
• Service supervision — automatic restart on failure with backoff

Adding Services

Services defined in services.<name> are supervised by the init system:

services.my-app = {
  # Setup (runs once as root before the service starts)
  preStart = "mkdir -p /tmp/data";

  # Long-running process (supervised, auto-restart on failure)
  command = "${pkgs.nodejs}/bin/node /app/server.js";

  # Environment variables
  env = {
    PORT = "8080";
    NODE_ENV = "production";
  };

  # Run as a specific user (default: serviceGroup, which defaults to "mvm")
  user = "app";

  # Log to a file instead of console
  logFile = "/var/log/my-app.log";
};

Health Checks

Health checks defined in healthChecks are automatically written to /etc/mvm/integrations.d/ at build time. The guest agent picks them up on boot:

healthChecks.my-app = {
  healthCmd = "${pkgs.curl}/bin/curl -sf http://localhost:8080/health";
  healthIntervalSecs = 10;
  healthTimeoutSecs = 5;
};

Query health status from the host:

mvmctl logs <name>       # view guest console (includes health check results)
mvmctl logs <name> -f    # follow in real time

Users

All services run as a built-in non-root user (default: mvm, uid 900) — never as root. Secrets at /mnt/secrets are owned by root:<serviceGroup> with mode 0440, so only members of the service group can read them. Custom users are automatically added to this group.

To change the default service user/group name, set serviceGroup:

mvm.lib.${system}.mkGuest {
  name = "my-app";
  serviceGroup = "app";  # default: "mvm"
  # ...
};

To run a service as a custom user, define it in users and reference it in the service. The custom user is automatically added to the service group for secrets access:

users.app = {
  uid = 1000;
  group = "app";
  home = "/home/app";
};

services.my-app = {
  command = "${pkgs.nodejs}/bin/node /app/server.js";
  user = "app";  # overrides the default serviceGroup user
};

The preStart script always runs as root regardless of the user setting, so it can perform privileged setup like mounting filesystems or creating directories.

Rootfs Types

By default, mkGuest produces an ext4 rootfs. The build system also supports squashfs for smaller, read-only images (~76% smaller with LZ4 compression). When using squashfs, the init system mounts tmpfs overlays on /etc and /var automatically.

Service Builder Helpers

The guest library provides high-level helpers that return a { package, service, healthCheck } set. Compose them with mkGuest:

mkPythonService

Build a Python HTTP service using python3.withPackages (nixpkgs packages only):

let
  pythonApp = mvm.lib.${system}.mkPythonService {
    name = "my-api";
    src = ./.;
    pythonPackages = ps: [ ps.flask ];
    entrypoint = "app/main.py";
    port = 8080;
    env = { WORKERS = "2"; };
  };
in
  mvm.lib.${system}.mkGuest {
    name = "my-api";
    packages = [ pythonApp.package ];
    services.app = pythonApp.service;
    healthChecks.app = pythonApp.healthCheck;
  };

mkStaticSite

Serve static files with busybox httpd (zero extra packages):

let
  site = mvm.lib.${system}.mkStaticSite {
    name = "docs";
    src = ./public;
    port = 8080;
  };
in
  mvm.lib.${system}.mkGuest {
    name = "docs";
    packages = [ site.package ];
    services.www = site.service;
    healthChecks.www = site.healthCheck;
  };

mkNodeService

Build a Node.js service with npm install + tsc:

let
  app = mvm.lib.${system}.mkNodeService {
    name = "my-app";
    src = fetchGit { url = "..."; rev = "..."; };
    npmHash = "sha256-...";
    entrypoint = "dist/index.js";
    port = 3000;
  };
in
  mvm.lib.${system}.mkGuest {
    name = "my-app";
    packages = [ app.package ];
    services.app = app.service;
    healthChecks.app = app.healthCheck;
  };

All three helpers return the same shape: { package, service, healthCheck }. This makes it easy to swap between runtimes or compose multiple services in a single guest.

Build Process

When you run mvmctl build --flake .:

1. The host CLI reads config and stages the selected flake/profile as a builder job.
2. The builder VM runs Nix evaluation and nix build in Linux.
3. The resulting closure is packed into the rootfs.
4. Kernel and rootfs artifacts are copied back to the host cache.
5. Runtime commands boot those already-built artifacts on the selected backend.

The same rootfs works on all backends (Firecracker, Apple Container, microvm.nix, Docker).

Profiles

The --profile flag selects which Nix output to build:

mvmctl build --flake . --profile minimal
mvmctl build --flake . --profile gateway

These map to packages.${system}.<profile> in the flake.

Running an LLM agent inside a microVM

A worked example: a microVM that boots claude-code (or any other agent binary) and reads its API key from a file you mount into the guest yourself. This is a manual file-materialization path, not the managed-secret model. For host-mediated managed secret refs, use mvm.toml or the SDKs. You write this in your project’s flake — mvm doesn’t ship a starter image to fork; you compose mkGuest yourself per Building MicroVM Images.

my-claude-code-vm/flake.nix

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
    mvm.url     = "github:tinylabscom/mvm";
    # Or from numtide/llm-agents.nix for the agent binary.
  };

  outputs = { self, nixpkgs, mvm, ... }:
    let
      system = "x86_64-linux";
      pkgs   = import nixpkgs { inherit system; };
    in
    {
      packages.${system}.default = mvm.lib.${system}.mkGuest {
        name = "claude-code";

        entrypoint.command = [ "${pkgs.claude-code}/bin/claude" "code" ];

        # If you choose to mount a credentials file manually, keep it
        # out of the rootfs and point the app at the mounted path.
        # Managed secret refs are declared through mvm.toml / SDKs,
        # not through this flake-only example.

        # Defense in depth: the workload is rootless by default in
        # prod (uid 1000); per-service seccomp tier lands in Phase 6.
        # See /guides/building-microvm-images#rootless-workloads.
      };
    };
}

mkdir -p ~/.config/mvm/secrets
printf '%s\n' 'sk-ant-…' > ~/.config/mvm/secrets/anthropic
chmod 0400 ~/.config/mvm/secrets/anthropic

cd my-claude-code-vm
mvmctl build
mvmctl up \
  --add-dir "$PWD:/workspace:rw" \
  --volume "$HOME/.config/mvm/secrets:/mnt/secrets"

Inside the guest, your workload can read the file you mounted under /mnt/secrets. If you do not want the guest to ever see the raw credential, do not use this manual file-mount pattern; use managed secret refs instead.

Why a microVM and not a process sandbox: process sandboxes share the host kernel and trust it. A microVM gives the agent its own kernel, so a kernel exploit can’t pivot to the host.

Full security composition (per-service uid, seccomp tier, secrets mode, verified boot) is documented in ADR-002 and the Rootless workloads section.