retsurf (retro + surfing) is a web browser built with Servo and SDL2. It aims to provide a full-featured web experience on small screens and unusual devices, while staying lightweight and portable. It is gamepad-first, with flexible pad and keyboard controls designed to make web browsing and gaming comfortable there.

Install on a PortMaster handheld, a Miyoo Mini, Android, Linux, Windows, or macOS.

Work in progress. Early development — expect bugs.

Demos

Powkiddy RGB30	Miyoo Mini Flip
OpenGL ES	software build, no GPU

Screenshots

Start page	Browsing	Link hints	Keyboard

Tabs	Downloads	Reader mode	Settings

Why?

Handheld Linux devices lack good browser options. Lightweight browsers struggle with modern, JS-heavy sites, while desktop browsers rely on windowing systems, mouse and keyboard input, and more capable hardware. retsurf is an attempt to build a web browser for devices like this, combining a modern web engine with gamepad-first controls and direct rendering that requires no compositor.

Features

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

• Customizable browser controls
  Every browser action can be rebound in-app or in bindings.toml, with support for taps, holds, and button chords.

• Game Mode
  Hides the browser chrome and hands keyboard and gamepad input to the page. Built-in input maps cover arrows, WASD, mouse, and raw gamepad, and all are editable, so different games can have different control schemes.

• 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 cached locally, so blocking works 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, displays release notes, and installs updates in place on PortMaster handhelds and Linux desktops. Supports stable, beta, and nightly channels.

• Audio and video
  A custom servo-media backend over SDL2 covers Web Audio and the <audio> and <video> elements: MP3, WAV, FLAC, Ogg/Vorbis, and AAC/M4A stream as they download, and <video> decodes H.264-in-MP4 in software. No MSE, so this supports direct files and embeds rather than streaming sites.

• No display server required
  SDL2 draws through whatever video backend the firmware ships, including handhelds that run none at all. X11 and Wayland are optional, not required.

• Hardware or software rendering
  A custom Servo rendering context over SDL2 draws pages on the device's OpenGL ES 3.x driver. Where there is no GPU, the software build renders on the CPU instead.

Install

Download from Releases, then:

Device	Package	Where it goes
PortMaster handhelds (ArkOS, dArkOS, EmuELEC, Knulli, muOS, ROCKNIX)	retsurf-portmaster.zip	ports folder, e.g. /roms/ports/
Miyoo Mini Flip and Plus on OnionOS	retsurf-onionos.zip	App/Retsurf/ on the SD card
Miyoo Mini Flip and Plus on Allium	retsurf-allium.zip	Apps/Retsurf.pak/ on the SD card
Android	retsurf-android-arm64.apk	sideload it
Linux	retsurf-linux-x86_64.zip, retsurf-linux-aarch64.zip	unpack and run
Windows	retsurf-windows-x86_64.zip	unpack and run
macOS	retsurf-macos-aarch64.dmg	open it and run Retsurf.app

On both Miyoo firmwares the app shows up in the Apps menu, and MENU quits it.

Building

cargo run, once Servo's build dependencies are installed. See Building from source for the prerequisites on each OS, the Cargo features, Android, and the handheld cross-builds.

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.

How to help

If you find the project useful, here is how you can help:

• Tell other people about it. Sharing the project helps it reach more users.
• Report bugs and request features in Issues. If something is broken or you have an idea, let me know.
• Star the repo. It helps the project get noticed and keeps me motivated.

Credits

• Web rendering by Servo
• SDL2 through rust-sdl2 for window, input and audio
• egui draws every overlay, with icons from Phosphor
• Blocking by Brave's adblock-rust, over EasyList and EasyPrivacy
• Reader mode by Mozilla's Readability
• Media by Symphonia and openh264 over Cisco's codec
• TLS by rustls
• SDL2 for the Miyoo Mini by Steward Fu