roamer
v1.3.1About Application
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_STATEpermission 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:
- Roamer calls
IActivityManager.startInstrumentationvia Shizuku withINSTR_FLAG_NO_RESTART. - The instrumentation runs inside Roamer's own process and invokes
startDelegateShellPermissionIdentity(myUid, null). - This delegates shell permissions to Roamer's UID, allowing
overrideConfigto run withMODIFY_PHONE_STATEunder 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:
Release Notes & Changelog
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 falsewhen 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
Declared Android Permissions
4 totalShizuku API Permissions
This application connects to the Shizuku service to execute system-level operations with ADB elevated privileges.
Standard Android Permissions
Specifications
Install via ShizuStore to enable automatic updates and silent installations using Shizuku.
More in Development utilities
Other applications in this category
LibChecker
LibChecker
An app to view libraries used in apps on your device. Uses Shizuku to determine the installation source of other apps.