OpenEUICC: two variants of an open-source Local Profile Assistant, one of them unprivileged

Privileged and unprivileged are two different products

The comparison table at the top of the project summary is the most useful thing in it, because it turns an abstract capability question into a table of what each variant can actually do.

OpenEUICC is the privileged variant. It must be installed as a system app, it supports internal eSIM and external eSIM, it supports USB readers, it does not require allowlisting by the eSIM, it has partial system integration, and it needs Android 11 or higher.

EasyEUICC is the unprivileged variant. It needs no privileged install, it does not support internal eSIM, it supports external eSIM and USB readers, it requires allowlisting by the eSIM except over USB, it has no system integration, and it runs on Android 9 or higher.

Two rows in that table carry the real constraints. The internal eSIM row is the dividing line, and the reason is stated in the FAQ: for EasyEUICC to work, the eSIM chip must proactively grant access via its ARA-M field. A chip that does not volunteer that access is unreachable, which is why internal eSIM support belongs to the privileged variant alone.

The allowlisting row is the other one. An unprivileged install can talk to a chip that grants access, but the eSIM itself has to approve the app first. That is a per-device step the user performs, and it is the reason the project tells removable eSIM chip vendors which ARA-M hash to include.

The two variants also differ in how you get them. Prebuilt release-mode EasyEUICC apks are published on the releases page. For OpenEUICC, no official release is currently provided and only debug mode APKs and Magisk modules can be found in the CI page.

The ARA-M hash is the key that decides what works

The mechanism that makes the unprivileged variant possible is a single 32-character hexadecimal hash, and the project spells it out: removable eSIM chip vendors wanting their chip supported by official builds of EasyEUICC should include the ARA-M hash `2A2FA878BC7C3354C2CF82935A5945A3EDAE4AFA`.

ARA-M is the mechanism by which a chip pre-approves a set of applications. The hash is the list of applications the chip is willing to trust, encoded. The EasyEUICC app is in that list, so a chip with the right hash will let it in without a per-install prompt. A chip without it will not, no matter how the app is installed, which is why the internal eSIM in most phones is out of reach for the unprivileged build and why the privileged system-app variant exists at all.

The project also states the rule for bugs. It asks that you do not submit bug reports for non-functioning removable eSIMs, and explains that they are not officially supported unless they also support or are supported by EasyEUICC, the unprivileged variant. That is a deliberate boundary on the support commitment, and it follows from the same mechanism.

The USB path sidesteps the problem differently. Both variants support accessing eUICC chips through USB CCID readers regardless of whether the chip contains the correct ARA-M hash to allow for unprivileged access. The chip is no longer deciding whether to trust the phone's software, because the reader is the interface. The constraint there is the reader itself: only T=0 readers that use the standard USB CCID protocol are supported.

If you are evaluating this project, the ARA-M hash is the first question to ask about any hardware you have.

Building the two variants is two Gradle tasks

The build instructions are short and assume you are comfortable with the Android build tooling.

Submodules first, because the project depends on code that is not in the tree:

git submodule update --init

Then a keystore. A file `keystore.properties` is required in the root directory, and the template shows four separate credentials plus a path:

storePassword=my-store-password
keyPassword=my-password
keyAlias=my-key
unprivKeyPassword=my-unpriv-password
unprivKeyAlias=my-unpriv-key
storeFile=/path/to/android/keystore

The two alias pairs are there because the two variants are separate applications with separate signing identities, and the note says you must have a Java-compatible keystore generated first.

With that in place, the two build commands are:

./gradlew :app:assembleRelease

for the privileged OpenEUICC, and:

./gradlew :app-unpriv:assembleRelease

for EasyEUICC. The Gradle module names match the directory names in the tree, where `app/` and `app-unpriv/` sit alongside `app-common/` and `app-deps/`, so the shared code and the bundled dependencies are separate modules from the two application modules. There is also `libs/` for the native side, and `buildSrc/` for custom build logic, with `build.gradle.kts` and `settings.gradle.kts` in the Kotlin DSL.

The project is also mirrored from Gitea, where the homepage lives, and the CI artefacts are produced by a Forgejo workflow, with the `.forgejo/` directory at the root. The last push to the repository was on 2026-10-05, so the code is being worked on.

AOSP integration is the path custom ROM builders take

For a device maker or custom ROM developer, the Gradle build is the fallback rather than the goal. The project documents two ways to include OpenEUICC in an AOSP-based system image.

