Skip to content
mxmgorinPublic

About

Portable, gamepad-first web browser on Servo. Runs on retro handhelds, Android, Kindle, Linux, Windows and macOS

Topics

Resources

Security policy

Stars

78 stars

Watchers

2 watching

Forks

Repository files navigation

retsurf

Latest release Nightly build date Downloads CI

Website · Install · Docs · Discussions

retsurf is a portable web browser built on Servo, an independent web engine written in Rust. It runs on retro handhelds, Kindle e-readers, Android, Linux, Windows and macOS, on ARM and x86, from a Miyoo Mini with 128 MB of RAM up to desktops. It is driven by a gamepad, a keyboard or touch, with gaming features like remappable input, game scaling and shaders.

Install on handhelds through PortMaster, OnionOS, Allium, spruceOS, CrossMix-OS, NextUI, or NX Redux, on Android, Linux, Windows, or macOS, and on jailbroken Kindle e-readers.

Work in progress. Early development — expect bugs. See Limitations.

Screenshots

Quick Access over the WebGL racer HexGL at the start through the zfast CRT shader, the browser chrome hidden: reload, the on-screen keyboard and bookmark, then scaling, shader, cursor, JS engine, the input map in use, launch mode and exit Vimium-style hints over a Wikipedia article, each link labeled with the gamepad buttons that open it
The built-in start page: the retsurf banner over filter tabs, a grid of bookmarks marked as sites, apps or games, and the search field and button hints at the bottom Quick Access at the right edge over Hacker News, headed by its bookmark: reload, enter game mode and bookmark, then user agent, the ad blocker switch, the reader view switch, page theme and launch mode, with button hints below

More screenshots and device photos are on the website.

Goals

  • A browser for any device. A full web engine on hardware that ships without a modern browser, like retro handhelds.
  • A runner for web games and apps. Runs a site or a local game folder full screen with its own controls and no browser UI, so a web game can ship as a port of its own.
  • Help Servo grow. Running Servo on real devices finds engine bugs, and the fixes go upstream.

Features

  • Runs on almost anything
    From a 128 MB handheld to desktops, and on e-ink Kindles. No X11 or Wayland required: SDL2 draws through whatever video backend the firmware ships. Renders on the GPU through OpenGL ES, or on the CPU on devices without one.

  • 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. --kiosk runs a game with no browser UI at all (Command line).

  • Game scaling and shaders
    Cuts the game out of its page and fits it to the screen, in whole pixels or stretched, then draws it through CRT, LCD, or upscaling shaders. Takes RetroArch's single-pass GLSL shaders, ten built in. See Shaders.

  • 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
    Each is a list on one full-screen view. Downloads run in the background with progress and cancellation and a progress ring in the toolbar.

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

  • No telemetry
    The only requests retsurf makes on its own are the update check and the ad-block list refresh, and both can be turned off in Settings.

Limitations

Area Limitation
Site compatibility Servo does not support every web feature yet: some sites render incorrectly or break.
Streaming video No Media Source Extensions: YouTube, Twitch and similar players do not play.
Media formats Video: H.264 in MP4 only, no WebM, VP9, AV1 or HEVC. Audio: MP3, AAC, FLAC, Vorbis and WAV, no Opus.
DRM No Encrypted Media Extensions: Netflix, Spotify and other DRM services do not play.
Video calls No WebRTC.
Extensions Browser extensions are not supported.
Low-end devices Heavy sites load slowly and can run out of memory on 128 MB devices.
Security All sites run in one process, with no site isolation.

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.

OS Package Where it goes
PortMaster retsurf-portmaster.zip ports folder, e.g. /roms/ports/
OnionOS retsurf-onionos.zip App/Retsurf/ on the SD card
Allium retsurf-allium.zip Apps/Retsurf.pak/ on the SD card
spruceOS retsurf-spruceos-aarch64.zip, retsurf-spruceos-armhf.zip (Miyoo Mini) root of the SD card
NextUI, NX Redux retsurf-nextui.zip root of the SD card, lands in Tools/
CrossMix-OS retsurf-crossmix.zip root of the SD card
Kindle (jailbroken) retsurf-kindle.zip root of the Kindle's USB storage
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 the Miyoo Mini firmwares, spruceOS included, the app shows up in the Apps menu, and MENU quits it. On spruceOS's aarch64 handhelds and CrossMix-OS it is under Apps too, and Select + Start quits it.

On Kindle, start it from KUAL (Retsurf > Start Retsurf) or from KOReader (Tools > Retsurf browser), and quit with Quit retsurf in the menu at the top left; it returns to where it was started.

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, Command line for arguments and environment variables, and Shaders for Game Mode shaders.

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

License

Copyright (C) 2025-2026 Maxim Gorin. retsurf is free software under the GNU General Public License v3.0 or later, with the additional terms in NOTICE. The name, logo and icons: TRADEMARKS.md.

About

Portable, gamepad-first web browser on Servo. Runs on retro handhelds, Android, Kindle, Linux, Windows and macOS

Topics

Resources

Security policy

Stars

78 stars

Watchers

2 watching

Forks

Releases

Contributors

Languages