URAAM

Universal Ruvomain ADB App Manager

URAAM is an open-source Bash toolkit for managing Android applications from a terminal. It provides package preview, carefully gated debloating, backup and restoration lists, APK installation, wireless ADB helpers, and support for multiple device-control backends.

It is designed to keep operations visible: URAAM shows the packages it intends to affect, requires explicit confirmation for destructive debloating, and records interrupted operations for manual reconciliation.

Important: Android package changes can remove features or make a device unstable. UAD risk labels and OEM profiles are advisory data, not guarantees. Read the preview, keep a backup, and never remove a package unless you understand its role.

Contents

• Features
• Supported environments
• Install
• Connect an Android device
• Debloat safely
• Backup and restore
• APK installation
• Data locations
• Documentation
• Development and tests
• Contributing
• License and acknowledgements

Features

• ADB, local root and Shizuku backends: use the control method available on the host/device.
• Preview before action: compare a selected JSON profile with the packages installed for Android user 0.
• Manual UAD-NG review: show package descriptions, categories and risk levels. Each package must be selected explicitly.
• Fail-closed selection: URAAM blocks protected, UAD-NG Unsafe, and unknown/unlisted packages in the UAD-NG selection flow.
• Dry-run: inspect the exact selected operations without uninstalling or disabling anything.
• Explicit apply gate: destructive debloat requires the exact APPLY N confirmation.
• Fresh-state validation: URAAM refreshes the package inventory and device identity before applying, including again after acquiring the exclusive apply lock.
• Dependency context: display UAD-NG dependency and reverse-dependency information when available. This metadata is advisory and incomplete.
• Interrupted-operation recovery: a private journal records an operation before it is sent; uncertain operations require human inspection and acknowledgement.
• Timeouts and transport checks: bounded device commands and backend health checks prevent a stalled or disconnected session from silently continuing a batch.
• Backup / restore lists: save packages missing for Android user 0 and ask Android to re-enable/reinstall existing system package records.
• Batch APK installation: install APK files placed in the configured Apps directory.
• Logs and updater: inspect operation logs and use the built-in updater where supported.
• Optional desktop foundation: an experimental GTK4 frontend can display device status and the installed user-0 package inventory; the Bash CLI remains the complete interface for package operations.

Supported environments

Environment	Device connection / backend	Notes
Android with Termux	ADB, Shizuku (rish), or local root	Termux storage permission may be requested
Linux desktop	ADB, local root where configured	Debian/Ubuntu packages and standalone installation are provided
WSL	ADB to a reachable Android device	USB passthrough/ADB transport must be configured separately
macOS	ADB	Install Android platform-tools and GNU coreutils (gtimeout)
Other Linux distributions	ADB; root backend where available	Install the required host tools manually if the installer cannot resolve them

URAAM manages Android user 0 package state. It does not modify Android system partitions or flash firmware. Backend availability and Android permission behavior vary by device and OS release.

Install

Universal installer

Review the installer before running it. Then launch it with Bash:

