ShizuStore

Roamer

eigenlux-ai

1.3.1 · GitHub

Download APK
Development utilities Android 12+ 1 month ago MIT
483 ShizuStore
1.6k GitHub
60 Stars
23 MB Size

More about this app

Developer tool overriding SIM country ISO and carrier name via Shizuku, with optional per-app locale syncing.

Roamer

Roamer is an Android developer tool for overriding a SIM card's reported home country (ISO) and carrier name without requiring root access. It also allows optionally syncing the overridden region to target applications via per-app locales.

English · 简体中文

Stack: Kotlin · Jetpack Compose · Shizuku · Haze · minSdk 31 (Android 12+)

Overview

Roamer modifies the CarrierConfig override layer exposed by Android telephony APIs via Shizuku. This lets developers test how apps respond to different SIM country ISOs and carrier names without swapping physical SIM cards.

Optionally, Roamer can mirror the primary SIM's overridden country code to selected apps using system per-app locales (Android 13+). Restoring the SIM automatically resets selected apps back to their original locales.

Features

  • Rootless SIM country ISO and carrier name override via Shizuku.
  • Multi-SIM support: apply or restore settings across all active slots. Quick switch moves every SIM to one region and restores a SIM whose real country is that region.
  • Configurable regions and carriers: every ISO 3166-1 country and region is built in with a preset carrier list. In Settings you choose which regions appear in the menu and in what order, turn preset carriers on or off, add custom regions and carriers, and pick the regions for the quick-switch row. Edits take effect when saved, and the configuration can be exported, imported, and reset to defaults.
  • Sourced carrier data: preset carriers are ordered by subscriber count. Sources and the verification status of each market are in docs/CARRIER_DATA.md; the order is still unverified for some markets.
  • Reversible restore: values are derived dynamically at runtime rather than saved to disk.
  • Force clear: writes back the real values and clears every SIM's override layer, for SIMs that restore cannot target.
  • Failure reasons from the privileged run are reported in the in-app log, per SIM. A failed entry also shows the app version, Android release, device brand, Android user, and Shizuku identity, and can be copied for a bug report.
  • Optional per-app region override for targeted app testing.
  • UI details: a Liquid Glass interface with side-by-side original vs. active values, monospace technical codes (MCC/MNC/ISO/subId), and light/dark themes.

Scope of Overrides

Roamer only edits the CarrierConfig override layer and does not alter underlying SIM or RIL hardware attributes.

Target Value Overridable Telephony API
Country ISO Yes getSimCountryIso
Carrier Name Yes getSimOperatorName
MCC / MNC Digits No getSimOperator (SELinux protected)
Network Registration No getNetworkOperator / getNetworkCountryIso

Because MNC and network values are read-only, Roamer does not modify actual phone numbers or cell tower registration. Whether an app detects the override depends on which Telephony or Location APIs it queries.

Requirements

  • Android 12+ (minSdk 31). Tested on Android 16 and 17 (Samsung).
  • Shizuku running via Wireless Debugging or ADB.
  • READ_PHONE_STATE permission granted on first launch to enumerate active SIM slots.
  • Per-app region override features require Android 13+ (System per-app locale API).

Technical Implementation

Privilege Escalation

Calling overrideConfig directly via Shizuku can fail on OEMs like Samsung because OEM security checks reject shell callers (getCallingUid() == SHELL).

To bypass this restriction without root:

  1. Roamer calls IActivityManager.startInstrumentation via Shizuku with INSTR_FLAG_NO_RESTART.
  2. The instrumentation runs inside Roamer's own process and invokes startDelegateShellPermissionIdentity(myUid, null).
  3. This delegates shell permissions to Roamer's UID, allowing overrideConfig to run with MODIFY_PHONE_STATE under Roamer's caller identity rather than SHELL.

Baseline-Free Restore

Roamer does not persist pre-override snapshots. When restoring:

  • The real country ISO is calculated from the immutable MCC (getSimOperator). The restore operation writes back the real ISO first to update the subscription database, then clears the override layer (overrideConfig(null)).
  • Clearing the override layer does not reliably revert the carrier name (a SIM can keep reporting the overridden name), so restore also writes back the carrier-ID name (getSimCarrierIdName) before clearing.

Force Clear

Restore only targets SIMs detected as overridden, which is decided by comparing the MCC-derived ISO with the effective one. Force clear runs the same write-back on every SIM and then clears the override layer unconditionally, even when the write-back has not settled.

Result Reporting

The instrumentation runs inside the app process, so it hands its outcome (overall error and per-SIM failures) back in memory. A failed run is reported immediately with its real cause; telephony state is polled only for SIMs the run did not report as failed.

Reflection & Hidden APIs

