Skip to content

feat(macos): run atvloadly natively on macOS - #228

Closed
Hintay wants to merge 1 commit into
bitxeno:masterfrom
Hintay:feat/macos-native
Closed

Hintay wants to merge 1 commit into
bitxeno:masterfrom
Hintay:feat/macos-native

Conversation

@Hintay

@Hintay Hintay commented Oct 21, 2026

Copy link
Copy Markdown

Why

atvloadly only runs in Docker on Linux/OpenWrt. On a Mac, Docker Desktop or OrbStack puts the service behind a VM network, so mDNS discovery is unreliable and the Mac's own usbmuxd is out of reach (see #96).

This PR runs the service natively on Apple Silicon and Intel Macs. It uses the system mDNS and the system usbmuxd, so Docker, Avahi, D-Bus and usbmuxd2 are not needed. Linux and Docker behaviour is unchanged.

How it works

  • Build: the web UI and the service build with the same commands as on Linux (npm run build, go build); no build script is added. Your PlumeImpactor fork's v2.7.0-patch.1 release, which the Docker image uses, has no macOS plumesign, so doc/macos.md documents building it from source with Cargo and omnisette/aos-kit for macOS's native Anisette. Everything is built in the ignored build/ directory.
  • Signing engine lookup: a plumesign placed next to the atvloadly binary is used before PATH, so the bundle works from any working directory. A missing engine is reported at startup instead of on the first install.
  • Data directories: config, database, logs and keys go to ~/Library/Application Support/atvloadly, no longer derived from the binary name. PlumeImpactor state follows plumesign's own XDG_CONFIG_HOME handling, and external certificate installs isolate XDG_CONFIG_HOME as well as HOME. CoreADI downloads are Linux-only (macOS uses the system Anisette) and are written to the engine's data directory.
  • Discovery: the mDNS browser reloads network interfaces every 30 seconds (Wi-Fi changes, waking from sleep) and accepts address updates. A rescan resets the pairing throttle and cancels in-flight pairing checks. TXT records are no longer logged, since they carry the remote pairing auth tag.
  • USB-paired devices: macOS keeps lockdown pair records in /var/db/lockdown, readable only by _usbmuxd, so devices paired over USB never matched their _apple-mobdev2 announcements. atvloadly now reads the records through the system usbmuxd socket (ListDevices and ReadPairRecord), decoding only the Wi-Fi MAC address. No sudo is needed and the records are never modified. Because usbmuxd attaches a Wi-Fi device after seeing the same announcement, the lookup is retried briefly, and a goodbye or rescan cancels it.
  • Remote pairing stays ahead of lockdown: on Linux the lockdown record is deleted once remote pairing succeeds. macOS owns its records, so a later mobdev2 announcement must not replace a remote connection. Lockdown devices now get their device class and trigger the device-connected callback (automatic refresh), like the Linux Avahi path.

Fixes found along the way

These apply to every platform:

  • Install result: an install now succeeds when the engine exits with status 0, instead of when the log contains Installation Succeeded or Installation complete. INFO logs can be hidden by RUST_LOG, and a success-looking line can precede a later failure.
  • Pairing: one pairing session per WebSocket, with PairManager state guarded against races. The server sends an explicit Pairing Succeeded! / Pairing Failed!, so the pair page no longer guesses from the output. The page also handles timeouts and lost connections, and clears the PIN.
  • AFC check: CheckAfcService shadowed err, so a usbmuxd restart that is not supported (it returned nil) counted as a successful recheck. Restarting usbmuxd now returns an explicit error outside Linux.
  • Tests: the route tests that queue an install run in their own process. Otherwise a later settings test starts the global queue worker, which installs the earlier test's app into the wrong temporary directory. This made TestSaveUpdateSettingsBlankRemovesToken flaky on master.
  • CI: the build workflow gains a macos-latest job, runs go test ./..., compiles both macOS architectures and uses npm ci.

Not in this PR

  • macOS binaries in releases. The way Linux is released would carry over: your PlumeImpactor fork (bitxeno/PlumeImpactor) publishes a macOS plumesign, and release.yml adds darwin/amd64,darwin/arm64 to its xgo targets. macOS users could then download a release instead of building from source. If this direction works for you, I can follow up with a PR to your fork that adds the macOS plumesign build to its release.
  • Running as a background service (launchd).

Validation

  • go test ./..., the race detector on internal/manager, internal/service and internal/exec, go vet, golangci-lint (0 issues) and the frontend tests pass.
  • darwin/amd64 cross-compiles with cgo on an Apple Silicon Mac.
  • Following doc/macos.md on a clean checkout builds the web UI, the service and the signing engine, and the service starts, finds the adjacent plumesign without PATH and serves the web UI.
  • On an Apple Silicon Mac: an Apple TV is discovered and paired over remote pairing; an iPad paired over USB appears as a paired Lockdown device with its device class, and plumesign device-info reaches it through the macOS usbmuxd.

Related to #96.

@bitxeno

bitxeno commented Oct 23, 2026

Copy link
Copy Markdown
Owner

Thank you for the PR. There are currently no plans to merge this feature. mygo will be used to support macOS and Windows platforms in the future.

@bitxeno

bitxeno commented Oct 25, 2026

Copy link
Copy Markdown
Owner

The new version is now supported.

@bitxeno bitxeno closed this Oct 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

⌂ 换网址