bash <(curl -fsSL https://raw.githubusercontent.com/Ruraam/Uraam/main/installer.sh)

If curl is unavailable, download installer.sh from this repository and run it locally with Bash. On Linux desktops, the installer asks whether to install the optional GTK4 desktop frontend. Choosing No keeps the Bash-only installation unchanged. Termux remains CLI-only.

Debian / Ubuntu

Use the latest .deb asset from the GitHub Releases page:

sudo apt install ./uraam-debian_VERSION_all.deb

Replace the filename with the exact asset downloaded. APT resolves declared package dependencies. To get the interactive GUI opt-in, GTK4 dependency installation and desktop-menu registration, use the universal installer above; a direct .deb installation does not enable the optional GUI menu entry automatically.

Run from a clone

git clone https://github.com/Ruraam/Uraam.git
cd Uraam
bash ./uraam.sh

Optional GTK4 desktop

During installation, choose Yes when the installer asks whether to install URAAM Desktop. On Debian/Ubuntu, it installs the GTK4 runtime dependencies and registers URAAM Desktop in the applications menu with the official SVG icon. The standalone Linux installer provides the same integration under /usr/local. Termux remains Bash-only.

You can also install the frontend dependencies manually and launch uraam-gui. The current GUI displays device identity and the installed Android user-0 package inventory; debloat and other package-changing workflows remain in the Bash interface. See URAAM Desktop architecture for the API boundary and current limitations.

Do not run an unreviewed script as root. Use the least-privileged backend that meets your needs.

Connect an Android device

Choose one connection method:

1. USB ADB: enable Developer options and USB debugging, connect the device, accept the authorization prompt, then verify it with adb devices.
2. Wireless debugging: use Android's Wireless debugging pairing flow or URAAM's wireless helper. Keep the host and device on the same trusted network.
3. Shizuku: start Shizuku and make its rish command available in the Termux environment before selecting the Shizuku backend.
4. Local root: use only on a rooted Android environment where the su command is available and authorized.

See the Quick Start and Shizuku / Wireless ADB guide for detailed setup.

Debloat safely

1. Connect to the intended device and confirm its identity.
2. Open Debloat apps and choose a JSON configuration.
3. Choose Uninstall for user 0, Disable, or cancel.
4. Review the package inventory classification:
   • selectable UAD-NG candidates: Recommended, Advanced or Expert;
   • blocked: Unsafe and unknown/unlisted UAD-NG entries;
   • protected by URAAM: packages covered by the built-in safety guard;
   • not installed: packages absent from the active user-0 inventory.
5. Select package numbers individually. There is no implicit select-all operation.
6. Review the final package list, OEM/ROM information and any dependency warnings.
7. Choose Dry-run to stop without changing package state, or Apply to continue.
8. For Apply, type the exact confirmation shown by URAAM, such as APPLY 2.

Before the commands are sent, URAAM refreshes the package inventory and rechecks device/OEM/ROM identity. It then acquires an exclusive lock and repeats the critical validation. If the state changed, the operation is aborted.

Risk labels are not safety guarantees. A package marked Recommended by UAD-NG may still be required by a particular device, carrier, region, application or firmware feature. OEM profile matches are informational cross-checks, not approval to remove a package.

Read Debloat safety and recovery and the UAD-NG catalogue policy before applying changes.

Backup and restore

From the dashboard:

• Choose Backup restoration list to save packages that are present in the device package database but are not currently installed for user 0.
• Choose Restore packages to pass the selected list to Android using pm install-existing --user 0.

This is a restoration list, not a complete device backup. It does not contain APK payloads, app data, settings, photos or firmware. Restoration works only when Android still has the package available on the device; it cannot reinstall an APK that has been completely removed from the package database.

Keep exported JSON files somewhere safe and review their contents before restoring.

APK installation

Place one or more .apk files in the Apps directory shown in the dashboard. Choose Install APK(s) and confirm the batch. URAAM reports successful and failed installs; it does not certify the APKs as trustworthy.

Install APKs only from sources you trust.

Data locations

Paths depend on how URAAM is installed:

Data	Portable checkout	Installed layout
Application files	Repository directory	Installation prefix / package-managed paths
User debloat profiles	Configs/debloat/	$XDG_CONFIG_HOME/uraam/debloat or ~/.config/uraam/debloat
APK staging	Apps/	$XDG_DATA_HOME/uraam/Apps or ~/.local/share/uraam/Apps
Restoration lists	Configs/backup-restore/	$XDG_DATA_HOME/uraam/Configs/backup-restore
Logs and operation journal	Logs/	$XDG_DATA_HOME/uraam/Logs

For installed paths, XDG_DATA_HOME and XDG_CONFIG_HOME are respected when set. The exact active paths are printed in the dashboard.

Documentation

Guide	Description
Documentation index	All user, maintainer and contributor guides
Quick Start	Installation, dependencies and first connection
Architecture	Runtime layout, backends, data flow and boundaries
Safety and Recovery	Preview/apply gates, timeout behavior, journal and lock
UAD-NG review catalogue	Pinned source, risk labels, dependency data and selection policy
Shizuku and Wireless ADB	Pairing and connection setup
Configuration format	JSON profiles, validation and OEM profile rules
Contributing	Code, documentation and profile contributions
URAAM Desktop architecture	GTK4 frontend, read-only JSON bridge and safety boundaries

Development and tests

The repository includes shell-safety, preview/dry-run, interrupted-process and metadata validation tests. On a Debian/Ubuntu development host:

sudo apt-get update
sudo apt-get install --yes bash jq shellcheck python3
bash -n uraam.sh
shellcheck --severity=error uraam.sh tests/*.sh
python3 tests/validate_uad_metadata.py
bash tests/test-preview-dry-run.sh
bash tests/test-interrupted-process.sh

The tests use mocks. They do not replace testing with a real Android device, each supported backend, or every host operating system. See the workflow files under .github/workflows/ for the CI commands.

Contributing

Issues, reproducible bug reports, documentation improvements and tested configuration profiles are welcome. Please read Contributing.md and the profile contribution guide before opening a pull request.

License and acknowledgements

URAAM is distributed under the GNU General Public License v3.0. The bundled UAD-NG catalogue is separately attributed and includes its upstream GPL-3.0 licence information in Configs/uad/.

Package risk metadata is sourced from Universal Debloater Alliance – Next Generation. See the pinned source revision in Configs/uad/source.json.

Thanks to the contributors and community members who report issues, test devices and share configuration profiles.