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.

19.1 KB
Raw Blame

macOS packaging — the .dmg

packaging/macos/build.sh produces one downloadable disk image per processor family:

Runner Artifact
Apple Silicon (macos-15) dist/installers/Dodaios-macOS-arm64.dmg
Intel (macos-15-intel) dist/installers/Dodaios-macOS-x64.dmg

The image contains Dodaios.app next to a symlink to /Applications: open it, drag the app across, done. The app is a PyInstaller BUNDLE built from dodaios.spec; its icon is assets/icons/dodaios.icns, regenerated by packaging/macos/make_icns.py.

Building

python3 -m pip install -e ".[full]"
python3 -m pip install pyinstaller
bash packaging/macos/build.sh
python3 scripts/ci/check_frozen_macos_app.py --app "dist/Dodaios.app"

DRY_RUN=1 prints every command it would run without running any of them, which is how the flow is rehearsed off a Mac.

The last command reads the finished app (the CI job runs it too) and fails when the bundle could not use its macOS permissions, which no headless smoke run can see:

  • LSBackgroundOnly must be False in Info.plist (dodaios.spec sets it explicitly). PyInstaller turns it on whenever the last executable of the bundle is a console one — the dodaios CLI and its earlier name jarvis are — and LaunchServices then runs the app with no Dock icon and no windows.
  • The frozen archive must contain AVFoundation and the other pyobjc modules the permission code loads by name, which a freezer cannot discover on its own. They come from the desktop-macos extra, so install it on the build machine: python3 -m pip install -e ".[desktop,desktop-macos]" (.[full] includes it).
  • Every usage-description string in dodaios/core/macos_privacy_strings.py must be in Info.plist with exactly that text, and the keys that table lists as removed (camera, speech recognition, system administration) must not be.
  • On a signed build, codesign -d --entitlements :- must report every entitlement of packaging/macos/entitlements.plist and none of the removed ones. An unsigned or ad-hoc build embeds no entitlements (build.sh passes them only with a Developer ID identity), so that part is skipped with a message saying so — it is not a pass.

The v2.5.0 image had the first two defects (BUG-222). In CI the smoke boot of the app also asks it for its permission status and fails when the microphone row reads "unavailable", which is what a framework that did not load looks like from inside.

The usage strings have one source

The NS...UsageDescription strings macOS shows in its permission dialogs live in exactly one file, dodaios/core/macos_privacy_strings.py (standard library only). dodaios.spec (this .dmg app) and dodaios/setup/macos_app_bundle.py (the managed source-install app) both load that file by path: the spec runs before the dodaios package is importable, so neither can use an ordinary import, and neither keeps a copy. tests/unit/packaging/test_macos_privacy_strings.py runs the real spec against stand-in PyInstaller classes and asserts that the spec's info_plist, the managed bundle's plist and the table agree. Add or reword a string in that file only. The Apple Events string is target-neutral on purpose (macOS names the app under control in the dialog itself; the same string serves Music, Spotify and Terminal) and the folder strings are short.

German and Spanish dialog text

