Skip to content

Standalone archive

A standalone archive runs FPLinux on one phone without a source checkout or build tools. If you received a ZIP, check that it names your exact phone and PC operating system. Its README.txt gives the boot key and startup commands. Check the phone’s support status and phone page for feature, storage and power limits.

No public ZIP release is available yet. You can build FPLinux and package an archive locally. Published archives and their matching sources belong on the Releases page.

Names use FPLinux-<target>-<linux|windows>-x64-<release_id>.zip. The twelve-character ID is shared by all phone and host variants in that Release. It also appears in Settings → About → Build on the phone. Check downloads against the Release’s SHA256SUMS, then keep the matching source ZIP available when distributing the runnable archive.

This format supports the default RAM profile, with archives for Linux x86-64 and Windows x64. USB loading and SSH from Windows have not been verified with Xiaomi Qin 1s+.

A RAM archive contains the RAM image, phone loader stages, Python, OpenSSH, a short README.txt, checksums and license notices. It contains no optional APKs or prepared phone data. The internal storage is never erased or written.

The archive includes any required extraction tools. It reuses compatible inputs and prepared data from your personal phone data store, including data saved by another archive or checkout. On first use, UMS9117 phones save a read-only NAND backup and Qin saves selected sound files from eMMC. Qin preparation does not make a full storage backup. Targets without required runtime data start Linux and open SSH immediately.

  • A Linux x86-64 PC with coreutils, iproute2, udev and a network manager that automatically runs IPv4 DHCP on a new USB network interface, such as NetworkManager; or a Windows 10 or 11 x64 PC with Windows PowerShell.
  • A USB data cable that fits your phone.
  • For UMS9117, enough free space for the full internal-storage backup in your personal phone data store.

Python and OpenSSH are bundled; no separate installation is needed. On Linux, the launcher asks for administrator access once if the included USB access rules need to be installed; this step requires sudo. On Windows, it can ask to set up the phone’s USB driver: read the described driver and certificate changes, confirm them with the checkbox and approve the administrator prompt. Run the launcher as your regular user.

  1. Extract the whole archive and keep the phone powered off and disconnected.

  2. Start the launcher from the extracted directory. On Linux:

    PC
    sh Run.sh

    On Windows, double-click Run.cmd.

  3. Wait until the launcher displays the connection instructions. Only then hold the boot key named in README.txt and connect the powered-off phone, keeping the key pressed.

  4. Keep USB connected. If compatible saved inputs are available, the launcher prepares data from them as needed and continues to Linux and SSH. Otherwise, it reads the required data from your phone. UMS9117 shows the progress of its full NAND backup; Qin reads its selected sound files. Wait until preparation and the storage check finish.

  5. If the launcher prints Disconnect USB., disconnect the cable. If the phone stays on, briefly remove and reinsert its battery. Run the launcher again with the phone powered off. This restart is needed only after reading new data from the phone.

Private connection keys and launcher logs are kept under .data/ beside the extracted launcher. FPLINUX_DATA_DIR selects another working data directory; relative values are anchored to the archive, not the terminal’s current directory. Copies in different folders have separate sessions even when they share a working directory. Keep the archive location and selected directory unchanged while reconnecting.

Backups and prepared data use the separate personal store, which survives replacing the archive. Use each store with one physical phone; FPLinux does not distinguish handsets of the same target automatically. Add --phone-data PATH to sh Run.sh or Run.cmd to select a separate store for another phone.

Each launch prints the exact path to its runtime.log, with run.json metadata beside it. The log includes launcher and USB loader diagnostics, but does not record your interactive SSH commands or terminal output. If preparation cannot verify that storage is safe to disconnect, it retains reader-session keys in the same working data directory. Keep the phone powered and retain that directory. Run the launcher again to reconnect and repeat the storage check; do not remove power while storage safety is unresolved. --reconnect requires a normal session and cannot reopen this preparation session.

Use the same sh Run.sh on Linux or Run.cmd on Windows for every later launch. If your phone is still running FPLinux, connect it to resume SSH with its saved keys. This also works if you reconnect USB after starting the launcher. For a fresh boot, keep the phone powered off and disconnected until the launcher displays the connection instructions. Then connect it with its boot key held. The launcher loads FPLinux with your prepared phone data and opens an SSH shell.

If SSH loses its connection during an interactive shell and the phone stays powered, the launcher waits for the same phone to return, verifies its connection and opens a new shell. It does not repeat commands from the interrupted shell. Reconnect USB if disconnected before the wait times out, or open the launcher again afterward. Ctrl+C cancels the wait. Interactive SSH status 255 starts this recovery; use exit 0 to close the shell unconditionally.

