netoy-tui

Your USB, upgraded. A Ventoy-style ISO manager that lives in your terminal — browse, download, and manage bootable ISOs without leaving the shell. Built with ratatui.

Turn any Ventoy stick into a pocket distro library. Works offline, never rots, and tells you exactly when it's safe to pull the plug.

Screenshots

Welcome	Network

Manage ISOs	Download ISOs

The whole app is one flow: Welcome → Network → Manage ISOs → Download ISOs.

Why it's good

• Offline-first. Manage what's already on your stick with zero internet. Downloads light up the moment connectivity is confirmed.
• No rotting scrapers. A bundled resolver ships verified live ISO links for the big Linux distros and the BSD family — plus a terminal browser as the universal fallback, so nothing is ever a dead end.
• Official Windows ISOs. Mido pulls straight from Microsoft with SHA-256 verification, version by version.
• Safe to yank. Every write is fsync'd straight to disk — the app tells you when the stick is safe to pull, and it means it.

Flow

• Welcome — the pitch.
• Network — real connectivity check (interfaces → IP → DNS → HTTP probe). <R> re-checks, <C> continues offline. In the integrated build, <N> launches nmtui (NetworkManager's TUI) for WiFi and Ethernet, <B> switches the Wi-Fi backend (wpa_supplicant ↔ iwd) and restarts NetworkManager, and <T> runs a DNS/connectivity test.
• Manage ISOs — always available. Finds Ventoy sticks by the Ventoy partition label, mounts on demand (<M>), lists every .iso with sizes and free space, deletes with <X> + <Y> confirmation. <Tab> cycles when several sticks are plugged in.
• Download ISOs — unlocked only while online (sidebar shows [off] when locked, and navigation skips it). A collapsible source tree writes the chosen ISO straight onto the mounted stick:

  Browse for any ISO (links/lynx)
  ▸ Linux
  ▸ BSD
  ▸ Windows
  ▸ Other

Expand with Enter/→, collapse with ←, launch a leaf with Space/Enter/L.

The Other branch also groups the rescue/utility tools (GParted Live, Clonezilla Live, Rescuezilla, Hiren's BootCD PE, SystemRescue) under a Rescue / partitioning tools sub-branch, plus one-click links to netboot.xyz, Memtest86+, and Super Grub2 Disk.

The source tree

Source	Covers	Notes
links / lynx	Anything at all	the terminal browser; its d (download) saves straight to the stick. links is used when installed, lynx as fallback
netoy-iso.sh	Linux + BSD + Other	our bundled resolver (vendor/netoy-iso.sh). Each distro uses its most stable mechanism — stable redirect, directory autoindex + version-sort, or a pinned URL — and was verified to resolve a live ISO (HTTP 206). Arch, Alpine, Ubuntu, Debian, Fedora, openSUSE, Tails, Qubes, SystemRescue + Free/Open/NetBSD. Needs curl+wget (busybox provides awk/grep)
netboot.xyz	Proxmox VE + netboot.xyz menu ISO (Other)	the few full ISOs netboot.xyz hosts in its GitHub asset releases; its endpoints.yml is otherwise iPXE netboot assets, so only Proxmox and its own bootable menu ISO are wired through
Mido	Windows	official Microsoft ISOs with SHA-256 verify, subdivided by version (11 / 10 / 8.x / 7 / Older-Server). Needs curl; non-English via MIDO_LANGUAGE (default English (United States))

Rescue / partitioning tools (GParted Live, Clonezilla Live, Rescuezilla, Hiren's BootCD PE) are hosted on SourceForge, which presents a Cloudflare challenge to scripted clients — so those rows open the official download page in the terminal browser (the browser can complete the challenge interactively) rather than a resolver that would be challenged out. SystemRescue lives on a plain Fastly CDN, so it gets a real netoy-iso.sh autodownload under Linux; netboot.xyz and Memtest86+ are browser links too (the netboot.xyz menu ISO is directly fetchable, so its row is a browser link to netboot.xyz/ rather than a one-shot ISO).

Windows 11 LTSC and Windows 10 IoT Enterprise LTSC aren't published through Microsoft's consumer/eval API, so those entries open the official download page in the terminal browser rather than a Mido call that would fail.

After the Network check, the screen offers <M> (Manage) or <D> (Download — online only). If the Ventoy USB isn't mounted, Download shows a warning pointing you at <M> first; sources whose tool is missing are greyed out with what they need.

When you pick a source, the app flushes the whole USB to disk with a live progress gauge (fsync every .iso + the directory) — don't pull the stick while "flushing … to the USB" is showing.

Build modes

Compile-time choice via a Cargo feature — no runtime switch:

cargo build --release                          # standalone mode
cargo build --release --features for-bootable  # integrated mode

• standalone (default) — runs on an already-working machine. It checks internet access but never configures networking: that's the user's job.
• integrated (for-bootable) — runs inside the dedicated Alpine boot entry (see netoy-os). Network screen gains <N> (nmtui), <B> (Wi-Fi backend switch) and <T> (DNS test).

The embedded undo-trick (integrated build only)

When the netoy Alpine ISO is itself booted from the Ventoy stick, Ventoy's loop/CD-emulation trick pins the data partition (busy or read-only). At startup the integrated build undoes it: unmount the iso9660/loop/ventoy mounts, then mount the real data partition read-write at /mnt/netoy. Runs only as root; refuses to touch mounts as a regular user — so don't run the integrated binary on your desktop.

Connectivity probe

No catalogue, no single point of failure: the probe just checks https://example.com. Override it for testing with NETOY_PROBE_URL (e.g. an unroutable address to simulate offline):

NETOY_PROBE_URL=http://192.0.2.1:9 cargo run

The browser's start page defaults to https://distrowatch.com; override with NETOY_BROWSER_URL. The browser itself is whichever of links / lynx is installed (links preferred); pick one at runtime from the Download screen with B (cycles auto → links → lynx), or force it up front with NETOY_BROWSER (e.g. NETOY_BROWSER=lynx netoy-tui).

Keys

Key	Action
q / Esc	quit
n / →, p / ←	next / previous screen
↑ ↓ / u d, Enter	sidebar select / open
r	re-check network / rescan USB (Download) / rescan USB (Manage)
m	Manage ISOs (Network / Download screens) / mount the Ventoy USB (Manage)
d	Download ISOs (post-network prompt, when online)
w / e	(removed) — WiFi / Ethernet now go through <N> (nmtui)
n	launch nmtui (NetworkManager TUI) — integrated build only
b	switch Wi-Fi backend (wpa_supplicant ↔ iwd) + restart NetworkManager
t	DNS / connectivity test (ping IP + hostname) — integrated build only
↑ ↓	move cursor (sidebar / Manage ISO list / Download source tree)
Enter / Space	open section (sidebar) / expand-collapse branch or launch leaf (Download)
← / →	collapse / expand the source-tree branch under the cursor (Download)
L	launch the highlighted source leaf (Download screen)
B	cycle the terminal browser used for Browse rows: auto → links → lynx
x	delete ISO (Manage, <Y> confirms)
Tab	switch focus between sidebar and screen content

Development

cargo test                              # unit tests (gating, sources, USB, sync)
python3 scripts/smoke.py standalone     # pty tests: online + offline gating
python3 scripts/smoke.py integrated     # pty tests: for-bootable build
python3 scripts/smoke.py usb            # pty test: real Ventoy USB (mount + sources + delete)

The usb scenario expects a Ventoy stick at /dev/sdc1.

Bundled tools

netoy-tui ships with these projects — big thanks to their authors:

• Mido — official Windows ISO downloader (Microsoft's API + SHA-256 verify). MIT, © Elliot Killick. Bundled as vendor/Mido.sh, patched to honor MIDO_LANGUAGE.
• netboot.xyz — ISC-licensed network boot menu project; netoy grabs the full ISOs it hosts (Proxmox VE, its own bootable menu ISO) from its GitHub releases / boot server.
• links / lynx — the classic terminal browsers (links = links2, GPL-2), the universal fallback for anything not auto-resolved. links is used when installed, lynx otherwise.
• netoy-iso.sh — our own bundled resolver (vendor/netoy-iso.sh), written for this project; every resolver is verified to return a live ISO.