summary refs log tree commit diff
path: root/README.md
diff options
context:
space:
mode:
authorskylar <me@casper>2026-11-16 18:35:00 -0800
committerskylar <me@casper>2026-11-16 18:35:00 -0800
commit936f6fb199f4a5fd7b81edde2eba97102dace9c5 (patch)
treee9e7b44f6328b7b749422e35ab7e65036a5e4c61 /README.md
parentb9f046b9b63ac8e17672df6f7e22d73200b808fb (diff)
Prepare for public release: README, MIT licenseHEAD main
Rewrite the README for outside users (requirements, install, how it works, isolation limits, configuration, troubleshooting), add an MIT LICENSE and SPDX header, and ignore .claude/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Diffstat (limited to 'README.md')
-rw-r--r--README.md197
1 files changed, 123 insertions, 74 deletions
diff --git a/README.md b/README.md
index 8935b32..59614bf 100644
--- a/README.md
+++ b/README.md
@@ -1,105 +1,154 @@
# 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` runs an application in a throwaway KVM virtual machine. The app's
+windows show up in your Wayland session like any other app. It is the QubesOS
+"disposable VM" idea on an ordinary Linux desktop, in a single Bash script.
```
dvm # Mullvad Browser in a fresh disposable VM
-dvm firefox https://... # Firefox, with a URL
+dvm firefox https://... # Firefox, opening a URL
dvm foot # a disposable terminal
-dvm template # terminal in the template (changes persist)
-dvm update # pacman -Syu + Mullvad Browser/extension refresh
+dvm template # a terminal in the template (changes persist)
+dvm update # upgrade the template, Mullvad Browser and extensions
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.
+Each VM window's title starts with `[dispNNNN]`, so you can always tell which
+windows belong to a VM. When you close the app, the VM powers off and its disk
+is deleted.
+
+## Requirements
+
+- A Linux host with KVM and the `vhost_vsock` kernel module.
+- A Wayland compositor. Any compositor works, because VM windows are ordinary
+ Wayland clients.
+- `qemu-system-x86_64` with PipeWire audio (Arch: `qemu-desktop`, or
+ `qemu-base` + `qemu-audio-pipewire`), `passt`, `waypipe`, `xorriso`,
+ `curl`, `flock` (util-linux).
+- Optional: `notify-send` for desktop notifications.
+
+The guest is always Arch Linux (the official cloud image). The host can run
+any distribution. If the host has `/var/cache/pacman/pkg`, the template build
+reuses it.
+
+## Install
+
+```
+make install # ~/.local/bin/dvm and app-menu entries
+dvm build # download and provision the template (several minutes)
+```
+
+`make PREFIX=/usr/local install` installs it somewhere else, and
+`make uninstall` removes it.
+
+The app-menu entries are Disposable Mullvad Browser, Disposable Firefox,
+Disposable Terminal and Update Disposable VM Template.
## 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.
+- **Template**: the build downloads the Arch Linux cloud image, checks its
+ SHA-256, and provisions it once through cloud-init. It installs Firefox
+ (with uBlock Origin), Mullvad Browser, foot, waypipe, PipeWire and fonts,
+ and copies in the GTK themes from your `~/.local/share/themes`. The result
+ is `~/.local/share/dvm/template.qcow2`.
+- **Disposable**: a copy-on-write qcow2 overlay on the template, stored in
+ `$XDG_RUNTIME_DIR`, which is RAM on most systems. Nothing the VM writes
+ reaches your disk, and the overlay is deleted 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>` and
+ connects back to the host (vsock CID 2). There is no emulated screen: every
+ app window is a real Wayland window on your compositor. The command, the
+ port and your current GTK theme are passed to the guest as systemd
+ credentials through 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).
+ the VM cannot reach services listening on the host's `127.0.0.1`. passt
+ opens connections from the host's own network stack, so VM traffic leaves
+ the same way as the host's traffic, including through a host VPN.
+- **Sound**: virtio-sound to the host's PipeWire. It is playback only, so the
+ VM has no microphone unless you start it with `DVM_MIC=1`. The guest's
+ volume is fixed at 100%, which leaves the host mixer as the only volume
+ control.
+- **Template safety**: running disposables hold a shared lock on the
+ template, and `dvm template` and `dvm update` need an exclusive one. This
+ means the backing image never changes under a running disposable.
+
+### Mullvad Browser and extensions
+
+Mullvad Browser is installed from the official tarball into
+`/opt/mullvad-browser`. The guest script `dvm-refresh-browsers` checks that
+the tarball is signed by the Tor Browser Developers key
+(`EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290`) before installing it.
+The browser runs in packaged-app mode, which keeps its profile in
+`~/.mullvad-browser`. It runs on X11 (its default, so it looks like other
+users' browsers) through waypipe's `--xwls` and xwayland-satellite.
+
+Both browsers get their extensions from `EXTENSIONS=(vimium-c darkreader)` in
+`dvm-refresh-browsers`, which lists addons.mozilla.org slugs. The XPIs are
+stored in the template, and both browsers install them by policy in every new
+profile. To change the list, edit it here in `dvm` before `dvm build`. On an
+existing template, run `dvm template`, then
+`sudoedit /usr/local/bin/dvm-refresh-browsers`, then
+`sudo dvm-refresh-browsers`.
## 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:
+keep a setting (extension options, a proxy, browser preferences), change it
+once in the template and then close the template:
```
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.
+Don't browse in the template. Every disposable inherits whatever the template
+keeps. The build and `dvm update` start Mullvad Browser once, headless, in the
+template, so first-run tabs open there and not in every 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:
+The VM has its own kernel, filesystem and network stack. It cannot see your
+home directory or the host's processes. It does talk Wayland to your
+compositor through waypipe, which means:
+
+- **The clipboard is shared**, as with any Wayland app, but only while a VM
+ window has focus. Qubes requires an explicit copy step; dvm does not.
+- The guest can learn harmless facts about your display (monitor names,
+ scale, keyboard layout). It could also try to exploit the compositor or
+ waypipe, which is a larger attack surface than Qubes' minimal GUI protocol.
+- Vsock ports are shared by the whole host, so one running VM can connect to
+ another VM's waypipe port. A disposable could therefore open windows
+ labelled as another one. This doesn't leak data, but you should know it.
+- Inside the guest, the `user` account has passwordless `sudo`. The VM itself
+ is the security boundary.
+
+dvm is not Qubes. Use it to keep risky browsing and untrusted files away from
+your session and your data, not to resist a determined, targeted attacker.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `DVM_MEM` | `4G` | VM memory |
+| `DVM_CPUS` | `4` | VM CPUs |
+| `DVM_DISK` | `20G` | template disk size (set at `dvm build`) |
+| `DVM_DATA` | `~/.local/share/dvm` | template, cache and lock |
+| `DVM_MIC` | `0` | `1` gives the VM a microphone |
+| `DVM_NOTIFY` | `1` | `0` turns off notifications |
-- **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.
+## Notifications
-## Install
+Each VM posts a desktop notification when it starts and replaces it when it
+stops. The stop notice says how long the VM ran and whether its disk was
+discarded or saved to the template.
-Host packages: `qemu-desktop` (or base + `qemu-audio-pipewire`), `passt`,
-`waypipe`, `xorriso`, `curl`.
+## Troubleshooting
-```
-make install # ~/.local/bin/dvm + app-menu entries
-dvm build
-```
+- `dvm build` stops with "provisioning failed": the guest's console log is
+ saved to `~/.local/share/dvm/build.log`. Run `dvm build` again to retry;
+ the downloaded base image is kept in `~/.local/share/dvm/cache/`.
+- To rebuild from scratch, delete `~/.local/share/dvm/template.qcow2`.
+- If a VM fails to start, `dvm` prints the last lines of its console.
-Environment: `DVM_MEM` (default 4G), `DVM_CPUS` (4), `DVM_DISK` (20G),
-`DVM_DATA` (`~/.local/share/dvm`), `DVM_MIC=1`.
+## License
-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).
+MIT. See [LICENSE](LICENSE).