Installing ArXistant
ArXistant has two cooperating parts:
- A local Python server that fetches, ranks, and stores papers.
- A Chrome extension that opens the interface, schedules reminders, and asks the server to refresh papers.
The extension cannot perform ranking by itself. The local server must be
running at http://localhost:8765.
On Android, a standalone app bundles both parts and needs no desktop install or Chrome extension — see Android.
Choose an installation method
| Platform | Recommended method | Server startup |
|---|---|---|
| macOS | Repository checkout and bundled helper app | Extension button or start_server.sh |
| Debian/Ubuntu | Build and install the .deb package |
systemd user service |
| Other Linux | Manual Python setup | Terminal or your service manager |
| Windows | Manual Python setup | PowerShell |
| Android | Standalone app (APK from GitHub Releases) | Runs on the phone (built-in) |
Python 3.8 or newer is required for a manual installation.
macOS
1. Download the project and dependencies
git clone https://github.com/jyshangguan/ArXistant.git
cd ArXistant
python3 -m pip install --user -r requirements.txt
If the server was already running when dependencies were installed, restart it
with ./start_server.sh. The manuscript workspace needs PyMuPDF in the same
Python interpreter used by the server. To verify the default macOS interpreter:
/usr/bin/python3 -c "import pymupdf; print(pymupdf.VersionBind)"
The launcher discovers the repository location automatically, so the checkout does not need to be in a particular directory.
2. Load the Chrome extension
- Open
chrome://extensions/. - Enable Developer mode.
- Click Load unpacked.
- Select the
chrome-extensiondirectory inside the repository. - Optionally pin the red ArXistant icon to Chrome’s toolbar.
Select the directory containing manifest.json, not the repository root:
ArXistant/
└── chrome-extension/ ← select this directory
├── manifest.json
├── popup.html
└── background.js
3. Register the server helper
Double-click:
chrome-extension/ArXistantServer.app
If macOS blocks it, open System Settings → Privacy & Security and choose
Open Anyway. The first time the extension opens arxistant://start, allow
Chrome to use ArXistantServer. The helper has no Dock window; it starts the
server in the background.
You can also start the server directly:
/bin/bash start_server.sh
Logs are written to local/server.log.
Debian and Ubuntu package
The package installs the server, a systemd user service, and a copy of the Chrome extension. It currently uses Debian’s Python, NumPy, and scikit-learn packages.
1. Build and install
From a repository checkout:
./packaging/linux/build-deb.sh
sudo apt install ./dist/arxistant_0.4.5_all.deb
The dependency installation is relatively large because Debian’s scientific Python packages pull in SciPy and supporting native libraries.
To build the package on a non-Debian host with Docker:
docker run --rm -v "$PWD:/work" -w /work debian:bookworm-slim \
sh -c 'apt-get update && apt-get install -y dpkg-dev && ./packaging/linux/build-deb.sh'
2. Start the service
systemctl --user daemon-reload
systemctl --user enable --now arxistant.service
It starts automatically on subsequent logins. Check its state and logs with:
systemctl --user status arxistant.service
journalctl --user -u arxistant.service
3. Load the extension
Open chrome://extensions/, enable Developer mode, choose Load unpacked,
and select:
/usr/share/arxistant/chrome-extension
The Linux popup’s footer power button (shown as Start Server when offline)
starts the server via Chrome Native Messaging (com.arxistant.server). The
popup also shows the equivalent systemctl --user restart arxistant.service
command, which is the fallback when the native messaging host is not installed
(for example on a manual installation).
The same button reads Stop Server when online. It stops the running server
process; because the systemd user unit is enabled, the service will start again
at the next login unless it is explicitly disabled with
systemctl --user disable arxistant.service.
Linux data location
The package stores writable data in:
~/.local/share/arxistant
If XDG_DATA_HOME is available to the service, it uses
$XDG_DATA_HOME/arxistant instead. Package upgrades do not remove this data.
Remove the Linux package
systemctl --user disable --now arxistant.service
sudo apt remove arxistant
Delete the data directory separately only if you also want to erase your paper database, model, configuration, and generated pages.
Windows and other manual installations
Clone the project and install its dependencies:
git clone https://github.com/jyshangguan/ArXistant.git
Set-Location ArXistant
py -m pip install --user -r requirements.txt
Generate a daily page and start the server:
py src\arxiv_daily_ranker_html.py --output local\arxiv_ranked_personalized.html
py src\arxiv_db_server.py
Keep the PowerShell window open while using ArXistant. Load the repository’s
chrome-extension directory through chrome://extensions as described above.
The popup’s Start Server button has no effect on Windows — start the server
manually as shown above.
Equivalent commands on an unpackaged Linux installation are:
python3 -m pip install --user -r requirements.txt
python3 src/arxiv_daily_ranker_html.py \
--output local/arxiv_ranked_personalized.html
python3 src/arxiv_db_server.py
Android (standalone app)
The Android app is self-contained: it runs the server, ML ranking, paper database, and cloud sync on the phone, so it needs no desktop install and no Chrome extension.
- Download
arxistant-release.v0.4.4.apkfrom the latest GitHub release. - Copy the APK to the phone and open it. Android asks you to allow “install unknown apps” for the file manager or browser you used.
- Launch ArXistant. The daily list appears once the embedded server has fetched arXiv (a few seconds on first launch).
- To share your library across devices, open the ⋯ menu → Cloud Sync and connect Nutstore as described in Cloud sync.
If you previously installed a debug build, uninstall it first: the debug and release builds use different signing keys, so they cannot be upgraded in place. Building the APK from source is covered in the Android app guide.
ADS API token
An ADS token is optional. Daily arXiv ranking and the saved-paper database work without one. SciX publication import, ADS search, and the ArXistant panel on scixplorer.org require a token from the NASA ADS API settings.
The easiest way to set it: open the extension’s Settings page, expand the ADS / SciX section, paste the token, and click Save Token — it is verified against SciX immediately. Alternatively, save it manually.
For a repository installation, save it as:
local/ads_token.txt
For the Debian package, save it as:
~/.local/share/arxistant/ads_token.txt
The file should contain only the token.
Chat LLM (optional)
The Chat page needs an OpenAI-compatible LLM (OpenAI, DeepSeek, OpenRouter, Moonshot, Zhipu, or a local Ollama). Nothing else requires one. After the extension is loaded, open its Settings page, expand the LLM (Chat) section, and save a base URL, model, and API key — see Configure an LLM in the user guide. The key is kept in ArXistant’s data directory with owner-only file permissions (plus a best-effort keychain copy), never inside the repository.
Cloud sync (optional)
ArXistant can mirror your paper database to Nutstore so several devices share
the same library. It uses the keyring package (already in requirements.txt)
to store the Nutstore app password in the operating-system keychain rather than
on disk. See the user guide for the step-by-step WebDAV setup.
On Linux, keyring uses the freedesktop Secret Service, so a provider such as
gnome-keyring (or KWallet with a Secret Service bridge) must be installed and
unlocked for the app password to be stored. The Debian package depends on
python3-keyring; install gnome-keyring for the Secret Service itself.
Migrating existing data
Stop the old and new servers before copying data. Copy the contents of the old
local/ directory into the new data directory. Important files include:
arxiv_papers.db— saved papers and publications.ml_ranker/— trained model and custom keywords.ads_token.txtandscix_config.json— ADS/SciX configuration.- Generated daily, recent, and ML feature pages.
Never run two ArXistant servers against the same SQLite database concurrently.
Updating
For a repository installation:
git pull
python3 -m pip install --user -r requirements.txt
Restart the server and click Reload for ArXistant on
chrome://extensions. For Debian/Ubuntu, build the new package and install it
with apt over the existing version, then restart the user service.
Installation troubleshooting
Chrome reports that the server is offline
Open http://localhost:8765/api/health. A
running server returns JSON containing "success": true, the api_version the
extension requires, and the release version the process was started from.
- macOS: inspect
local/server.logand run/bin/bash start_server.sh. - Linux package: run
systemctl --user status arxistant.serviceand inspectjournalctl --user -u arxistant.service. - Manual setup: look for the traceback in the terminal running the server.
The app or extension is missing a feature you just upgraded to
A server started before the upgrade keeps running the old code — new pages and
new behaviour appear only after it restarts. Compare the version in
/api/health with the checkout, then run /bin/bash start_server.sh: the
launcher treats a process left over from another release as stale and replaces
it. (A process whose version differs but that the launcher does not recognise
as this checkout’s own is never killed; stop that one yourself.) This also
applies to behaviour that has no new endpoint to announce it — notebook cloud
sync, for example, changed how the existing /api/cloud/sync carries data.
NumPy architecture errors on Apple Silicon
If training, feature-page regeneration, or the daily refresh fails with an
ImportError mentioning “incompatible architecture (have ‘arm64’, need
‘x86_64’)”, the server is running as x86_64 while NumPy is arm64. Run
/bin/bash start_server.sh: a server left over from an older checkout announces
a different release version and is replaced. The launcher explicitly starts
ARM64 Python, and ArXistant now also forces its worker subprocesses to ARM64 so
they match the installed NumPy wheels.
Port 8765 is already in use
Only one server can listen on the default port. Stop the older ArXistant process or identify the other program using the port before restarting.
Notifications do not appear
Use Extension Settings → Test Notification. Also verify that Chrome has notification permission in the operating system and that Focus/Do Not Disturb is not suppressing banners.