Aegion on a desktop

Aegion on a desktop: Linux, macOS and Windows

Aegion is the same Kivy app on every platform: mobile/main.py. On a desktop it opens in a phone-shaped window that you can resize (the size is remembered). Nothing is built or installed system-wide; it runs from this folder with a Python virtual environment.

What each desktop gets

Feature	Linux (this laptop)	macOS	Windows
Ask, Library, Tutorials, Markets, Shield of Zeus, Handshake	yes	yes	yes
Weather, exchange rates, city times (needs internet)	yes	yes	yes
Read-aloud	Kokoro when the laptop backend runs, else espeak / spd-say	`say`	PowerShell System.Speech
Voice questions and the Artemis wake word	the laptop's Vosk worker (`arecord`)	no (type instead)	no (type instead)
Laptop tab, laptop engine answers	local backend on 127.0.0.1:8000	over the LAN with a pairing code	over the LAN with a pairing code
Signal Walk viewer and full map	yes (Pull from phone needs `adb`)	yes	yes
Guardian scan (Shield screen)	yes (`/proc`)	hidden	hidden
SignalDub Studio card	when `~/signal-dub` is installed	same	same
Background learning with the app closed	no (Android only)	no	no

On this Linux laptop

Use the launcher: Aegion in the app menu (~/.local/share/applications/aegis-terminal.desktop), or ./aegis in the repo root. It reuses the backend on port 8000, starts the Artemis worker and Kokoro when they are installed, and opens the app. ./aegis --classic still opens the old GTK window for one more release. mobile/run-desktop.sh opens the app alone.

macOS (from source)

# Python 3.11 or 3.12 from python.org or Homebrew (brew install python@3.12)
git clone <this repo> Aegis-Terminal        # or copy the mobile/ folder
cd Aegis-Terminal/mobile
python3.12 -m venv .venv && source .venv/bin/activate
pip install "kivy[base]==2.3.1" plyer certifi
python main.py

Windows (from source)

# Python 3.12 from python.org (tick "Add python.exe to PATH")
cd Aegis-Terminal\mobile
py -3.12 -m venv .venv
.venv\Scripts\activate
pip install "kivy[base]==2.3.1" plyer certifi
python main.py

Use the native Windows Python, not WSL: Kivy needs a real window. If the window stays black, update the graphics driver or run set KIVY_GL_BACKEND=angle_sdl2 before python main.py.

The knowledge pack

The app answers offline from mobile/assets/aegis-pack.sqlite (git-ignored, a few MB). Copy it from the laptop, or build it there with the backend stopped:

fuser -k 8000/tcp; .venv/bin/python mobile/export_mobile_pack.py; systemctl --user start aegis-backend

Or start without it, set the laptop link (below) and press Sync now: the app downloads a fresh pack into its data folder.

Link to the Aegis laptop (macOS, Windows, phones)

On the laptop, let the backend listen on the network. Its systemd unit pins --host 127.0.0.1, so run systemctl --user edit --full aegis-backend, change that to --host 0.0.0.0 (or start uvicorn by hand with AEGIS_HOST=0.0.0.0), then systemctl --user restart aegis-backend and check curl --noproxy '*' http://127.0.0.1:8000/health. Every request from another computer needs the pairing code; only /health is open.
Open the laptop's Handshake page, Settings > Phone link (Aegis app), and note the code.
In Aegion: Settings > LAPTOP LINK, the laptop's address (192.168.x.x:8000) and the code, then Sync now. That swaps teachings both ways, downloads a fresh knowledge pack and the Signal Walk log, and lets the laptop engine answer what the offline library can't.

Where the app keeps its data

Kivy picks the folder from the app class name (AegisMobile), so it stays the same across the rename to Aegion: ~/.config/aegismobile on Linux, ~/Library/Application Support/aegismobile on macOS and %APPDATA%\aegismobile on Windows. The log is aegis-log.txt there (Settings > Logs shows it).

Compiled 5 October 2026 from the Aegis-Terminal repo on this laptop. Living copies of the long documents stay in the git tree. Upload this whole overview folder to chief.