summary refs log tree commit diff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md105
1 files changed, 105 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8935b32
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# dvm — disposable VM apps as native windows
+
+Run an application in a throwaway KVM virtual machine and have its windows
+appear in your Wayland session like any other app — the QubesOS disposable
+idea, on a plain Linux desktop.
+
+```
+dvm # Mullvad Browser in a fresh disposable VM
+dvm firefox https://... # Firefox, with a URL
+dvm foot # a disposable terminal
+dvm template # terminal in the template (changes persist)
+dvm update # pacman -Syu + Mullvad Browser/extension refresh
+dvm build # create the template (first time)
+```
+
+Window titles are prefixed with `[dispNNNN]` so VM windows are always
+recognisable. Closing the app powers the VM off and deletes its disk.
+
+## How it works
+
+- **Template**: an Arch Linux cloud image, provisioned once by cloud-init with
+ Firefox (+ uBlock Origin), Mullvad Browser, foot, waypipe, PipeWire, fonts
+ and your GTK theme. Lives in `~/.local/share/dvm/template.qcow2`.
+- **Mullvad Browser**: the official tarball in `/opt/mullvad-browser`,
+ installed by `dvm-refresh-browsers` only if its signature is from the Tor
+ Browser Developers key (EF6E 286D … 9329 8290). Packaged-app mode keeps the
+ profile in `~/.mullvad-browser`. It runs on X11 (its default, to blend in
+ with other users) through waypipe's `--xwls` / xwayland-satellite.
+- **Extensions**: `EXTENSIONS=(vimium-c darkreader)` in `dvm-refresh-browsers` lists
+ addons.mozilla.org slugs. The XPIs are kept in the template and both
+ browsers install them by policy in every new profile. To add one, edit the
+ list in the template (`dvm template`, then `sudoedit
+ /usr/local/bin/dvm-refresh-browsers`, `sudo dvm-refresh-browsers`) and in
+ this repo.
+- **Disposable**: a copy-on-write qcow2 overlay of the template in
+ `$XDG_RUNTIME_DIR` (RAM). Nothing it writes touches your disk; the overlay is
+ removed when the VM exits.
+- **Display**: `waypipe` on the host listens on a random vsock port; inside the
+ guest `dvm-app.service` runs `waypipe server -- <your command>` connected to
+ the host (vsock CID 2). There is no emulated screen: each app window is a
+ real Wayland window on your compositor. The app's command, the port and the
+ current GTK theme reach the guest as systemd credentials via SMBIOS.
+- **Network**: passt user-mode networking with `map-host-loopback=none`, so
+ the VM cannot reach services listening on the host's 127.0.0.1. passt
+ connects from the host's own network stack, so VM traffic leaves through
+ whatever the host uses — Mullvad VPN included (and Mullvad's SOCKS proxy at
+ 10.64.0.1:1080 works from the VM).
+
+## Persistent settings
+
+A disposable starts from the template's disk, home directory included. To
+make settings stick (Vimium C options, the Mullvad extension's proxy, Firefox
+prefs), change them once in the template and close it:
+
+```
+dvm template mullvad-browser
+```
+
+Don't browse there — anything the template keeps, every disposable inherits.
+The build and `dvm update` start Mullvad Browser once headless in the
+template, so new extensions' welcome tabs don't open in every disposable.
+
+## Notifications
+
+Each VM posts a notification when it starts and replaces it when it stops
+(with how long it ran, and whether its disk was discarded or saved to the
+template). `DVM_NOTIFY=0` turns them off.
+- **Sound**: virtio-sound to the host's PipeWire, playback only — the VM
+ gets no microphone unless you launch with `DVM_MIC=1`. Guest volume is
+ fixed at 100% so your host mixer is the only control.
+- **Template safety**: disposables hold a shared lock on the template;
+ `dvm template`/`update` need it exclusively, so the backing image never
+ changes under a running disposable.
+
+## What is and isn't isolated
+
+The VM has its own kernel, filesystem and network stack; it cannot see your
+home directory or host processes. It does talk Wayland to your compositor
+through waypipe, which means:
+
+- **Clipboard is shared** (as with any Wayland app — only while a VM window
+ has focus). Qubes requires an explicit copy step; this does not.
+- The guest can learn harmless display facts (monitor names, scale, keyboard
+ layout) and could try to exploit the compositor or waypipe — a larger
+ surface than Qubes' minimal GUI protocol.
+- Any VM can connect to another running VM's waypipe port on the host
+ (vsock ports are host-wide), so one disposable could open windows labelled
+ as another. Not a data leak, but worth knowing.
+
+## Install
+
+Host packages: `qemu-desktop` (or base + `qemu-audio-pipewire`), `passt`,
+`waypipe`, `xorriso`, `curl`.
+
+```
+make install # ~/.local/bin/dvm + app-menu entries
+dvm build
+```
+
+Environment: `DVM_MEM` (default 4G), `DVM_CPUS` (4), `DVM_DISK` (20G),
+`DVM_DATA` (`~/.local/share/dvm`), `DVM_MIC=1`.
+
+The template build mounts the host's `/var/cache/pacman/pkg` read-only so
+already-downloaded packages aren't fetched again (signatures are still
+checked in the guest).