Install CIRCE

Last updated: 14 May 2026  ·  bundle ID io.sp5.circe

1. Android

1a. Signed APK sideload (GitHub Releases)

Each tagged release publishes a signed .apk as a GitHub release asset. Releases are tagged android-vX.Y.Z (matches the versionName + versionCode baked into the APK).

1. Open github.com/subinacls/CIRCE/releases on your phone.
2. Find the latest release whose tag starts with android-v.
3. Download circe-android-vX.Y.Z.apk (and the matching .apk.sha256 file — see §3).
4. Tap the APK in your downloads. Android will prompt: "For your security, your phone is not allowed to install unknown apps from this source." Tap Settings → enable Allow from this source for your browser → back out → tap the APK again → Install.
5. Recommended: after install, go back to Settings and disable "Allow from this source" again. The app is already installed; you don't need it on for updates (you'll re-download the next APK manually anyway).

Signing key. APKs are signed with the CIRCE Android release key. You can pin the certificate fingerprint and verify every future APK against it:

$ apksigner verify --print-certs circe-android-vX.Y.Z.apk
Signer #1 certificate SHA-256 digest: (published in the GitHub release notes)
Signer #1 certificate SHA-1   digest: (published in the GitHub release notes)

The first release pins the fingerprint; every subsequent release MUST show the same SHA-256. If it ever differs, do not install — open an issue.

1b. F-Droid reproducible build

CIRCE ships an fdroid/ metadata folder (fastlane/metadata/android/en-US/) so the F-Droid project can build CIRCE from public source on F-Droid's own infrastructure with reproducible-build verification. Once accepted upstream, install via the official F-Droid client:

1. Install F-Droid from f-droid.org.
2. Search for CIRCE (package io.sp5.circe).
3. Tap install. F-Droid auto-updates from its own signing key.

The F-Droid build does not include any proprietary Google services (no Firebase, no FCM, no Play Services dependency). Push notifications under F-Droid use the relay's web-push endpoint via UnifiedPush if available, or fall back to long-poll while the app is foregrounded.

1c. Google Play Internal Testing

For users who prefer the Play Store update path, CIRCE is available on the Play Internal Testing track. You need an opt-in invitation link (open an issue or contact the maintainer). The Play build is bit-for-bit identical to the F-Droid build except for the signing key — Play Store re-signs every upload with their own key.

1d. Build it yourself

git clone https://github.com/subinacls/CIRCE.git
cd CIRCE
git checkout mobile/android
npm ci --legacy-peer-deps
npm -w packages/client run build -- --mode mobile
npx cap sync android
cd android
./gradlew assembleRelease
# APK at: app/build/outputs/apk/release/app-release-unsigned.apk
# Sign it yourself with apksigner, or use assembleDebug for a self-signed debug build.

2. iOS

2a. TestFlight

iOS builds are distributed via Apple TestFlight. Apple does not permit sideloading on iOS without enrolling the device in a paid Developer Program ($99/yr) or using third-party signing services that violate Apple's terms — so TestFlight is the only practical path for end users.

1. Install TestFlight from the App Store.
2. Open the public TestFlight invite link from the GitHub release notes (look for tags starting with ios-v).
3. Tap Accept → Install.
4. Updates roll out automatically through TestFlight.

TestFlight builds expire 90 days after upload — if your build stops launching, check for a newer one in the GitHub releases.

2b. Build it yourself

Requires a macOS host with Xcode 15+ and an Apple Developer account (free tier works for personal sideload via Xcode → Devices, paid for distribution).

git clone https://github.com/subinacls/CIRCE.git
cd CIRCE
git checkout mobile/ios
npm ci --legacy-peer-deps
npm -w packages/client run build -- --mode mobile
npx cap add ios
cd ios/App && pod install --repo-update && cd ../..
open ios/App/App.xcworkspace
# In Xcode: select your team in Signing & Capabilities, plug in your
# device, Cmd-R to install.

3. Verify a download

Every release publishes:

• circe-android-vX.Y.Z.apk — the installable
• circe-android-vX.Y.Z.apk.sha256 — SHA-256 hex digest
• circe-android-vX.Y.Z.apk.sig — minisign signature (see the maintainer's public key in scripts/generate-release-key.mjs's sibling file)

To verify on Linux / macOS:

sha256sum -c circe-android-vX.Y.Z.apk.sha256
# circe-android-vX.Y.Z.apk: OK

# (optional, requires `minisign` from your package manager)
minisign -V -p circe-release.pub -m circe-android-vX.Y.Z.apk

To verify on Windows (PowerShell):

(Get-FileHash circe-android-vX.Y.Z.apk -Algorithm SHA256).Hash.ToLower()
# Compare against the contents of circe-android-vX.Y.Z.apk.sha256

4. Permissions reference

CIRCE never requests location, contacts, SMS, call log, calendar, or storage-wide access. See the privacy policy for the full data-handling commitment.