Skip to content
JaseundaPublic

About

Run a real GNU/Linux distro on any Android device over ADB, no root, no app to install.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

53 Commits

Folders and files

Repository files navigation

ULS ~ Universal Linux Shell

Run a real GNU/Linux distro on any Android device over ADB — no root, no app to install.

     :::    ::::::       ::::::::
    :+:    :+::+:      :+:    :+:
   +:+    +:++:+      +:+
  +#+    +:++#+      +#++:++#++
 +#+    +#++#+             +#+
#+#    #+##+#      #+#    #+#     ULS — Universal Linux Shell
######## ##################

ULS sets up a rootfs container environment on any ADB-connected Android device, then boots an interactive Linux shell into it — all orchestrated from your Mac. Starting with Android via ADB, with more targets on the roadmap.


Table of Contents


Requirements

What Details
Mac Apple Silicon (arm64)
ADB brew install android-platform-tools
Android device ARM64 or ARMv7, Android 8+
USB cable Or an already-paired wireless ADB connection

Install from a Release

Option 1 — Quick Install (Recommended)

Run directly in your terminal:

curl -fsSL https://raw.githubusercontent.com/Jaseunda/uls/main/install.sh | bash

This will:

  • Automatically download the latest release .zip from GitHub Releases
  • Verify integrity against SHA256SUMS
  • Extract and install uls into ~/.uls/bin
  • Symlink to /usr/local/bin (or $HOME/.local/bin) so it's in your $PATH
  • Clear macOS Gatekeeper quarantine flags automatically

Option 2 — Manual Download

  1. Download the latest uls-<version>.zip from the Releases page.
  2. Unzip and install:
unzip uls-<version>.zip
cd uls-<version>
./install.sh
  1. Verify:
uls --help

Tip: If your shell doesn't pick up the PATH change, add export PATH="$HOME/.uls/bin:$PATH" to your ~/.zshrc or ~/.bashrc.


Quick Start

1 — Onboard your device

Connect your Android device over USB and run:

uls setup

This will:

  • Detect all connected ADB devices and let you pick one
  • Let you choose a Linux distro (Arch Linux, Ubuntu, Debian, Alpine, …)
  • Save a per-device config for future commands

2 — Deploy Linux to the device

uls deploy

Downloads the chosen distro bootstrap tarball matched to your device's CPU, then configures and extracts it on the device. First run takes a few minutes depending on your connection speed.

3 — Log in

uls login arch        # or: ubuntu, debian, alpine, etc.

Drops you into a full interactive Linux shell on the device. pacman, apt, apk — all work.


Commands

Command What it does
uls setup Interactive device onboarding + distro selection
uls deploy Download + push distro rootfs to device
uls login <distro> Enter the Linux container (real PTY)
uls upgrade Re-push ULS files — updates an already-installed Linux
uls repair Re-extract rootfs on-device (fixes corrupt installs)
uls distros List available distros and download links
uls monitor Watch USB/ADB device events in dmesg style
uls uninstall Remove ULS environment + rootfs from device ⚠

Passing flags

uls deploy --dry-run           # show the plan without touching the device
uls deploy --no-download       # use already-cached tarballs
uls deploy --repair            # re-extract rootfs from cached tarball
uls login arch 'echo hello'    # run a one-shot command inside the container

Supported Distros

ID Name Arches
archlinux Arch Linux (latest rolling) arm64, armv7
ubuntu Ubuntu 24.04 LTS (Noble) arm64, armv7
debian Debian 12 (Bookworm) arm64, armv7
alpine Alpine Linux 3.24 arm64, armv7

Run uls distros to see the live list with download links.

Want to add a distro? See Contributing a Distro.


Device Requirements

  • CPU: ARM64 (arm64-v8a) or ARMv7 (armeabi-v7a)
  • Android: 8.0+ (API level 26+)
  • System support: Kernel must allow container ptrace syscalls. Galaxy-class and standard ARM64 devices generally work.

Uninstall

From the device

uls uninstall             # from the phone
uls uninstall --dry-run    # preview what would be deleted

From your Mac

cd <the release folder you downloaded>
./uninstall.sh             # removes ~/.uls and the PATH symlink

Contributing a Distro

The distro catalog is community-maintained in this folder's latest.json.

To add a new distro or fix a dead mirror:

  1. Fork this repo.
  2. Edit latest.json — add your entry under "distros".
  3. Verify each URL is reachable: curl -sIL --max-time 20 <url>
  4. Open a PR — title format: [catalog] Add <distro-name> (<arch>)

See CONTRIBUTING.md for the full guide and entry format.


License

This repository contains two distinct licenses:

What License
Catalog data (latest.json, CONTRIBUTING.md, community docs) MIT — free to use, modify, and redistribute
uls binary and install.sh (distributed via Releases) Proprietary — see the NOTICE file inside each release ZIP

The uls binary is proprietary software © 2026 Jaseunda. Redistribution is not permitted without written permission. Third-party components (proot GPLv2, Arch Linux ARM) are credited in each release's NOTICE.

About

Run a real GNU/Linux distro on any Android device over ADB, no root, no app to install.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages