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.
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:
LSBackgroundOnlymust beFalseinInfo.plist(dodaios.specsets it explicitly). PyInstaller turns it on whenever the last executable of the bundle is a console one — thedodaiosCLI and its earlier namejarvisare — and LaunchServices then runs the app with no Dock icon and no windows.- The frozen archive must contain
AVFoundationand the other pyobjc modules the permission code loads by name, which a freezer cannot discover on its own. They come from thedesktop-macosextra, 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.pymust be inInfo.plistwith 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 ofpackaging/macos/entitlements.plistand none of the removed ones. An unsigned or ad-hoc build embeds no entitlements (build.shpasses 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.