Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

docs(packaging): macOS and Linux packaging guides

rubenluetke10-beep84ea2aa0fa64
diff --git a/packaging/linux/README.md b/packaging/linux/README.md
new file mode 100644
index 0000000000..7866bacba5
--- /dev/null
+++ b/packaging/linux/README.md
@@ -0,0 +1,150 @@
+# Linux packaging — AppImage and Debian package
+
+`packaging/linux/build.sh` turns this repository into two downloadable files:
+
+| Artifact | Path | What it is |
+|---|---|---|
+| `PersonalJarvis-Linux-x86_64.AppImage` | `dist/installers/` | One executable file. No Python, no pip, no root. Download, `chmod +x`, run. |
+| `personal-jarvis_<version>_amd64.deb` | `dist/installers/` | The same tree as a normal Debian package: `apt install ./personal-jarvis_*.deb` registers the app in the menu and puts `jarvis` on `PATH`. Built only when `dpkg-deb` is present. |
+
+Both are produced from one PyInstaller `onedir` freeze and one AppDir, so a bug
+can only exist in both or in neither.
+
+## Building
+
+```bash
+# on a Linux x86_64 machine or an ubuntu-22.04 runner
+python -m pip install -e ".[full]" # or ".[desktop]" for a smaller build
+python -m pip install pyinstaller
+bash packaging/linux/build.sh
+```
+
+The script builds the web bundle first when `jarvis/ui/web/dist` is missing
+(needs `npm`), freezes the app, assembles the AppDir, downloads a
+**pinned** `appimagetool` (version and SHA-256 are in the script; a digest
+mismatch aborts the build), and prints the artifact paths on the last lines.
+
+Useful switches: `DRY_RUN=1` prints every command without running it,
+`SKIP_PYINSTALLER=1` reuses an existing freeze in `FREEZE_DIR`, `BUILD_DEB=0`
+skips the Debian package, `APPIMAGETOOL=/path/to/tool` uses a local build tool.
+
+## The window question — read this before "fixing" it
+
+**The AppImage has no native desktop window. It serves the interface over
+loopback HTTP and opens it in the user's default browser.** That is a decision,
+not a bug, and here is the whole reasoning:
+
+* pywebview needs a *native* backend. On Linux that is GTK 3 + WebKit2GTK
+ through PyGObject, or Qt through QtWebEngine.
+* **The system's PyGObject cannot be used.** `python3-gi` is a compiled
+ extension built against the distribution's own CPython. A PyInstaller bundle
+ ships its own interpreter, so `import gi` inside the frozen app can never
+ resolve to the system package no matter which system packages are installed.
+ Telling users to `apt install gir1.2-webkit2-4.1` does not help this build.
+* **Bundling GTK + WebKit2GTK is not a small change.** WebKitGTK is not one
+ library: it needs its `WebKitNetworkProcess` / `WebKitWebProcess` helper
+ binaries at the paths it was compiled for, plus GIO modules, GdkPixbuf
+ loaders, GSettings schemas and typelibs. Freezing that stack portably is a
+ project of its own, and it breaks in ways that only show up on other people's
+ distributions - the exact failure mode this project treats as a defect.
+* **Qt is not available either, today.** The `[desktop]` extra installs
+ `pyside6-essentials`, which does *not* contain QtWebEngine; pywebview's Qt
+ backend needs `QtWebEngineWidgets` from `pyside6-addons`. `jarvis.spec` also
+ excludes PySide6 outright to keep the bundle small. Adding `pyside6-addons`
+ and removing that exclusion is the realistic route to a native Linux window,
+ at roughly +400 MB - a trade worth making deliberately, not by accident.
+
+So the app degrades, and it really does degrade: `jarvis/ui/desktop_app.py`
+catches pywebview's `WebViewException`, keeps the already-running backend
+serving, and prints where the interface is. Verified in a container against a
+real build:
+
+```
+Native desktop window unavailable: You must have either QT or GTK with Python
+extensions installed in order to use pywebview.
+Browser-UI fallback: UI stays reachable at http://127.0.0.1:47821
+```
+
+A double-clicked AppImage has no terminal to read that message in, so `AppRun`
+closes the gap: with no arguments and a graphical session it waits for
+`/api/health` to answer and then opens the address with `xdg-open` (falling
+back through `gio`, `x-www-browser`, `sensible-browser`, and the common browser
+binaries). It never opens a tab it has not confirmed first, and it stops
+waiting as soon as the app exits. `JARVIS_APPIMAGE_NO_BROWSER=1` turns it off.
+
+Whether to do this at all is decided at build time, not guessed: `build.sh`
+inspects the freeze for PyGObject and writes
+`usr/share/personal-jarvis/browser-ui` only when there is no window backend. A
+future build that does bundle one stops opening the browser tab by itself.
+
+**One rough edge, stated plainly:** the app's own fallback message suggests
+installing `python3-gi` / `gir1.2-webkit2-4.1`. For a frozen build that advice
+does not apply (see above). It lives in `jarvis/ui/desktop_app.py`
+(`_degrade_to_browser_ui`), which is where a frozen-aware wording belongs.
+
+## Using it as the CLI
+
+`AppRun` passes every argument straight through, so the AppImage *is* the
+command-line tool:
+
+```bash
+chmod +x PersonalJarvis-Linux-x86_64.AppImage
+./PersonalJarvis-Linux-x86_64.AppImage --version
+./PersonalJarvis-Linux-x86_64.AppImage serve # headless API + browser UI
+./PersonalJarvis-Linux-x86_64.AppImage --doctor
+```
+
+To type `jarvis` instead, link it once:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf "$PWD/PersonalJarvis-Linux-x86_64.AppImage" ~/.local/bin/jarvis
+```
+
+The Debian package does this for you: it installs `/usr/bin/jarvis` (the
+console entry) and `/usr/bin/personal-jarvis` (the launcher).
+
+On a host without FUSE - containers, some hardened servers - run the AppImage
+with `--appimage-extract-and-run` (or `APPIMAGE_EXTRACT_AND_RUN=1`). That is
+also how the build machine runs `appimagetool` itself.
+
+## Desktop registration
+
+* **`.deb`** registers the app the normal way: a `.desktop` entry in
+ `/usr/share/applications`, the icon in the hicolor theme, and the two
+ commands on `PATH`. `apt remove personal-jarvis` takes all of it away again.
+* **AppImage** carries its `.desktop` entry and icon inside itself, which is
+ what AppImageLauncher and `appimaged` read when they offer to "integrate"
+ the file. Without one of those tools an AppImage is just a file you run -
+ that is how the format works, and Personal Jarvis does not fight it.
+
+The app itself registers **nothing** when it is a frozen build:
+`jarvis/setup/desktop_integration.py` and the writers in
+`jarvis/ui/icon_utils.py` return a logged no-op under
+`jarvis.core.frozen.is_frozen()`. They would otherwise write an entry whose
+`Exec=` points at `sys.executable` - which, inside an AppImage, is a path in a
+temporary mount that disappears the moment the app exits.
+
+## Updates
+
+The in-app updater replaces the running AppImage in place: it downloads the new
+`PersonalJarvis-Linux-x86_64.AppImage` from the GitHub Release, verifies it
+against `installers-SHA256SUMS.txt` from the same release, atomically replaces
+the file `$APPIMAGE` points at, restores the executable bit and relaunches.
+A `.deb` install updates through the package, not through the app.
+
+## What has actually been tested
+
+Proven in a `python:3.12-bookworm` container on 2026-08-25, against a real
+156 MB AppImage built by this script:
+
+* `appimagetool` digest check, AppDir assembly, `desktop-file-validate` passes
+* `--version` through the packaged AppImage (`APPIMAGE_EXTRACT_AND_RUN=1`),
+ through the extracted `AppRun`, and through `usr/bin/jarvis`
+* `AppRun serve` boots the backend and `/api/health` answers in ~3 s
+* the browser hand-off calls the opener with `http://127.0.0.1:47821`
+* the Debian package's control file, symlinks and desktop entry
+
+Not tested: a real FUSE-mounted run on a desktop distribution, and the app on a
+machine that actually has a display. Both belong in the CI job and on a real
+Linux desktop before release.
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
new file mode 100644
index 0000000000..eba5e0c42d
--- /dev/null
+++ b/packaging/macos/README.md
@@ -0,0 +1,134 @@
+# macOS packaging — the .dmg
+
+`packaging/macos/build.sh` produces one downloadable disk image per processor
+family:
+
+| Runner | Artifact |
+|---|---|
+| Apple Silicon (`macos-15`) | `dist/installers/PersonalJarvis-macOS-arm64.dmg` |
+| Intel (`macos-15-intel`) | `dist/installers/PersonalJarvis-macOS-x64.dmg` |
+
+The image contains `Personal Jarvis.app` next to a symlink to `/Applications`:
+open it, drag the app across, done. The app is a PyInstaller `BUNDLE` built
+from `jarvis.spec`; its icon is `assets/icons/jarvis.icns`, regenerated by
+`packaging/macos/make_icns.py`.
+
+## Building
+
+```bash
+python3 -m pip install -e ".[full]"
+python3 -m pip install pyinstaller
+bash packaging/macos/build.sh
+```
+
+`DRY_RUN=1` prints every command it would run without running any of them,
+which is how the flow is rehearsed off a Mac.
+
+## Signing and notarization
+
+All four settings come from the environment, so the same script serves a
+maintainer's Mac and both GitHub runners:
+
+| Variable | Meaning |
+|---|---|
+| `APPLE_SIGNING_IDENTITY` | `Developer ID Application: NAME (TEAMID)` |
+| `APPLE_ID` | Apple ID used for notarization |
+| `APPLE_TEAM_ID` | 10-character team identifier |
+| `APPLE_APP_SPECIFIC_PASSWORD` | app-specific password for that Apple ID |
+
+With the identity set, the script signs every nested Mach-O object inside the
+bundle before sealing the bundle itself (Apple's guidance is inside-out;
+`--deep` on the outer seal is the safety net, not the strategy), using
+`--options runtime --timestamp` and `packaging/macos/entitlements.plist`. It
+then notarizes **the app** before building the image, so the ticket is stapled
+into the bundle and survives the user dragging the app out of the `.dmg` -
+otherwise the first launch after that drag needs a network round trip. The
+image is signed, notarized and stapled afterwards, then `hdiutil verify` and
+`stapler validate` check the result.
+
+The app-specific password is never written to the build log: the `notarytool`
+line is printed with the secret replaced and the real invocation is not traced.
+
+Without `APPLE_SIGNING_IDENTITY` the script **ad-hoc signs**
+(`codesign --force --deep -s -`), skips notarization, and says so in one line.
+That build is fine for local testing and must not be published.
+
+## First launch
+
+* **Signed and notarized build:** a normal double-click. Nothing to explain.
+* **Unsigned or ad-hoc build:** macOS refuses the first double-click
+ ("Personal Jarvis can't be opened because Apple cannot check it for malicious
+ software"). The way through is **right-click (or Control-click) the app in
+ Finder, choose Open, then Open again in the dialog**. macOS remembers the
+ decision for that copy of the app. Alternatively
+ `xattr -dr com.apple.quarantine "/Applications/Personal Jarvis.app"`.
+
+## Permission prompts
+
+macOS grants privacy permissions to an *app identity*, not to a folder, and
+Apple does not let an installer pre-approve any of them. The app therefore asks
+for each one at the moment it needs it, through Apple's own prompts:
+
+* **Microphone** — voice input; the app is usable for text without it.
+* **Speech recognition** — on-device dictation.
+* **Camera** — only the vision features.
+* **Screen recording** — screen capture and Computer-Use; granted in
+ System Settings > Privacy & Security, and macOS requires a restart of the app
+ afterwards.
+* **Accessibility / Input monitoring** — global hotkeys and Computer-Use input.
+* **Automation (Apple events)** — controlling other apps, e.g. the media
+ session.
+
+Each of these needs *both* an entitlement in
+`packaging/macos/entitlements.plist` and a usage-description string in the
+bundle's `Info.plist` (built by `jarvis.spec`). Missing entitlement: the app is
+refused before the prompt appears. Missing usage string: macOS kills the app
+the moment it asks. Declining any of them leaves the app working, with that
+feature honestly unavailable.
+
+## Reaching the CLI
+
+The bundle ships the console entry at
+`Personal Jarvis.app/Contents/MacOS/jarvis`. It is the same program as the
+pip-installed `jarvis` command:
+
+```bash
+"/Applications/Personal Jarvis.app/Contents/MacOS/jarvis" --version
+"/Applications/Personal Jarvis.app/Contents/MacOS/jarvis" serve
+```
+
+To type plain `jarvis`, link it once:
+
+```bash
+sudo ln -sf "/Applications/Personal Jarvis.app/Contents/MacOS/jarvis" /usr/local/bin/jarvis
+# or, without sudo, if ~/.local/bin is on your PATH:
+mkdir -p ~/.local/bin
+ln -sf "/Applications/Personal Jarvis.app/Contents/MacOS/jarvis" ~/.local/bin/jarvis
+```
+
+The symlink keeps working across updates because the app bundle is replaced at
+the same path. Run the CLI through the **bundle**, never through a copy of the
+executable moved elsewhere: macOS ties privacy grants to the bundle identity,
+and a launch from outside it is a different identity with no grants.
+
+## How an update replaces the app
+
+The in-app updater downloads the `.dmg` for this Mac's architecture from the
+GitHub Release, verifies it against `installers-SHA256SUMS.txt` from the same
+release, mounts it with `hdiutil attach`, replaces the running
+`Personal Jarvis.app` atomically, detaches the image and relaunches with
+`open`. Because the bundle identifier does not change, the privacy grants the
+user already gave survive the update - that is the entire reason every launch
+path has to enter through one bundle identity.
+
+## What has NOT been verified
+
+Nobody has run this script on a Mac yet. What has been checked:
+`bash -n`, ShellCheck 0.11.0 at `-S style` with zero findings, and a full
+`DRY_RUN=1` rehearsal of both the unsigned and the signed/notarized path,
+including a check that the app-specific password never reaches the output.
+
+A real run - PyInstaller on macOS, `codesign`, `notarytool`, `hdiutil`,
+Gatekeeper on a downloaded image, and the permission prompts - needs the macOS
+CI job or a physical Mac and is the last gate before the first public macOS
+release.
diff --git a/packaging/macos/make_icns.py b/packaging/macos/make_icns.py
index 1bddb2bc75..25edcf762d 100644
--- a/packaging/macos/make_icns.py
+++ b/packaging/macos/make_icns.py
@@ -62,9 +62,7 @@ def build(target: Path = TARGET) -> Path:
try:
from PIL import Image
except ModuleNotFoundError as exc: # pragma: no cover - environment problem
- raise SystemExit(
- "Pillow is required to build the macOS icon: pip install Pillow"
- ) from exc
+ raise SystemExit("Pillow is required to build the macOS icon: pip install Pillow") from exc
source_path = _pick_source()
with Image.open(source_path) as source:
@@ -77,10 +75,7 @@ def build(target: Path = TARGET) -> Path:
# Rendered here rather than left to Pillow: its writer resizes with the
# default filter, Lanczos keeps the mascot's thin outline readable at
# 32 px and its glow clean when upscaled.
- members = [
- master.resize((size, size), Image.Resampling.LANCZOS)
- for size in ICNS_SIZES
- ]
+ members = [master.resize((size, size), Image.Resampling.LANCZOS) for size in ICNS_SIZES]
largest = members[-1]
target.parent.mkdir(parents=True, exist_ok=True)
largest.save(target, format="ICNS", append_images=members)
@@ -107,9 +102,7 @@ def verify(target: Path = TARGET) -> list[int]:
sizes = sorted({int(w) * int(scale) for w, _h, scale in icns.info["sizes"]})
missing = [size for size in ICNS_SIZES if size not in sizes]
if missing:
- raise SystemExit(
- f"{target} is missing icon sizes: {', '.join(str(s) for s in missing)}"
- )
+ raise SystemExit(f"{target} is missing icon sizes: {', '.join(str(s) for s in missing)}")
return sizes