The same file carries the German and Spanish versions. Both bundles declare CFBundleDevelopmentRegion (en) and CFBundleLocalizations (en, de, es) in Info.plist (the spec spreads localization_plist_keys() into its dict) and carry Contents/Resources/{de,es}.lproj/InfoPlist.strings. English stays the base text in Info.plist, so there is no en.lproj. For this .dmg app, build.sh runs packaging/macos/add_localizations.py --app "dist/Dodaios.app" on the finished bundle BEFORE signing, because the .lproj files are part of the code seal: one added after codesign would invalidate the signature and the notarization. The managed bundle writes the same files itself when it lays out the app. The format version of the managed bundle is not bumped for this (a bump would rebuild every installed bundle and an ad-hoc rebuild re-asks every permission). scripts/ci/check_frozen_macos_app.py fails the build if a plist key or a .strings file is missing or differs from the table. Unverified: no Mac was available, so that macOS shows these strings in its dialogs, and that it accepts the UTF-8 file (Apple's own tooling writes UTF-16), is not proven; plutil -lint runs on each file in build.sh where plutil exists.

Keys that are deliberately not shipped, because Dodaios has no caller for them (least privilege; a string would promise access the app never uses): NSCameraUsageDescription (and the camera entitlement), NSSpeechRecognitionUsageDescription (speech-to-text is local or a cloud provider, never Apple's speech service) and NSSystemAdministrationUsageDescription (the wrong key for Accessibility and Input Monitoring, which have no usage-description key at all). NSScreenCaptureUsageDescription is kept for parity between the two bundles; Apple's documentation index has no page for that key, so whether it changes anything on macOS is unverified.

Where plutil exists (it does on macOS), build.sh validates the built Info.plist with plutil -lint and signs with a canonical-XML copy of entitlements.plist made by plutil -convert xml1 (written to dist/entitlements.normalized.plist; the tracked file is never rewritten). Anywhere else those steps are skipped, with a log line, and the script stays bash 3.2 clean.

Signing and notarization

All 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) — optional on CI, where it is read from the imported certificate
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
APPLE_CERTIFICATE_P12_BASE64 CI only: the exported Developer ID Application certificate (.p12, with its chain), base64 encoded
APPLE_CERTIFICATE_PASSWORD CI only: the password chosen when exporting it

A GitHub runner starts with an empty keychain, so codesign cannot find a Developer ID identity there until the certificate is imported. With the two APPLE_CERTIFICATE_* variables set, build.sh imports it into a temporary keychain (removed again on exit, search list restored, decoded file deleted), reads the signing identity back from it when APPLE_SIGNING_IDENTITY is not given, and never prints a secret. It does this before the long freeze, so a certificate that cannot be used fails in seconds. A Mac that already holds the identity in its login keychain needs neither variable. Getting the certificate needs an Apple Developer Program membership. The steps, as Apple documents them and not yet followed end to end for this project: create a Developer ID Application certificate in the developer portal, export it from Keychain Access as .p12 together with its chain, encode it with base64 -i certificate.p12 | pbcopy, and store the five required values (APPLE_ID, APPLE_TEAM_ID, APPLE_APP_SPECIFIC_PASSWORD and the two APPLE_CERTIFICATE_* ones) as GitHub Actions secrets; APPLE_SIGNING_IDENTITY is optional on CI.

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.

Those two checks answer "is the image intact" and "is a ticket attached". Neither answers the question the downloader cares about, so a notarized build is finally assessed with spctl while quarantined, exactly as a fresh download is, and the build fails if Gatekeeper rejects it. The quarantine part is not ceremony: an unquarantined file takes a different path through Gatekeeper and is accepted in cases where the downloaded copy is not, so assessing the file as it sits on the builder would prove nothing.

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. The wording varies — "cannot be checked for malicious software", or, commonly, "is damaged and can't be opened", which describes a corrupt download rather than an unsigned one and is why most people simply delete the file.

    The way through depends on the macOS version, and the two are not interchangeable:

    • macOS 15 Sequoia and newer: double-click once and dismiss the warning, then go to System Settings > Privacy & Security, scroll to Security, and use Open Anyway. The failed launch is required — the button only appears for an app that has already been refused.
    • macOS 14 Sonoma and earlier: right-click (or Control-click) the app in Finder, choose Open, then Open again in the dialog. Apple removed this shortcut for unsigned apps in Sequoia, so do not hand it to a user without asking which version they are on.

    Either way, xattr -dr com.apple.quarantine "/Applications/Dodaios.app" does the same thing from a terminal on every version.

    These steps follow Apple's published behaviour and have not been tried on a Mac for this project. An ad-hoc signature is a hash of the app's bytes, so an update is a new app to macOS and its permissions are asked for again; a downloaded image keeps one identity across versions only when it is signed with a stable certificate, which for a public download means a Developer ID one.

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 a permission at the moment a feature the person starts needs it, never at launch, and Apple's own prompt or System Settings pane does the asking:

  • Microphone — dictation, talking to Dodaios, the wake word once it is switched on; typed chat works without it.
  • Screen recording — screen capture and Computer-Use; granted in System Settings > Privacy & Security. Whether macOS needs the app reopened afterwards is unverified (reports conflict), so the app re-checks the live state and only suggests a restart as a hint.
  • Accessibility / Input monitoring — typing and clicking for you (Computer-Use, dictation paste) and global shortcuts. These two have no usage-description key; the dialog text is fixed by macOS.
  • Automation (Apple events) — controlling other apps: Music or Spotify while "Mute music while dictating" is on, and Terminal for sign-in and agent windows.
  • Files and folders, local network — asked by macOS itself the first time a feature touches Desktop, Documents, Downloads, an external or network drive, or a device on the local network.

There is no camera and no speech-recognition row: Dodaios has no caller for either, so the bundle neither declares a string nor an entitlement for them.

The downloaded app is its own app to macOS: bundle id ai.personaljarvis.desktop (dodaios.spec), separate from the managed bundle the source installer builds (com.personal-jarvis.desktop). Both are accepted as "the installed app" by the permission code, and each keeps its own grants.

Each protected API needs both halves on a hardened (Developer ID) build: an entitlement in packaging/macos/entitlements.plist and a usage-description string in the bundle's Info.plist (the table in dodaios/core/macos_privacy_strings.py). Missing entitlement: the app is refused before the prompt appears. Missing usage string: macOS ends the process (microphone) or, as third parties report for other services, silently refuses without a prompt; the exact failure mode is unverified, which is why check_frozen_macos_app.py asserts the whole string table on every built app. Declining any permission leaves the app working, with that one feature honestly unavailable.

Entitlements (entitlements.plist)

An entitlements file has no comment syntax Apple documents, so entitlements.plist carries none; this section is where the reasoning lives.

Notarization requires the Hardened Runtime (codesign --options runtime), and the Hardened Runtime denies by default exactly the things this app needs. Every entry below is here because leaving it out breaks a shipped feature or stops the app from launching at all. Nothing is requested "just in case", because each one weakens a real platform protection. The file is only embedded by the Developer ID path of build.sh: the ad-hoc images published so far carry no entitlements, so every judgement below is unverified on a hardened build until the signed path has run once (scripts/ci/check_frozen_macos_app.py then reads them back with codesign -d --entitlements :-).

Entitlements grant the app the right to ask; the usage strings are what the person reads in the prompt. A hardened app missing the entitlement is refused before the prompt appears.

Entitlement Why
com.apple.security.device.audio-input Microphone. The whole voice pipeline (wake word, dictation, calls) reads the default input device through PortAudio. Without it a hardened build fails every capture attempt instead of showing the microphone prompt.
com.apple.security.automation.apple-events Apple events. Dodaios drives other applications through AppleScript for the media-session and window-control paths (dodaios/platform/media_session.py, music_player.py). Sending an Apple event to another process from a hardened app requires this entitlement plus NSAppleEventsUsageDescription.
com.apple.security.cs.allow-unsigned-executable-memory Unsigned executable memory. Expected to be needed by a CPython application: ctypes/libffi build closure trampolines in memory they mark executable (sounddevice's PortAudio binding, vosk's libvosk binding, and several numeric wheels all go through ctypes), and the Hardened Runtime is documented to refuse such allocations without it. Whether this app really needs it has not been observed on a hardened build. It is the narrowest of the "allow ... memory" entitlements; allow-jit and its broader siblings are deliberately not requested.
com.apple.security.cs.disable-library-validation Library validation. A PyInstaller bundle dlopen()s dozens of third-party .so/.dylib files out of Contents/Frameworks and Contents/Resources at runtime (onnxruntime, PortAudio, libvosk, PyAV's FFmpeg libraries). Library validation demands every loaded library be signed by the same team ID as the main binary; the re-sign pass in build.sh does re-sign them, but any library loaded from a path the pass did not walk, or a plugin the user installs later into the same process, is then refused with an opaque "code signature invalid". This is the one entitlement that could be dropped later: it needs a build where every loadable object is provably signed by us, which the plugin system's "install a wheel at runtime" design currently rules out.

Removed: com.apple.security.device.camera. The old file requested it for "vision/screen-share features", but no code in Dodaios opens a camera (the web voice path asks for audio only, and screen capture is Screen Recording, not the camera), so it granted the right to ask for something nothing asks for. Re-adding it needs a camera feature, NSCameraUsageDescription in the string table and a caller in the same change.

Screen Recording, Accessibility, Input Monitoring and posting events have no entitlement at all; they are gated by the person's decision in System Settings alone.

Reaching the CLI

The bundle ships the console entry at Dodaios.app/Contents/MacOS/dodaios. It is the same program as the pip-installed dodaios command:

"/Applications/Dodaios.app/Contents/MacOS/dodaios" --version
"/Applications/Dodaios.app/Contents/MacOS/dodaios" serve

To type plain dodaios, link it once:

sudo ln -sf "/Applications/Dodaios.app/Contents/MacOS/dodaios" /usr/local/bin/dodaios
# or, without sudo, if ~/.local/bin is on your PATH:
mkdir -p ~/.local/bin
ln -sf "/Applications/Dodaios.app/Contents/MacOS/dodaios" ~/.local/bin/dodaios

Contents/MacOS/jarvis is the same entry under the command's earlier name; a link made to it before keeps working.

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 Dodaios.app atomically, detaches the image and relaunches with open. Whether the privacy grants the user already gave survive the update depends on the signature, not on the bundle identifier alone: with a Developer ID signature the identity (bundle id plus Team ID) is the same in every version and the grants stay; with the ad-hoc images published so far each version is a new app to macOS and every permission is asked for again. Either way, every launch path has to enter through one bundle identity.

What has NOT been verified

The macOS CI runners build and publish the ad-hoc images (PyInstaller, codesign -s -, hdiutil; the v2.5.0 build log shows it). The signed and notarized path has never run for real: it needs the Apple secrets above, and with them the first real codesign, notarytool and stapler pass, the first import into a real keychain, Gatekeeper on a downloaded image, and the permission prompts of a signed app are all still to be seen. The certificate export steps and the first-launch steps for each macOS version are written from Apple's documentation, not from a run. What has been checked off a Mac: bash -n, ShellCheck 0.11.0 at -S style with zero findings, a DRY_RUN=1 rehearsal of the unsigned path, the certificate import and the signed/notarized path, and the real import branch run against a stand-in security command (tests/unit/packaging/test_macos_build_script.py), including that no secret reaches the output.