Wren Linux

wren-linux / docs / extras.md (as plain text)

The extras

Optional programs, one script each in extras/. Nothing here is installed unless you choose it.

ToDo this
Install onewrenctl install NAME (Tab completes the name; it runs extras/NAME.sh)
Repair it, or update a downloaded app to the newest releaseRun that again
Undo itwrenctl remove NAME. An app's data is never deleted: wallets, chats and keyrings stay
Do it all by handwrenctl manual NAME prints the steps, and changes nothing
Pick from a listThe Wren menu's More apps > Get more apps and Remove apps (bash install-extras.sh, bash install-extras.sh --remove)

Each one has a page in extras/: its commands, what it is, what it doesn't protect against, and those manual steps.

Browsing the web

firefox-sandbox: firefox is Firefox as its own locked-down user (firefox), as a normal window.

tor-browser: Tor Browser as its own user, in a window of its own (Safest, JavaScript off, a bridge before its first connection if you need one: obfs4, webtunnel, Snowflake or meek). More below.

tor-browser-unsafe: a second Tor Browser, its own user, at Safer (JavaScript on https sites) for sites that need it, kept apart from the Safest one so a hacked page can't reach its files. Its address bar and tab are red, as a reminder. Needs tor-browser first.

mullvad-browser-sandbox: Mullvad Browser as its own user: Tor Browser's anti-tracking without Tor, for use with a VPN

w3m: w3m, a text-mode web browser for the terminal (no JavaScript)

Privacy and anonymity

whonix: Whonix Gateway + Workstation VMs on KVM. More below.

mullvad-vpn: Mullvad VPN (app and mullvad command), from Mullvad's signed apt repo.

onionshare: Share files, receive files, host a site or a chat over Tor, with a bridge if you need one (obfs4 or Snowflake).

onion-site: Your own onion site, able to run more than static files: nginx in front and your own app server, or a Python (Flask) app run by gunicorn.

apt-tor: apt downloads Debian's packages through Tor, over https, so your network doesn't see which packages you get and Debian's mirrors don't see your address. Signatures are checked either way; it is slower. Asked as "Network privacy" during the install, or later here.

remote-access: ssh into this computer from another one over a Tor onion service, with no firewall port opened. sshd listens on 127.0.0.1 only (keys only, your user only) and the onion service needs a client key.

metadata-cleaner: Metadata Cleaner, the graphical program Tails ships, and the mat2 command: removes hidden metadata from photos, PDFs and documents before you share them.

Passwords, keys and backups

keepassxc: KeePassXC password manager, the minimal build (keepassxc-minimal): no browser integration and no Firefox add-on, so no web page can talk to it; copy and paste a password, or use auto-type.

security-key: A FIDO2 hardware security key (YubiKey, Nitrokey...): SSH keys that need it (ed25519-sk), website logins in the sandboxed Firefox if you say so, and sudo with your password and a touch (--sudo), tried first and undone by itself unless it works.

vault: ~/Vault, an encrypted folder (gocryptfs) with its own password: vault open opens it for an hour (--for 2h, --no-timeout), and it closes itself when its time is up or the screen locks (idle, before sleep, Super+Escape, the lid).

backup: Encrypted backups of your home folder with restic, and a backup command.

signing-key: In a git copy only (see wren-dev.sh).

Messages

signal: Signal Desktop, from Signal's signed apt repo (updated by unattended-upgrades), linked to your phone's Signal; its sandbox helper isn't setuid root.

Pictures, video and files

media: imv (images) and mpv (video, music), each started in a bubblewrap sandbox that sees only the files you open.

pdf-viewer: zathura PDF viewer, in a sandbox

gimp: GIMP image editor, in a sandbox: ~/Pictures to open and save in, no network

yt-dlp: yt-dlp, the video downloader, as its own locked-down user (ytdlp): yt-dlp URL works as usual and the files land in ~/Downloads, copied out as you.

grim-slurp: screenshot and its keys (packages: grim, slurp)

file-manager: Thunar, a light graphical file manager, with Trash and thumbnails (made the default for folders).

mousepad: Mousepad, a simple graphical text editor (made the default for text files).

archive-tools: unzip, zip, 7z, bzip2 and zstd for archives

wallpapers: Fills ~/Pictures/Wallpapers with pictures that come with Wren Linux: wrens, art, Earth and space. Stronger ones only if you tick them

