diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | LICENSE | 29 | ||||
| -rw-r--r-- | README.md | 197 | ||||
| -rwxr-xr-x | dvm | 4 |
4 files changed, 156 insertions, 75 deletions
@@ -1,2 +1,3 @@ *.qcow2 *.log +.claude/ @@ -0,0 +1,29 @@ +MIT License + +Copyright (c) 2026 The dvm contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +------------------------------------------------------------------------------- + +This license covers Yesod's own code. The libraries in public/vendor/ and the +models, images, sounds and data in public/assets/ keep their own licenses, +listed under "Credits" in README.md and in the CREDITS and LICENSE files next +to them. Most are CC0 or public domain; the great horned owl clips +(public/assets/sounds/owl-great-horned-*.ogg) are CC BY-SA 4.0. @@ -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). @@ -16,6 +16,8 @@ # VM powers off. Environment: DVM_MEM (4G), DVM_CPUS (4), DVM_DISK (20G), # DVM_MIC=1 to give the VM the host microphone, DVM_NOTIFY=0 to skip # desktop notifications when VMs start and stop. +# +# SPDX-License-Identifier: MIT set -euo pipefail DATA=${DVM_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/dvm} @@ -419,6 +421,6 @@ case ${1:-} in template) shift; cmd_template "$@" ;; update) shift; cmd_update ;; run) shift; cmd_run "$@" ;; - -h|--help) sed -n '2,/^set -e/{/^#/s/^# \{0,1\}//p}' "$0" ;; + -h|--help) sed -n '2,/^set -e/{/SPDX/d;/^#/s/^# \{0,1\}//p}' "$0" ;; *) cmd_run "$@" ;; esac |