RustyWolf/README.md

RustyWolf

RustyWolf is a minimal, privacy-focused browser shell built with Rust + system webviews.

(complete honesty, this whole thing is vibecoded, however I never paid for any ai service (I got a free student plan for a year) so if you wanna avoid AI slop, just skip this but I never contributed to the AI BOOM with my money, if you wanna contribute, feel free to do so)

• macOS: native WKWebView
• Linux: WebKitGTK
• Windows: WebView2

No Firefox install. No extension system. Fast startup, clean UI.

What It Does

• Really, I mean really lightweight! the reason I even made this is because I need a lightweight browser to run on my old macbook unibody 2010 4gb ddr3
  • So light in fact in my gentoo(openrc)+i3wm setup it took only 285mb ram with one tab open (dvorakmortonxd.dev) compared to firefox which took 866mb ram
  • THATS 3.04 TIMES AS MUCH RAM, so yeah it is light
  • tabs have a toggle for Keeping-in-ram (K), it basically just saves the url if its off and reloads it on reclick, if you toggle it on it keeps the whole page in ram.
• Privacy-first defaults: DuckDuckGo home + search fallback from the URL bar
• Multi-tab browsing with back, forward, reload, and keyboard shortcuts (Ctrl/Cmd+T, W, L)
• Built-in custom adblock with top-bar toggle (ADS)
• Popup permission gate: asks before a site opens a new tab
• Download support with live progress panel (D) and session download history
• Properties page with session browsing history + download history
• Default window size 1000x600 (still fully resizable)
• Optional --private mode when backend support is available

Run

cargo run --

cargo run -- --url https://example.com
cargo run -- --url example.com
cargo run -- --title "RustyWolf"
cargo run -- --private
cargo run -- --dry-run

# compatibility
cargo run -- --ua-chrome            # Chrome UA for sites that block WebKit
cargo run -- --clear-cache          # drop HTTP cache + service workers (keeps logins)

# Linux backend controls
cargo run -- --linux-backend x11
cargo run -- --linux-backend wayland
cargo run -- --linux-disable-dmabuf
cargo run -- --linux-backend x11 --linux-disable-dmabuf

Sessions are persistent: cookies and site data live in ~/.local/share/RustyWolf, so logins and consent choices survive restarts. --private gives an ephemeral session instead. The default user agent is WebKit's native one (best match for the engine); --ua-chrome is a last-resort fallback for sites that refuse to run on WebKit.

Privacy Notes

RustyWolf applies baseline hardening in page context:

• navigator.doNotTrack = "1"
• disables legacy openDatabase
• disables RTCPeerConnection

Adblocking is built-in and lightweight. It is not full uBlock Origin parity.

Linux Setup (prerequisites)

Install WebKitGTK development/runtime packages before building.

Debian

sudo apt update
sudo apt install -y libwebkit2gtk-4.1-dev libgtk-3-dev build-essential pkg-config git appmenu-gtk3-module appmenu-gtk2-module
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Arch

sudo pacman -Sy
sudo pacman -S --needed webkit2gtk-4.1 gtk3 base-devel pkgconf git appmenu-gtk-module
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Gentoo

(u can replace doas with sudo btw)

doas emerge --sync
doas emerge --ask net-libs/webkit-gtk:4.1 x11-libs/gtk+ virtual/pkgconfig dev-vcs/git x11-misc/appmenu-gtk-module
doas mkdir -p /etc/portage/package.use
echo ">=media-libs/gst-plugins-base-1.24.13-r1 gbm" | doas tee /etc/portage/package.use/rustywolf-media
doas emerge --ask 'media-libs/gst-plugins-base[gbm]' media-plugins/gst-plugins-soup media-plugins/gst-plugins-vpx media-plugins/gst-plugins-hls media-plugins/gst-plugins-dash media-plugins/gst-plugins-libav
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

For NVIDIA, make the DRM modeset setting part of the boot command line, not only /etc/modprobe.d, then reboot:

doas cp /etc/default/grub /etc/default/grub.bak
doas sed -i 's/^#GRUB_CMDLINE_LINUX=""/GRUB_CMDLINE_LINUX="nvidia-drm.modeset=1 nvidia-drm.fbdev=1"/' /etc/default/grub
doas grub-mkconfig -o /boot/grub/grub.cfg
doas reboot

After reboot, verify the active command line:

cat /proc/cmdline

Linux media playback deps (important)

If Linux logs gstreamer element autoaudiosink not found or YouTube/audio fails, install GStreamer audio/video plugins.

Debian/Ubuntu/Pop!_OS example:

sudo apt update
sudo apt install -y gstreamer1.0-tools
sudo apt install -y gstreamer1.0-plugins-base gstreamer1.0-plugins-good
sudo apt install -y gstreamer1.0-plugins-bad gstreamer1.0-libav
sudo apt install -y gstreamer1.0-pulseaudio gstreamer1.0-pipewire gstreamer1.0-alsa

Verify the sink exists:

gst-inspect-1.0 autoaudiosink

If your distro is not Debian-based, install the equivalent GStreamer base/good/bad/libav + audio sink plugin packages.

Linux Troubleshooting (Wayland/X11)

RustyWolf supports both X11 and native Wayland on Linux.

Some NVIDIA + WebKitGTK stacks can fail with dmabuf/gbm allocation errors, especially on Wayland. On NVIDIA X11, RustyWolf disables WebKitGTK's broken dmabuf renderer automatically. This avoids the blank webview/GBM allocation failure while keeping GStreamer media codecs available for sites such as YouTube.

Try these launch modes:

# auto backend (also applies the NVIDIA/X11 WebKitGTK fallback when needed)
cargo run

# native wayland
cargo run -- --linux-backend wayland

# X11/XWayland
cargo run -- --linux-backend x11

# last-resort compatibility fallback
cargo run -- --linux-disable-dmabuf

# force the upstream dmabuf renderer anyway
WEBKIT_FORCE_DMABUF_RENDERER=1 cargo run

If you still see Failed to load module "appmenu-gtk-module", that is a desktop GTK setup issue (not a RustyWolf crash).

Debian/Ubuntu/Pop!_OS fix:

sudo apt update
sudo apt install -y appmenu-gtk3-module appmenu-gtk2-module

If you do not want global appmenu integration, remove appmenu-gtk-module from GTK settings files:

~/.config/gtk-3.0/settings.ini
/etc/gtk-3.0/settings.ini
/etc/xdg/gtk-3.0/settings.ini

MacOS

installing Homebrew (skip if already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Windows Setup

Install the Microsoft Edge WebView2 Runtime (Evergreen), then build normally with Rust MSVC toolchain.

• WebView2 Runtime: https://developer.microsoft.com/microsoft-edge/webview2/
• Rust toolchain target: x86_64-pc-windows-msvc

Dev Quick Checks

cargo fmt
cargo check
cargo test