Coding

claude-vm: The claude-vm command runs Claude Code inside a disposable Debian VM (QEMU/KVM, built with mockvps-kvm), so a kernel bug that would escape a user-level sandbox only reaches a VM you can delete (does this computer have KVM?).

git: git; then wrenctl git sets your commit name and email and how you log in to push

vim: Debian's full vim, with colors for each programming language, and a ~/.vimrc (light or dark with the theme, modelines off)

wren-dev: For working on Wren Linux itself, on the computer where you build its package: lintian (Debian's package checker, which tools/build-deb.sh runs) and shellcheck (which test.sh runs), and a git copy in ~/wren-linux, which has what the package leaves out (tests, build tools, the signing key).

mockvps-kvm: mockvps-kvm: a disposable Debian "VPS" in a local QEMU/KVM VM for trying out server setups, with snapshots and one-command removal.

Your computer

pipewire-audio: Sound.

bluetooth: Bluetooth for headphones, keyboards and mice (bluez; bluetoothctl pairs).

webcam: A webcam switch: a USB camera (most laptops' built-in ones) starts off at every boot and when plugged in, and the Wren menu gets a Webcam line (wrenctl --camera on|off).

phone-tethering: Use a phone's mobile data over the USB cable (usbmuxd and the iPhone pairing tools; Android needs nothing but its own "USB tethering" switch).

zram: Compressed swap kept in memory, for more room, nothing on disk.

lid-awake: Closing the lid no longer suspends the laptop (Debian's default does): it locks the screen and turns the laptop's own panel off, while the network, downloads and the timer's alarms keep going; an external screen stays on.

one-workspace: One workspace: Super+1 … 0 and Super+Shift+1 … 0 do nothing and the bar shows no workspace buttons, so no window ends up out of sight (make-install-iso.sh --simplesway ticks it in the first install list)

console-only: log in to tmux (the same bar and keys) instead of starting sway

autologin: Log in on tty1 without your password, straight into sway (the disk passphrase, the screen lock and sudo still ask).

emoji-font: Color emoji (packages: fonts-noto-color-emoji)

Other systems

get-iso: get-iso downloads Debian, Tails, Kicksecure or Qubes (through Tor when Tor runs here), keeps it only if it is the newest release and its project's pinned key vouches for it, and offers to write it to a USB stick you pick and type the name of.

tails-usb: tails-usb downloads the newest Tails (through Tor when Tor runs here), uses it only if it is signed by the pinned Tails key and is the current release, writes it to a USB stick you pick and type the name of, and reads it back to check.

Retired and removed

These were taken out of Wren Linux: they can't be installed, update.sh doesn't run them again, and what is left of each is its --remove, which update.sh offers to anyone who still has one (and wrenctl remove NAME runs). Your own files are never deleted by it: the wallets stay in /var/lib/wren-wallet, a VM's disk and images stay in its user's home unless you say to delete them, and ~/projects is untouched.

Not included: a BitTorrent client. BitTorrent always shares: every client uploads to the other peers while it downloads, and announces your IP address to everyone sharing the same files. What's legally offered as a torrent (Linux images, archive.org, Blender's films) is almost always a plain download too, which only that site sees.

Does this computer have KVM?

claude-vm needs it. Both of these should succeed:

grep -cE 'vmx|svm' /proc/cpuinfo     # a number above 0: the CPU can do it
ls -l /dev/kvm                       # the file exists: the kernel can too

No /dev/kvm usually means one of: virtualization (Intel VT-x or AMD-V) is switched off in the BIOS/firmware, the CPU is too old, or Wren Linux itself is running inside a VM that doesn't pass virtualization through. The first is fixable in the BIOS; the others mean claude-vm can't run here, and Wren Linux offers no other way to sandbox Claude Code.

What the VM doesn't protect: the internet (the agent can still send anything it can read to anywhere), and what you pull from it. Read what it leaves before you run it. See THREAT-MODEL.md.

The sandboxed Firefox (extras/firefox-sandbox.sh)

firefox opens Firefox as a different Linux user, so a browser exploit lands in a user with no password, no login and none of your files. It looks like any other window. What is shared with you, and what is not:

Your files, ssh keys, passwordsnot reachable (only ~/Downloads)
Logins, history, bookmarkskept, in /var/lib/wren-firefox (that user's home)
Clipboardshared while its window has focus
~/Downloadsshared both ways; treat what lands there as untrusted
Screen and keyboardno screen reading, typing for you or session locking: it gets a restricted Wayland socket (wayland-restrict)
Microphone and your audio serverno: sound goes through one pipe into a player of yours
Your local network and this computer's servicesblocked by a firewall rule; sudo systemctl stop wren-firefox-firewall lifts it for a while
Other programs' linksopen in the running Firefox (a private message bus carries them)
KeePassXCno browser add-on (Wren Linux's KeePassXC has none); copy and paste a password

It also becomes your default browser: links from other programs (a terminal, a file manager) open in it, because the desktop entry wren-firefox.desktop is set as the handler for web links in ~/.config/mimeapps.list (undone by --remove).

firefox-unsafe runs the same Firefox as you, with everything you can reach, if the sandbox is ever in the way: Debian's firefox-esr is moved there (with dpkg-divert, so its updates land there too), and firefox-esr by name, /usr/bin/firefox and x-www-browser open the sandboxed Firefox, so nothing starts the unsandboxed one by accident. --remove puts firefox-esr back. Profiles made with firefox-profiles/new-profile.sh each get a user of their own like this one (fx-NAME), so a hacked page in one reaches neither your files nor the other profiles; they share the one firewall rule through the group wren-fx.

Your onion site (extras/onion-site.sh)

A website at a .onion address, served from this computer, for sites that need more than static files. The most common way an onion site gives away where it runs is its own software reaching out to the internet (an image, a font, an update check, an email, a DNS lookup), so here the site runs in a VM that can't reach any network at all:

Tor Browser → Tor network → Tor on this computer → 127.0.0.1:18080 → the VM: nginx → your app

The app can't fetch anything from the internet, ever: no packages from pip or npm at run time, no outside images or fonts, no email. What it needs goes in with upload, or comes from Debian during onion-site update.

What it can't hide: the site is only up while this computer is on and the VM runs (it starts at every boot; onion-site stop and start by hand), and that timing can link it to you; a dedicated machine is the right host for anything serious. A hole in your app gets the VM and the site's data, not this computer. Back up /var/lib/tor/wren-onion-site (as root) to keep the address; --remove asks before deleting it.

Remote access (extras/remote-access.sh)

For logging in to this computer from another one without opening a port: the firewall stays closed, and nothing on the local network can reach ssh.

Turn it on only if you need it: it is a service that other computers can try to reach, even if only the holder of your keys can get in.

extras/firefox-profiles/

bash extras/firefox-profiles/new-profile.sh gives a website you stay logged into (a bank, email, shopping, a work account) its own Firefox profile and a command named after it (bank, or firefox-bank when a program has that name). See extras/firefox-profiles/README.md for why that's useful.

Firefox (extras/firefox-sandbox.sh)

Installs Firefox ESR with the video codecs and uBlock Origin, runs the hardening below, runs it as its own locked-down user (firefox), and sets up incognito too. firefox-unsafe runs the same Firefox as you, for the odd page the sandbox's firewall blocks (your router's, say). wrenctl remove firefox-sandbox takes all of it out again (it asks about incognito; your profiles stay).

Firefox hardening

extras/firefox-sandbox.sh runs parts/firefox-hardening.sh, which sets these for every Firefox profile:

How: default prefs in /etc/firefox-esr/wren-hardening.js (any profile can change them at about:config), a uBlock and DNS policy in /usr/share/firefox-esr/distribution/policies.json (only written if no other policies file exists), and a systemd user timer. bash parts/firefox-hardening.sh --remove undoes all of it.

incognito

incognito opens Firefox as a different, locked-down user, for sites you don't trust or don't want tied to the rest of your browsing. incognito https://example.org/ opens a page. wifi-signin (the Wren menu's "Wi-Fi sign-in") opens it as the Wi-Fi sign-in window: the network's own DNS and plain http allowed, for a café's or hotel's sign-in page, with secure DNS off only while it is open. What parts/incognito.sh sets up:

What it doesn't do: it uses your network and your IP address (use Tor Browser or a VPN for that), and it uses the same kernel, so a kernel bug could get out of it. Pages are drawn by software, so heavy sites are slower. The keyboard layout inside it is the US one. Remove it with bash parts/incognito.sh --remove, which also deletes the user.