All hidden API accesses use HiddenApiBypass, avoiding compile-time hidden API stubs.

Building

export JAVA_HOME=/path/to/jdk-21
./gradlew :app:assembleDebug        # Build debug APK
./gradlew :app:testDebugUnitTest    # Run JVM unit tests

Debug builds use the application ID com.eigenlux.roamer.debug, so they install next to a release build and need their own Shizuku authorization. CI runs the unit tests and a debug build on every push to main and on pull requests.

Project Structure

com.eigenlux.roamer/
├── core/   # Telephony APIs, Shizuku bindings, and instrumentation logic
│   ├── ShizukuManager
│   ├── SystemServices
│   ├── CarrierConfigController
│   ├── InstrumentationTrigger
│   ├── PrivilegedOverrideInstrumentation
│   ├── PrivilegedSubscriptionReader
│   ├── RegionLogic
│   ├── Diagnostics
│   └── LocaleOverrideController
├── data/   # Region/carrier presets and local app state storage
├── ui/     # Glass material, shared controls, and theme
├── MainActivity.kt
├── MainViewModel.kt
├── SettingsScreen.kt
└── AppPickerScreen.kt

Internationalization

UI text is defined in res/values (English, the default) and res/values-zh (Chinese). Chinese is the source copy; the English strings are translated from it. A JVM unit test (StringsParityTest) checks string key parity across translation files. Layout rules for the longer English copy are in docs/DESIGN.md.

Limitations

  • Privilege delegation was designed around Samsung's shell UID restrictions on Android 12-16. Other OEM implementations are supported on a best-effort basis.
  • After a restore, the carrier name is the carrier-ID name, which can differ from the name the SIM reported before the override.
  • If a SIM loses connection (e.g., airplane mode) during operation, telephony state updates may lag behind UI confirmation.

License

MIT License. See LICENSE for details.

Acknowledgements

Inspired by earlier Shizuku-based carrier override tools:

Close

How Shizuku is used

Can spoof SIM country and carrier, restore originals and sync app languages via `Shizuku`.

This is an AI-assisted analysis of Shizuku-related usages in the app's public source code. It is best effort, so it may not catch every single usage.

How this app uses Shizuku

Roamer uses Shizuku to present a different mobile country, carrier name and app language than the inserted SIMs provide.

  • Spoof SIM country and carrier: choose a country code and carrier name for one SIM, or apply one country to all SIMs at once, applied as a carrier settings override through Shizuku.
  • Restore original network info: restore one SIM or all overridden SIMs at once, writing back the real country derived from the SIM and clearing the custom carrier name through Shizuku, with a force clear that removes the override layer from every SIM.
  • Show SIM identifiers: display each SIM slot with its subscription and card identifiers, reading the normally hidden card identifier through Shizuku when available.
  • Sync app languages: enroll installed apps to follow the primary SIM country language and toggle the follow switch, reading and setting each selected app language through Shizuku, with the original language restored when unenrolled or switched off.

Android APIs or commands used

  • IActivityManager.startInstrumentation
  • IActivityManager.startDelegateShellPermissionIdentity
  • IActivityManager.stopDelegateShellPermissionIdentity
  • CarrierConfigManager.overrideConfig
  • ICarrierConfigLoader.notifyConfigChangedForSubId
  • ISub.getActiveSubscriptionInfoList
  • ILocaleManager.getApplicationLocales
  • ILocaleManager.setApplicationLocales

Notable details

Overrides try persistent mode first where the system allows it, otherwise they last until reboot. All override, restore, card identifier and app language actions require Shizuku, with no alternate privileged path in the current source.

Close

Changelog

What's new for version 1.3.1

Fixes

  • Override in a secondary user: the privileged run was always started in Android user 0. The system looks up the instrumentation in the user it is given and answers startInstrumentation returned false when Roamer is not installed there, so an install in a work profile, an app clone, a Secure Folder, or a second user could never override. Roamer now starts the run in the user it is installed in. Reported in #2.

Log

  • A failed or partially successful entry in the Log section now shows the environment it happened in: Roamer version, Android release, device brand, Android user, and Shizuku identity.
  • Copy under the entry puts the whole report on the clipboard, ready to paste into an issue.

Notes

  • Verified on a Samsung device running Android 17, in the primary user, in Chinese and English with the light theme.
  • The fix was not tested in a work profile, an app clone, or a second user, and the new log layout was not checked in the dark theme.

Full changelog: https://github.com/eigenlux-ai/roamer/compare/v1.3.0...v1.3.1

Close

Permissions

4 permissions requested

  • android.permission.READ_PHONE_STATE
  • android.permission.QUERY_ALL_PACKAGES
  • com.eigenlux.roamer.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION
  • moe.shizuku.manager.permission.API_V23
Close