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.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
docs(packaging): macOS and Linux packaging guides
rubenluetke10-beep84ea2aa0fa64
diff --git a/packaging/linux/README.md b/packaging/linux/README.mdnew file mode 100644index 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.mdnew file mode 100644index 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.pyindex 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 Imageexcept 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 excsource_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