Type exit or press Ctrl+D to close the shell; Linux keeps running on the phone. Open the same launcher to connect again. Only one launcher can run from the same extracted directory at a time; close its active launch before opening another. A connection that is present but cannot be verified stops with an error instead of starting another load. Ctrl+C cancels loading or waiting, but does not power the phone off.

The matching source ZIP contains the project sources, selected upstream originals and host rebuild material. A complete Release shares FPLinux-<release_id>-sources.zip across all its runnable ZIPs; a local package can have its own matching companion. Follow the exact filename in README.txt. Component licenses remain in the runnable archive. Dependency inputs for rebuilding are separate Release assets; see Dependency snapshots.

For UMS9117, you can select a complete physical NAND backup of the same phone for a RAM launch. On Linux:

PC
sh Run.sh --from-dump /path/to/nand.bin

On Windows, open a terminal in the extracted directory:

PC
Run.cmd --from-dump "C:\path\to\nand.bin"

Keep its nand.bin.json receipt beside it. The launcher preserves both input files, imports the backup into the selected personal store and reuses or replaces prepared data there as needed. It then continues the normal boot in the same invocation. Keep the phone disconnected until the loader asks for it. To prepare data without booting, use the source checkout’s device-data prepare --from-dump.

For Qin, use the same option with a complete eMMC USER-area image containing GPT. The launcher extracts the selected sound files without changing or copying the whole image. A NAND image or a single partition is not an eMMC USER-area image.

A local microSD system-card export uses the shared fplinux.py runtime with Python and OpenSSH supplied by your PC. Its filename includes the selected profile, such as microsd-uboot. It can contain prepared personal data selected by its build; keep it private. System-card exports are excluded from the public RAM release matrix and include docs/index.html for reading the site offline.

You need Linux x86-64, Python 3.14, GNU stdbuf from coreutils, ip from iproute2, and ssh, ssh-keygen, ssh-keyscan and sftp from OpenSSH. A network manager must automatically run IPv4 DHCP on the phone’s USB network interface.

The phone-side loader stages are included in the archive, including FDL1, FDL2 and SML for Qin.

  1. Extract the whole archive, enter its top-level directory and check every file:

    PC
    cd <extracted-top-level-directory>
    sha256sum -c SHA256SUMS
  2. Install the USB rules and reload them:

    PC
    sudo install -m 0644 ./60-fplinux.rules /etc/udev/rules.d/60-fplinux.rules
    sudo udevadm control --reload-rules

    Disconnect the phone if it is attached. On a headless PC, edit your installed copy to use a local group with MODE="0660" instead of TAG+="uaccess". Never make the USB devices world-writable.

SHA256SUMS checks that the extracted files are complete and unchanged. It does not show that the archive is authentic or that the phone works.

If the archive contains FPLINUX.img.xz, it boots from a microSD system card. Prepare the card first; see microSD system card.

Run the runner as your regular user, not as root.

  1. Power the phone off and disconnect USB.

  2. Start the runner:

    PC
    python3.14 -I fplinux.py run
  3. Wait until it asks for the phone.

  4. Only then hold the boot key named in README.txt and connect the powered-off phone, keeping the key pressed.

  5. Wait for the runtime to open a shell when the session is ready. Repeat the same command to reopen a running session.

Exiting the shell does not stop Linux. Reconnect, run one command or copy files with --reconnect:

PC
python3.14 -I fplinux.py run --reconnect
python3.14 -I fplinux.py run --reconnect --exec 'uname -a'
python3.14 -I fplinux.py run --reconnect --upload ./song.wav /tmp/song.wav
python3.14 -I fplinux.py run --reconnect --pull /tmp/photo.jpg ./photo.jpg

Linux RAM launchers accept the same options, for example sh Run.sh --reconnect --exec 'uname -a'. File transfer requires a Linux host; native Windows supports the SSH and NAND workflows. To add applications, see Optional packages. The feature pages describe how to use supported features from an archive.

For machine-readable progress during a fresh runner load, add --events PATH; see loader events.

For a fresh RAM load, connect the phone only when the launcher or runner asks. If you connected it too early, disconnect it, power it off and start again. To reopen SSH to the same running phone, leave it connected or reconnect USB while the launcher is waiting.

Exiting a launcher or shell leaves Linux running. To end the session without losing data, follow Power. Without a battery, disconnecting USB cuts power immediately.