The first is to include the project and its dependencies inside the AOSP tree, with the dependencies hosted in a separate repository, android_prebuilts_openeuicc-deps. If inclusion in `manifest.xml` is required, the option to set is `sync-s`, which clones submodules. The module name is `OpenEUICC`, and it can be added to `PRODUCT_PACKAGES` or built standalone using `mm`.

The second is to build with Gradle and import the apk as a prebuilt, for when compiling against the AOSP source tree is not possible. The project is candid about the two gaps in this path: no official `Android.bp` is provided for it, though writing one should be straightforward, and you might want to include the privapp whitelist file, `privapp_whitelist_im.angry.openeuicc.xml`, which is present at the repository root. That whitelist file is what grants a privileged app the permissions it needs, and the file name encodes the package name.

There is a version caveat that matters for anyone building a ROM for an older release. Compilation of the project is only tested against the latest AOSP release version. The app itself should be compatible with older AOSP versions, but the source may not compile against an older AOSP source tree.

The system integration row in the comparison table is also partial, and the footnote explains why: the Carrier Partner API is unimplemented yet. That is a real functional gap, since a carrier-facing integration is what lets an LPA download profiles from an operator's servers, and without it the app is limited to profiles you already have or that you load by other means.

Prebuilt binaries exist for EasyEUICC and not for OpenEUICC

The FAQ is unusually direct about prebuilt binaries, and the answer differs by variant.

For OpenEUICC, the answer is no. Debug-mode APKs and Magisk modules are available continuously as an artefact of the CI the project uses, but those debug APKs are not intended for inclusion inside system images and are not supported by the developer in any sense. A custom ROM developer is directed to either include the entire repository in the AOSP source tree or generate an APK with Gradle and import that as a prebuilt system app, with the privapp whitelist file as an optional extra.

For EasyEUICC, the answer is yes. Prebuilt release-mode apks are published on the releases page, which is the practical path for a user who just wants the app on a phone.

The distinction is not fussiness. A debug-mode APK signed with a development key and built by CI is not something to put into a shipping system image, where signature consistency with the rest of the image and the privileged permissions whitelist both matter. The project is being explicit so that nobody builds a ROM with it and assumes it is supported.

There is also documentation on the deep link interface, in `docs/DEEP-LINK.md`, which describes how to use the `lpa:` deep link to call OpenEUICC or EasyEUICC from other apps. That is the integration point for a ROM or an automation tool that wants to drive the assistant without going through the UI.

The project also has a stated political position, which explains the shape of the project. It says Google is threatening to lock down the Android platform in 2026, and that OpenEUICC and EasyEUICC, as Free Software projects, will never accept the proposed third-party developer verification flow.

The licence has no or-later clause, and the mirror has a different licence

The licensing is specific and worth reading closely, because it differs from the usual expectation for a GPL project and because this repository is a mirror.

The project states that it is Free Software licensed under GNU GPL v3, WITHOUT the or later clause. Any modification and derivative work must be released under the same licence, which means that at the very least the source code must be available upon request. There is also a request, rather than a requirement, that a modification change at least the app name and package name, which is a courtesy request rather than a licence condition.

The copyright block at the bottom of the summary makes the scope explicit: everything except `libs/lpac-jni` and `art/` is covered by that notice, with copyright 2022 to 2026 for the OpenEUICC contributors. So the native LPA interface library and the ART artwork directory are excluded from that particular block, and their terms have to be checked separately in the tree.

This repository is described as a mirror of OpenEUICC, and the primary homepage given is a Gitea instance rather than a GitHub project page. That matters for provenance: the canonical upstream is PeterCxy's OpenEUICC on Gitea, and the mirror here exists so the code is reachable from another host. For anyone who wants to file an issue or send a patch, the upstream is where the project asks people to go, and where the CI and release pages live.

The GPL-3.0-without-or-later choice is a deliberate one for a project that expects to be modified and shipped in system images, and it is a real constraint on a distributor: a derived build stays under GPL-3.0 and its source has to be offered on request.

Editorial conclusion

OpenEUICC fits a custom ROM builder integrating eSIM management into a system image, a developer who needs to work with eUICC chips over a USB reader, or a user whose device cannot be rooted but whose eSIM chip grants access through its ARA-M field. It is the wrong tool for a stock phone whose internal eSIM does not hand out that grant, because the unprivileged variant cannot touch it. Check three things before you commit: whether your eUICC implements the SGP.22 standard and whether your reader speaks the USB CCID protocol with T=0, since the project supports only that combination, whether you are willing to accept GPL-3.0 without the or-later clause for any modification you publish, and that you have a Java-compatible keystore, because the release build needs one and the template lists separate privileged and unprivileged aliases.

Frequently asked questions

Official sources

1. estkme-group/openeuicc on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README