From c32be2f8c8ce80f071266947202a65cf6ceebaac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Mon, 3 Nov 2025 17:56:25 +0100
Subject: [PATCH] README: add usage information

---
 README.md | 60 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 46 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 6a770f9..8c1563e 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,55 @@
 
 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
+```
+
+## 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
 
-Building an example closure:
-
-```
-nix build '.#nixosConfigurations.x86_64-linux.testvm.config.system.build.toplevel'
-```
-
-Running the nix build:
-
-```
-nix run '.#packages.x86_64-linux.munix' $(readlink result)
-```
-
 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 $(readlink result)
+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
+- For audio: PipeWire running with `PIPEWIRE_RUNTIME_DIR` or `XDG_RUNTIME_DIR`