Website · Install · Docs · Discussions

retsurf is a web browser written in Rust and built with Servo and SDL2. It aims to provide a full-featured web experience while staying lightweight and portable. It targets handheld devices while also working on Android and desktops. It has gamepad- and keyboard-friendly controls for browsing and gaming-specific features like remappable input.

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

Work in progress. Early development — expect bugs.

Screenshots

Start page	Browsing	Link hints	Keyboard

Quick Access	Quick Menu	Reader view	Settings

Game mode	Input map	Controls	Forced dark

Features

• Gamepad-first navigation
  The browser is fully navigable with a gamepad or keyboard, with a virtual cursor, Vimium-style link hints, and an on-screen keyboard as a grid or a wheel.

• Customizable browser controls
  Every browser action can be rebound in-app, with support for tap, hold, and chord.

• Game mode
  Hides the browser chrome and routes input to the page, with an in-app editor for input maps that turn buttons and sticks into keys, mouse, or raw gamepad input.

• Web games
  WebGL 2, the Gamepad API, Web Audio, and IndexedDB, plus compatibility shims that let Emscripten exports from itch.io run.

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

• Real page zoom
  Reflows the layout rather than simply magnifying it, with 50–300% zoom steps. Zoom is per-tab.

• Reader view
  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.

• In-app updates
  Checks GitHub for updates, displays release notes, and installs updates in place on Linux. Supports stable, beta, and nightly channels.

• Audio and video
  A custom Servo media backend provides audio and video playback. Supports direct media files and embedded players, but not streaming sites that require MSE.

• No display server required
  SDL2 draws through whatever video backend the firmware ships. X11 and Wayland are optional, not required.

• Hardware or software rendering
  A custom Servo rendering backend uses OpenGL ES for GPU-accelerated rendering on supported devices, with a CPU-based software renderer for devices without a GPU.

Install

Download the latest release for your platform below. All builds are available on Releases. Nightly builds from main use the same file names under the rolling nightly tag.

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

Files are stored in the user data directory (SDL_GetPrefPath, e.g. ~/.local/share/mxmgorin/retsurf/ on Linux). Templates with the defaults are written on first run. See Configuration for all options, Controls for bindings and Game Mode input maps, and Command line for arguments and environment variables.

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. Feedback is welcome.
• Star the repo. It helps the project get noticed and keeps me motivated.
• Buy me a coffee on Ko-fi.

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 view by Mozilla's Readability
• Media by Symphonia and openh264 over Cisco's codec
• TLS by rustls
• SDL2 for the Miyoo Mini by Steward Fu