ArXistant Android app (standalone)
The android/ directory contains an Android app that runs the complete
ArXistant pipeline on the phone: fetching arXiv, ranking with the ML model,
the SQLite paper database, and Nutstore cloud sync. It does not need a remote
server or a desktop Mac.
Download
Prebuilt, signed APKs are attached to each GitHub release. For the latest published release (v0.4.4) the direct download is:
https://github.com/jyshangguan/ArXistant/releases/download/v0.4.4/arxistant-release.v0.4.4.apk
Once an APK is installed, the app can update itself: ⋯ → Check for Updates downloads the newest release APK and opens the installer.
Copy the APK to the phone and open it to install. If a debug build is already installed, uninstall it first (the debug and release builds use different signing keys). Building the APK from source is described under Build.
How it works
The app embeds the existing Python server with Chaquopy, which runs CPython (plus NumPy and scikit-learn) inside the Android process:
[Android app]
├─ ServerService (foreground service)
│ └─ Chaquopy Python runtime
│ └─ arxiv_db_server.run_server() on 127.0.0.1:8765
│ ├─ fetch arXiv (urllib)
│ ├─ ML rank (numpy + scikit-learn)
│ ├─ SQLite paper DB (app-private storage)
│ └─ Nutstore WebDAV sync (periodic auto-sync)
└─ MainActivity
├─ TextToSpeech engine (native voice for the Listen button)
└─ WebView -> http://127.0.0.1:8765/daily.html
The WebView renders the same HTML pages the server already generates, and the
existing save buttons keep working because they POST /api/... to the embedded
server. The ML model is not synced; the phone trains its own model from the
Nutstore-synced saved papers, exactly like a second desktop install.
Mobile interface
Because the desktop pages were written for a wide browser window, the server injects a small mobile layer (CSS + JavaScript) only when it detects an Android WebView. It adds:
- A floating ⋯ menu (top-right) that replaces the desktop navigation bar. It links to Daily/Recent papers, Saved Papers, Notebook, Search, My Publications, ML Features, and Settings (Cloud Sync lives in the Settings page). Tap ⋯ to open it, tap outside to dismiss. A long-press on a menu item shows a tooltip describing what it does.
- Pull-to-refresh on the daily and recent pages: drag down from the top to sync the library and re-fetch the list. A spinner overlay appears while the refresh runs (the page’s own Refresh button is hidden on Android in favor of the gesture).
- Sync-then-refresh: a refresh first pulls the latest saved papers from Nutstore, then regenerates the ranked list, so the phone always reflects changes made on other devices.
- Train-before-refresh: a refresh checks whether the ML model needs updating and trains it first when no model exists yet (fresh install) or a retrain is due, so the phone shows the same relevance scores as the desktop. With no saved papers there is nothing to learn from, so training is skipped.
- Back navigation: the system back button/gesture returns to the previous page instead of leaving the app, and the same works as an edge swipe inside the page (swipe right from the left edge, or swipe left from the right edge).
- Voice digest (🔊 Listen): the Daily and Recent pages’ Listen button
works on the phone too. The WebView has no speechSynthesis, so the app
exposes its native TextToSpeech engine through the
ArxistantAndroidbridge (ttsSpeakspeaks one sentence chunk at a time and reports completion back into the page). The same LLM digests, paper announcements (“Paper N. Title. By author and colleagues.”), pauses, transcript, batch Continue, Pause/Skip/Stop all work — Pause stops the current sentence and Resume re-speaks it, since Android’s engine cannot pause mid-utterance. The Listen panel shows a small voice / rate / papers row that saves to the server (/api/tts/config). If no TTS engine is installed, the panel explains the problem and offers a direct link to the system speech settings plus a retry. - ⚙️ Settings page (⋯ → Settings): the app has no Chrome extension, so
the server renders a settings page (
/settings.html) with the LLM used by Chat and the voice digests (base URL, model, API key, provider presets, connection test), Voice Reading (voice / rate / papers per reading), and Cloud Sync (identical to the desktop’s cloud-sync page). This is how the LLM is configured on the phone — without it, Listen reads the raw titles and abstracts. - Check for Updates (⬆️ in the ⋯ menu): the app compares its version with
the latest GitHub release, offers to download the release APK, verifies
the download (byte count and SHA-256 against the release asset metadata,
retrying once and deleting a suspect file rather than installing it), and
then hands it to the package installer. Android asks once for the “install
unknown apps” permission; after allowing it, the installer opens
automatically. A silent check also runs once at startup and only speaks up
when a newer release exists. Every check logs the parsed release, asset
size, and digest under the
ArxistantUpdatetag, so a failed update can be diagnosed fromadb logcat. - Rate-limited update checks: GitHub’s unauthenticated API allows 60 requests per hour per network address, and answers exhaustion with HTTP 403 — on a phone network that address is shared, so the check can be refused through no fault of the app. The checker recognises the rate limit from the response headers, backs off until the window resets instead of hammering, and still answers the version question through the release page redirect (plain github.com traffic, outside the API budget): an update found that way opens the release page in the browser, since the APK cannot be download-verified without the API’s asset metadata.
The app icon is the ArXistant logo, and MainActivity shows a loading page and
polls the embedded server until it is ready, so the daily list appears as soon
as the server has started.
Python-side changes that make this possible
Three small changes were made to the shared Python code (all backwards compatible with the desktop app):
- In-process tasks —
src/arxistant_tasks.pyruns training, feature-page generation, and daily/recent refresh. On desktop they still run as subprocesses; on Android (ARXISTANT_IN_PROCESS=1) they import the modules and call the functions directly, because Chaquopy cannot spawn Python subprocesses. - Pluggable secret store —
src/arxistant_secrets.pyaccepts a custom backend viaset_backend(...). The Android app supplies a Keystore-backed backend (SecretStore.java) so the Nutstore app password is encrypted, not stored in plaintext. - Configurable bind address —
run_server()honorsARXISTANT_BIND(defaultlocalhost); the Android bootstrap sets it to127.0.0.1. - Native voice bridge — the Listen script injected into the Daily and
Recent pages checks
window.ArxistantAndroid.ttsSpeakat runtime: when present it drives the app’s TextToSpeech engine (same sentence chunking, announcements, and pauses as the desktop’s speechSynthesis path) and offers the inline voice settings row; when absent (older APK, desktop browser) the behavior is unchanged.
Prerequisites
- JDK 17+ (Android Gradle Plugin 8.x requires it):
brew install openjdk@17 - Android SDK (Android Studio, or the command-line tools).
- The Chaquopy Gradle plugin (declared in
android/build.gradle).
Build
cd android
./copy_python.sh # copy ../src/*.py into app/src/main/python/
# Debug APK:
./gradlew :app:assembleDebug
# -> app/build/outputs/apk/debug/app-debug.apk
# Release APK (signed; see "Release build" below):
./gradlew :app:assembleRelease
# -> app/build/outputs/apk/release/arxistant-release.v0.4.5.apk
The first build downloads Chaquopy, NumPy, and scikit-learn wheels for the target ABIs, so it is slow and produces a large APK (scikit-learn is the bulk of it).
Release build
The release APK is signed with a local keystore so it can be installed and updated over the debug build. The signing material is not committed:
android/keystore/release.keystore— the private signing key.android/keystore.properties— the store path, passwords, and key alias.
Both are listed in android/.gitignore. To create them from scratch:
cd android
mkdir -p keystore
keytool -genkeypair -v \
-keystore keystore/release.keystore \
-alias arxistant \
-keyalg RSA -keysize 2048 -validity 10000 \
-storepass <store-password> -keypass <key-password> \
-dname "CN=ArXistant, OU=Personal, O=ArXistant, C=CN"
then write keystore.properties:
storeFile=keystore/release.keystore
storePassword=<store-password>
keyAlias=arxistant
keyPassword=<key-password>
app/build.gradle reads keystore.properties when present and applies it to
the release build type. Keep a backup of both files; without the same key you
cannot push an update over an existing install. The current Android version is
v0.4.7 (versionName "0.4.7", versionCode 15 in app/build.gradle);
bump both whenever you publish a new release so the in-app update check can
detect it.
CI builds (GitHub Actions)
The Build release assets workflow builds the signed APK automatically when a
release is published — no local Android SDK needed. It requires four
repository secrets (Settings → Secrets and variables → Actions), created
from the local keystore:
| Secret | Value |
|---|---|
ARXISTANT_KEYSTORE_BASE64 |
base64 -i android/keystore/release.keystore (macOS) |
ARXISTANT_KEYSTORE_PASSWORD |
the store password from keystore.properties |
ARXISTANT_KEY_ALIAS |
the key alias (arxistant if generated as above) |
ARXISTANT_KEY_PASSWORD |
the key password from keystore.properties |
If the secrets are missing, the workflow still builds the Debian package and the Chrome extension zip and simply skips the APK (an unsigned APK cannot be installed, so none is uploaded). To add the APK to an already-published release after configuring the secrets, run the workflow manually with the existing tag.
Install and run
- Phone: install the release APK
(
app/build/outputs/apk/release/arxistant-release.v0.4.5.apk) or the debug APK (app/build/outputs/apk/debug/app-debug.apk) and launch it. The daily page appears in the WebView after the server starts. - Emulator: use an arm64 system image on Apple Silicon. The
x86_64ABI filter is included so x86_64 emulators also work.
Nutstore sync on the phone
Cloud sync is configured exactly as on desktop: open the ⋯ menu and choose Cloud Sync (or ☁️ Cloud Sync), select Nutstore WebDAV (坚果云), enter your email and the 第三方应用密码, and click Connect. The app password is stored encrypted via the Keystore backend.
Once connected, the phone syncs automatically every 30 minutes (the default
interval_minutes), and also syncs before every manual refresh. Syncing uses
the same last-write-wins versioned snapshot as desktop — saved papers,
publications, custom keywords, and the Notebook’s folders and notes — so the
phone and your Mac stay in step, reading list included.
Current limitations (to be aware of)
- No Chat page. The reader/chat interface is desktop-oriented and is stripped from the Android build; the chat API endpoints stay in place, so libraries and highlights still merge cleanly with the desktop.
- No manuscript review assistant. The Chat-page manuscript workspace
(PDF review findings, proposals, and the review skills) is desktop-only:
it needs the Chat page, PyMuPDF, and the
src/skills+src/assetsdirectories, none of which ship in the APK.copy_python.shskips its Python modules andstrip_chat.pyremoves its endpoints from the server. - No browsing panel. The “add to ArXistant” panel that appears on arxiv.org and scixplorer.org paper pages is a Chrome-extension content script. The phone has no extension, and ArXistant’s own WebView is not a general browser, so there is nothing to inject it into. Save, tag, and chat from the Daily, Recent, Search, and Saved Papers pages instead — the tag editor there is the same one.
- No browser tab icons. The favicon assets the desktop server injects
into every page are not bundled; the phone uses the app’s native launcher
icon, so the favicon routes and
<link>injection are stripped too. - No daily reminders yet. The desktop Chrome extension’s alarm/notification
logic has no Android equivalent. A
WorkManagerjob that calls/api/refresh-dailyand posts a notification is the intended follow-up. - The server is single-threaded. A long daily refresh blocks other requests while it runs (same behavior as the desktop server during a refresh).
- First launch generates the daily page by fetching arXiv, which needs a network connection and takes a few seconds.
- Secret store requires an Android Keystore key; the
SecretStore.javabackend uses AES/GCM with the key held in the Keystore.