summary refs log tree commit diff
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--LICENSE29
-rw-r--r--README.md197
-rwxr-xr-xdvm4
4 files changed, 156 insertions, 75 deletions
diff --git a/.gitignore b/.gitignore
index f3d89dc..43027d6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
*.qcow2
*.log
+.claude/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..dd35d05
--- /dev/null
+++ b/LICENSE
@@ -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.
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).
diff --git a/dvm b/dvm
index b0cfe3c..ae04146 100755
--- a/dvm
+++ b/dvm
@@ -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