LiveUSBAgent-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
LiveUSBAgent-mcp
Bootable Debian 13 (Trixie) LiveUSB rescue OS that turns any broken or bare-metal PC/laptop into an AI-assisted sysadmin, OS repair, and data-recovery workstation — controlled via MCP directly from Gemini, ChatGPT, or Claude.
Русская версия: README_RU.md
Repository: github.com/LevRa7/LiveUSBAgent-mcp (evolved from github.com/LevRa7/remote-harness-mcp)
What It Is & Purpose
When a PC refuses to boot, a drive starts failing, BitLocker or LUKS locks you out, or you need to rescue files from a Windows, Linux, or macOS disk, you usually have to memorize obscure rescue commands on a bare terminal.
LiveUSBAgent-mcp solves that for both beginners and experienced sysadmins:
For beginners: Plug in the USB stick, boot the broken PC, connect to Wi-Fi or tether your phone on the graphical screen, scan the QR code, and paste one link into Gemini, ChatGPT, or Claude. You can then describe the problem in plain language while the AI inspects disks, reads logs, and guides or executes the recovery.
For sysadmins & engineers: Get an instant, zero-config Debian 13 (Trixie) rescue environment loaded with cross-OS filesystem drivers (NTFS/BitLocker, ext4/Btrfs/XFS/F2FS/ZFS/LVM/mdadm/LUKS, HFS+/APFS), hardware/RAM diagnostics, curated
SKILL.mdplaybooks, and full root MCP access over an outbound TLS WebSocket tunnel — no SSH setup, no port forwarding, and no manual agent installation.
Gemini (/sse) · ChatGPT (/mcp) · Claude (/mcp, CLI or JSON)
│ MCP over HTTPS
▼
Mesh Gateway (/connect/<session_code>)
│ Outbound WebSocket tunnel (no open ports)
▼
Booted LiveUSB (Debian 13 Trixie · python3 -m core.agent --ephemeral-liveusb)
├─ tty1: Graphical Kiosk UI (127.0.0.1:8787) — Wi-Fi, USB tethering, SVG QR
├─ tty2: Fallback console dashboard (firstboot_tui.py + nmtui + [S] Shell (bash))
└─ Full root MCP tools + read-safe rescue_info / rescue_action + SKILL.md libraryRelated MCP server: SSH MCP Server
Key Features
1. Broad Hardware, Wi-Fi & Phone USB Tethering Out of the Box
Firmware & drivers (
non-free-firmware): Ships withfirmware-linux,firmware-linux-nonfree,firmware-misc-nonfree,firmware-iwlwifi(Intel Wi-Fi 6/6E/7),firmware-realtek,firmware-atheros,firmware-brcm80211(Broadcom),firmware-mediatek,firmware-marvell-prestera,firmware-qcom-soc,firmware-ti-connectivity,firmware-zd1211, andfirmware-libertas, plusnetwork-manager,wpasupplicant,iw,rfkill,ethtool,usb-modeswitch,modemmanager,wireguard-tools, andopenssh-client. Out-of-tree DKMS support includesbroadcom-sta-dkmsfor older Broadcom/MacBook Wi-Fi adapters.iPhone USB Tethering (iOS): Preinstalled
usbmuxd,ipheth(ipheth-utils),libimobiledevice-utils(idevicepair,ideviceinfo), andifuse. Plug in an iPhone with Personal Hotspot enabled, tap Trust, and NetworkManager brings up DHCP automatically.Android USB Tethering: Built-in
rndis_host,cdc_ether, andcdc_ncmsupport with99-rhm-network-tethering.rulesso newly attached USB-Ethernet interfaces automatically acquire DHCP.
2. Graphical Kiosk Startup Screen + Console Fallback
Kiosk UI (
tty1): Boots directly into a clean fullscreen Chromium kiosk overopenbox/ Xorg served locally byops/live-usb/kiosk_server.pyon127.0.0.1:8787. Features an interactive Wi-Fi scanner (nmcli) withОбновить список(refresh list) andСкрытая сеть(hidden SSID) controls, a password modal with an on-screen keyboard (handy for touchscreens or broken laptop keyboards), live Ethernet & USB tethering status (including an iPhone Trust prompt when unpaired), and a Ready view with a large SVG QR code, a detected-disks summary,Сменить Wi-Fi(switch Wi-Fi), andНовый токен(regenerate token).Headless / GPU Fallback (
tty2):ops/live-usb/firstboot_tui.pyruns ontty2(switch viaCtrl+Alt+F2; also takes over automatically if X11 cannot start), giving full status, QR code,nmtuinetwork configuration, and a localbashshell viaCtrl+Alt+F2→[S] Shell (bash).
3. Zero-Config Ephemeral Onboarding
As soon as the LiveUSB gets internet access,
rhm-live-agent.service(python3 -m core.agent --ephemeral-liveusb) automatically registers a temporarylive-*node with the gateway (POST /v1/liveusb/register).Generates an ephemeral 24-hour
lk_...link key stored only in RAM (/run/rhm-live/) and displays a QR code pointing tohttps://<gateway>/connect/<session_code>.Scanning the QR code on your phone or second computer opens a mobile-friendly pairing page with 1-click copy buttons for Gemini (
/sse), ChatGPT (/mcp), and Claude (/mcpURL,claude mcp add --transport http ...CLI command, andmcpServersJSON config) plus live connection status.
4. Out-of-the-Box Cross-OS Filesystem Support
OS Family | Filesystem / Volume | Included Packages & Modules | Capabilities & Notes |
Cross-platform | exFAT |
| Full R/W, |
Cross-platform | FAT32 / FAT16 ( |
| Full R/W, EFI System Partition (ESP) repair. |
Windows | NTFS | Kernel | Full R/W via |
Windows | BitLocker |
| Decrypt with password or 48-digit recovery key, then mount NTFS. |
Linux | ext2 / ext3 / ext4 |
| Full R/W, |
Linux | Btrfs |
| Full R/W, subvolumes, snapshots, |
Linux | XFS |
| Full R/W, |
Linux | F2FS |
| Full R/W ( |
Linux | ZFS (OpenZFS) |
| Full R/W and read-only |
Linux | LVM2 / mdadm / LUKS |
| Manual RAID assembly, LUKS1/LUKS2 unlock, and LVM activation. |
macOS | HFS / HFS+ |
| Safe R/O; R/W supported ( |
macOS | APFS |
| Dual-mode: native |
5. Built-In Progressive SKILL.md Library
Instead of flooding the AI's context window with dozens of long manuals, LiveUSBAgent-mcp exposes two progressive-disclosure MCP tools (list_skills and load_skill) backed by /opt/remote-harness-mcp/skills/:
4 custom LiveUSB recovery skills in
skills/liveusb/:windows-offline-boot-repair— UEFI/ESP & BCD repair, offline Windows Registry (chntpw,libhivex-bin),ntfsfix, and BitLocker decryption.linux-chroot-grub-luks-rescue— Safemdadm->cryptsetup->lvm2assembly,chroot, GRUB/systemd-boot, andinitramfsrebuilds.macos-apfs-hfs-recovery— Safe data extraction from APFS (apfs-dkms/apfs-fusefor FileVault /libfsapfs-utils) and HFS+.ram-hardware-live-diagnostics— Hardware inventory (dmidecode,lshw,lspci,lsusb,lm-sensors), live RAM stress testing (memtester), and memory capture (/proc/kcoreworks out of the box;avmlis not preinstalled in the ISO and is optional if installed separately).
Curated external skills (
ops/live-usb/fetch-skills.sh): Downloads vetted GitHub sysadmin, DevOps, storage, and recovery skills listed inops/live-usb/skills-manifest.json, records exact commit SHAs inops/live-usb/skills-lock.json, and scans them offline with NVIDIA/SkillSpector (--recursive --no-llm) when installed.
Step-by-Step: Build, Flash, Boot & Use
Note: Prebuilt ISO releases are not published yet — ISO images are currently built locally on a Debian 13 (Trixie) host or VM.
Step 1: Build the ISO (on Debian 13 Trixie)
Install the build prerequisites on a Debian 13 (Trixie) host or VM:
sudo apt-get update
sudo apt-get install -y \
live-build debootstrap squashfs-tools xorriso \
grub-efi-amd64-bin grub-pc-bin mtools dosfstools \
curl jq git ca-certificatesConfigure and build the hybrid ISO (including curated external skills):
git clone https://github.com/LevRa7/LiveUSBAgent-mcp.git
cd LiveUSBAgent-mcp
sudo ./ops/live-usb/build-iso.sh --with-external-skills --buildUseful build-iso.sh options:
--work-dir PATH— Customlive-buildworkspace (default:/tmp/rhm-live-build; use e.g./var/tmp/rhm-live-buildif/tmpis small).--gateway HOST— Mesh gateway hostname (default:smart-server.online).--distro NAME/--arch ARCH— Debian suite and architecture (defaults:trixie,amd64).Omit
--buildif you want to inspect the generatedlive-buildconfig before runningsudo lb buildmanually.
The finished hybrid image (live-image-amd64.hybrid.iso) is written to your WORK_DIR.
Optional: Test in QEMU/KVM Before Flashing
# UEFI boot with auto-created virtual test disks (exfat, ntfs, ext4, btrfs, xfs, vfat)
./ops/live-usb/test-qemu.sh --mode uefi --create-fs-disks
# Legacy BIOS and Low-RAM (< 4 GB) check
./ops/live-usb/test-qemu.sh --mode bios --ram 2048
# Headless serial-console mode for CI or previewing the exact QEMU command
./ops/live-usb/test-qemu.sh --headless --create-fs-disks
./ops/live-usb/test-qemu.sh --dry-run --mode uefi --create-fs-disks(Requires qemu-system-x86, ovmf, and filesystem tools exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs, xfsprogs, dosfstools.)
Step 2: Flash the ISO to a USB Drive
The ISO is hybrid (UEFI + Legacy BIOS). Choose whichever tool fits your OS:
Ventoy (recommended for multi-boot USBs): Install Ventoy onto a USB stick and copy the
.isofile straight onto the Ventoy partition. If normal mode has issues on a specific machine, choose Grub2 mode in the Ventoy menu.Rufus (Windows): Select your USB drive and the
.isofile, then click START. When prompted, choose Write in DD Image mode to preserve the hybrid UEFI/BIOS partition layout.balenaEtcher (Windows / Linux / macOS): Click Flash from file, pick the
.iso, select your target USB drive, and click Flash!.dd(Linux / macOS): Verify the target device withlsblk(Linux) ordiskutil list(macOS), then write to the whole disk (not a partition):sudo dd if=/tmp/rhm-live-build/live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress oflag=sync sync
Step 3: Boot from USB (UEFI / BIOS, Secure Boot & GRUB Menu)
Insert the USB drive, power on the target PC, and open its boot menu (
F12,F8,F11,Esc, orOptionon Intel Macs).Secure Boot note: The image includes
shim-signedand Debian's signed kernel, so basic boot works with Secure Boot enabled. However, unsigned out-of-tree DKMS kernel modules — specificallyapfs-dkms(Apple APFS),zfs(OpenZFS), andbroadcom-sta-dkms(some Broadcom Wi-Fi cards) — will be blocked by the kernel while Secure Boot is on. Disable Secure Boot in UEFI/BIOS (or enroll a MOK key) if you need APFS, ZFS, or Broadcom Wi-Fi.Choose an entry in the GRUB boot menu:
Remote-Harness LiveUSB (Load to RAM / toram, >= 4 GB RAM)(default) — Copiesfilesystem.squashfscompletely into RAM. Fast, responsive, and lets you unplug the USB stick after boot.Remote-Harness LiveUSB (Low RAM < 4 GB, boot from USB)— Reads SquashFS directly from the USB drive to conserve RAM. Keep the USB stick plugged in until shutdown.Memtest86+— Standalone pre-boot memory hardware tester (works on both UEFI and Legacy BIOS).
Step 4: Connect to the Internet
Once the Kiosk screen appears on tty1:
Ethernet: Plug in a cable — DHCP connects automatically.
iPhone USB Tethering: Enable Personal Hotspot on your iPhone, connect via USB, unlock the phone, and tap Trust This Computer (enter passcode). The Kiosk screen prompts you if pairing is still pending.
Android USB Tethering: Connect via USB and toggle USB Tethering in Android network settings — DHCP connects automatically.
Wi-Fi: Pick your network on the Kiosk screen (click
Обновить списокto rescan orСкрытая сетьto connect to a hidden SSID), and enter the password using your keyboard or the built-in on-screen keyboard.Console fallback / local shell: Press
Ctrl+Alt+F2forfirstboot_tui.py, where you can launchnmtuior open a localbashshell via[S] Shell (bash).
Step 5: Pair with Gemini, ChatGPT, or Claude
As soon as the LiveUSB is online, the Kiosk Ready screen displays a large SVG QR code, short pairing URL (https://<gateway>/connect/<session_code>), detected-disks summary, Сменить Wi-Fi, and Новый токен:
Scan the QR code with your phone or open the URL on another device.
Copy the MCP URL or config for your AI client:
Gemini (Web / Mobile): Copy the
/sseURL (https://<gateway>/sse?user=<live_node_id>&token=<lk_...>) and add it as an MCP connector.ChatGPT: Copy the
/mcpURL (https://<gateway>/mcp?user=<live_node_id>&token=<lk_...>) and add it under Custom MCP Servers.Claude (Claude.ai Custom Connectors / Claude Desktop / Claude Code): Copy the
/mcpURL, theclaude mcp add --transport http ...CLI command, or the one-clickmcpServersJSON snippet shown on/connect/<session_code>.
Start with a first prompt:
"Check
mesh_statusand runrescue_info(summary) to show me all disks, partitions, and detected operating systems.""My Windows PC won't boot. Load the
windows-offline-boot-repairskill and inspect the EFI partition and NTFS health read-only first.""Check SMART health and kernel I/O errors (
dmesg_io) on/dev/nvme0n1, then prepare a safeddrescueplan to my external drive.""Run
rescue_infowithram_infoand show all DIMM slots, ECC status, and available RAM."
Available MCP Tools & Use Cases
LiveUSB-Specific Tools
Tool | Purpose | Key Parameters / Capabilities |
| Read-only hardware, disk, OS, RAM, and driver diagnostics (never modifies disks). |
|
| Controlled recovery actions with mandatory |
|
| Progressive discovery of installed | Optional filters: |
| Loads full instructions for a skill or a specific file from its |
|
Core System, File & Background Job Tools
Tool | Purpose |
| Verify node connectivity, active session, and reachability. |
| Host summary: OS, kernel, CPU, memory, disks, load, and top processes. |
| Real-time CPU, RAM, and disk utilization metrics. |
| Run shell commands directly on the LiveUSB host as |
| Read line-numbered files, write files atomically, or apply exact string replacements. |
| Browse directories, find files by glob pattern, and recursively search file contents. |
| Run long tasks ( |
| Inspect or adjust node settings (access mode, working directory, pause/resume). |
Concrete Rescue Use Cases
Windows Unbootable / BitLocker Repair: Detect Windows partitions and EFI entries via
rescue_info(boot_efi, win_artifacts), unlock BitLocker volumes withdislockerorcryptsetup --type bitlk, clear dirty NTFS flags (ntfs_fix), or edit offline Registry hives (chntpw,libhivex-bin) guided bywindows-offline-boot-repair.Linux GRUB / LUKS / LVM / RAID Chroot Rescue: Inspect arrays with
rescue_info(raid_lvm), assemblemdadm, unlock LUKS, activate LVM volume groups, chroot viachroot_exec, and repair GRUB or rebuildinitramfsguided bylinux-chroot-grub-luks-rescue.macOS APFS / HFS+ Data Extraction: Mount unencrypted APFS read-only with
apfs-dkms, unlock FileVault APFS volumes read-only withapfs-fuse, inspect damaged containers withlibfsapfs-utils, or extract data from HFS+ (hfsplus/libfshfs-utils) guided bymacos-apfs-hfs-recovery.Failing Disk
ddrescueImaging: Checkdmesg_ioandsmartbefore mounting anything, mount damaged filesystemsro,noloadviamount_safe, or generate a resumablegddrescueplan (ddrescue_plan) with a mapfile writing strictly to non-volatile external storage.RAM & Hardware Diagnostics: Inventory DIMM modules, ECC error counters (
edac-utils), PCI/USB devices, and temperatures (lm-sensors); run live memory stress tests (ram_test_plan->memtester), capture physical memory (ram_dump_plan->/proc/kcoreworks out of the box;avmlis not preinstalled and is optional if installed separately), or reboot intoMemtest86+from GRUB.
Security Model & Safety Guardrails
LiveUSBAgent-mcp is designed to be transparent about both its power and its built-in protections:
1. Full Root Access & Trust Boundary
On a booted LiveUSB,
rhm-live-agent.serviceruns asrootwithMESH_SCENARIO=live_usb,MESH_ACCESS_MODE=full, andMESH_WORKSPACE=/so the AI can immediately diagnose hardware, mount partitions, and repair operating systems without blocking on local approval prompts.Physical/screen possession of the QR code and
lk_...token is the trust boundary. Treat the pairing URL and token on screen like a temporary root password — do not share screenshots of the Kiosk QR code publicly.
2. Ephemeral Credentials & Session Lifecycle
Credentials are generated per boot in RAM (
/run/rhm-live/) with a 24-hour TTL.Clicking
Новый токен(token regeneration) in the Kiosk UI or a graceful agent exit (atexiton clean shutdown/reboot) calls/v1/liveusb/revokeon the gateway to invalidate the active session andlk_...key immediately; a hard power-off falls back to the 24-hour TTL.The gateway enforces a
LIVEUSB_MAX_ACTIVEcap on concurrent ephemeral LiveUSB sessions.The local UI state file (
session.json) is written with strict0600permissions and intentionally excludesdevice_tokenso the tunnel credential is never exposed to the Kiosk frontend.
3. Storage & OS Safety Guards
No silent automounting:
/etc/udev/rules.d/99-rhm-no-automount.rulesdisables automatic mounting at boot so failing or dirty disks are never touched before inspection.No automatic LVM/RAID activation:
/etc/lvm/lvm.conf(auto_activation_volume_list = []) and/etc/mdadm/mdadm.conf(AUTO -all) prevent the kernel from auto-assembling degraded host arrays on boot.Dry-run & read-only defaults:
rescue_actiondefaults todry_run=True(previewing exact commands before execution) andwritable=False(ro,noloadformount_safe).Mountpoint restrictions:
rescue_actionrestricts target mount directories to/mnt/rescue/*and/mnt/scratch/*.Volatile RAM-disk write refusal: Before creating disk images (
ddrescue_plan) or RAM dumps (ram_dump_plan),core/rescue.pyinspects/proc/mountsand refuses destinations on volatiletmpfs,ramfs,overlay,squashfs, ordevtmpfsfilesystems (including/tmp,/run, and/var/tmp) to prevent crashing atoramsession via OOM. Also capsjournaldto50Mvolatile RAM (Storage=volatile,SystemMaxUse=50M).APFS experimental-write warning: APFS volumes default to read-only. Encrypted FileVault volumes use read-only
apfs-fuse. Write mode on unencrypted APFS (apfs-dkms) is explicitly flagged as experimental and requires opt-in after backing up critical data.
4. Network, UI & Skill Safety
Active uplink protection (
active_uplink_lock): Protects the active default-route interface carrying the WebSocket tunnel from accidental disconnection during network troubleshooting.Hardened loopback-only Kiosk server:
ops/live-usb/kiosk_server.pybinds strictly to127.0.0.1:8787(never exposed on LAN/WAN) and enforces loopbackHost,Origin, and CSRF checks on mutating endpoints.Hardened
/connect/<session_code>pairing page: Served by the gateway with non-wildcard CORS, a per-response CSP nonce, andX-Frame-Options: DENYto prevent clickjacking and cross-origin token theft.Strict transport hardening: Outbound agent-to-gateway HTTP calls enforce TLS 1.2+ with HTTP redirects disabled.
Path-traversal rejection:
load_skillvalidates everyreference_filepath and rejects..traversal or absolute paths outside the skill'sreferences/directory.Offline skill security scanning: External skills fetched by
ops/live-usb/fetch-skills.share commit-SHA pinned inops/live-usb/skills-lock.jsonand scanned offline withSkillSpector(--recursive --no-llm) against prompt injection and tool poisoning.
Additional Documentation
LiveUSB ISO build & QEMU testing guide: ops/live-usb/README.md
Russian README: README_RU.md
Architecture & development roadmap: ProjectPlan.md
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives AI assistants full SSH/SFTP remote operations — session management, command execution, interactive shells, file transfers, port forwarding, and system diagnostics.2MIT
- AlicenseAqualityDmaintenanceEnables AI tools to manage SSH connections, execute commands, transfer files, and perform remote server diagnostics via MCP protocol.1710 npmMIT
- AlicenseNot gradedqualityDmaintenanceA free, open-source MCP server that gives AI agents real filesystem, terminal, git, and process control over your machine for inspection, diagnosis, and repair.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to perform comprehensive Windows system health diagnostics, security checks, developer workflows, and maintenance tasks via 85 tools with actionable recommendations, over MCP and OpenAI-compatible HTTP.MIT