A gamepad-native web browser for unconventional devices.

retsurf (retro + surfing) is an experimental web browser written in Rust. The goal is to bring a fully featured web experience to devices that traditional browsers weren't designed to run on. Powered by Servo for web rendering, SDL2 for windowing and input, and egui for the UI, retsurf runs without X11 or Wayland, rendering OpenGL ES directly through KMSDRM and providing gamepad-first navigation.

It runs on PortMaster-compatible handhelds, Miyoo Mini Flip / Plus running OnionOS and Allium, as well as regular desktops and Android. On GPU-less devices such as the Miyoo Mini, retsurf uses CPU rasterization for both web pages and its UI.

Work in progress. Early development — expect bugs.

Gallery

Start page	Browsing	Link hints	Keyboard

Tabs	Downloads	Reader mode	Settings

Why?

Handheld Linux devices have no good browser options. Lightweight browsers often struggle with modern, JS-heavy sites, while desktop browsers depend on a windowing system, mouse and keyboard, and hardware that these devices don't have. retsurf is an attempt to fill that gap: a modern web engine, gamepad-first controls, and direct rendering without a compositor.

Features

• Gamepad-native navigation
  Virtual cursor with stick/D-pad control, Vimium-style link hints, and an on-screen keyboard (QWERTY + ЙЦУКЕН).

• Customizable controls
  Every gesture is rebindable in-app or in bindings.toml, with D-pad scrolling for stickless devices.

• Tabs, bookmarks, history, and downloads
  Everything lives in one full-screen menu. Downloads run in the background with progress and cancellation, with a toolbar chip for active downloads.

• Real page zoom
  Reflows the layout rather than magnifying it, following Firefox's 50–300% zoom ladder; zoom is per-tab.

• Reader mode
  Strips pages down to their articles using Mozilla's Readability. Runs in place, so it also works with logged-in and dynamically rendered pages.

• Dark web pages
  Uses sites' own dark themes through prefers-color-scheme, or forces a dark appearance by inverting pages that don't provide one.

• Ad & tracker blocking
  Network-level blocking powered by Brave's adblock-rust, using EasyList and EasyPrivacy. Filters are compiled and cached locally, making warm starts instant and allowing blocking to work offline.

• Native start page
  A search/URL field over a speed-dial grid of pins (retsurf:home), fully controller-navigable like every other overlay.

• In-app updates
  Checks GitHub for updates and shows release notes inline. On PortMaster handhelds and Linux desktops, updates can be installed in place; elsewhere, the release page is opened. Supports stable, beta, and dev channels.

• Web Audio
  Custom Servo media backend with SDL2 output. Supports oscillators, gain, filters, panners, scripted buffers, and decodeAudioData for MP3, WAV, FLAC, Ogg/Vorbis, and AAC/M4A, with resampling to the context rate.

• Modern rendering
  Servo's WebRender uses OpenGL ES 3.x with a single GL context and zero CPU readback, drawing directly into the on-screen framebuffer.

Building & running

You need Servo's build dependencies. On Debian/Ubuntu:

sudo apt-get install -y build-essential clang cmake curl git gperf pkg-config python3 \
  libssl-dev libdbus-1-dev libfreetype6-dev libglib2.0-dev \
  libgl1-mesa-dev libegl1-mesa-dev libgles2-mesa-dev \
  libharfbuzz-dev liblzma-dev libudev-dev libunwind-dev libsdl2-dev

Then:

cargo run

On a Wayland desktop, retsurf auto-selects SDL's Wayland driver and a GLES context. Environment variables override the config, data, and download paths and set logging — see Configuration.

Android

With the Android SDK/NDK installed:

rustup target add aarch64-linux-android
cargo install cargo-ndk --locked
./android/scripts/build.sh release   # android/app/build/outputs/apk/release/app-release.apk
adb install -r android/app/build/outputs/apk/release/app-release.apk

Configuration

config.toml (settings) and bindings.toml (gamepad/keyboard mappings) live in the user data dir (SDL_GetPrefPath, e.g. ~/.local/share/mxmgorin/retsurf/ on Linux). Templates with the defaults are written on first run. See Configuration & bindings for every option and the full bindings reference.

References

• Handheld notes — how it works, architecture, porting status
• Android notes — build/packaging, storage, touch, lifecycle, status
• Allium package — the Miyoo Mini build: install, controls, limits
• OnionOS package — the same build in Onion's App/ layout
• The Servo Book — the embedded engine: architecture, concepts, build system