macOS agent

On macOS the agent ships as a menu-bar app that supervises the background process and shows the pairing QR. Requires macOS 12 or later. Apple silicon and Intel builds are separate DMGs — open the matching one and drag SpadeIDE Agent.app to Applications.

Install

Open the .dmg and drag SpadeIDE Agent.app to Applications.
Launch it. A spade icon appears in the menu bar.
Click the icon — the popover shows the pairing QR, the agent's status, and your paired tablets.

The app is signed with a Developer ID certificate and notarised, so Gatekeeper opens it without a warning. If macOS says the app is damaged or from an unidentified developer, the download was modified — fetch it again rather than right-clicking past the warning.

Folder access

The first time the agent reads a folder macOS protects — Documents, Desktop, Downloads — the system asks for permission. Allow it once and the grant sticks, because the app is signed with a stable identity.

If the prompt reappears after every restart, the copy you are running is unsigned (a local build rather than a release). Release builds do not re-prompt.

Enable Start at login in the popover. The agent then comes up with the machine and is ready before you pick up the iPad — worth doing, since an agent that is not running is an iPad that cannot connect.

Pairing

Open the popover, then scan the QR in the iPad app under Pair a host. The code is single-use and expires after ten minutes; click New pair code to mint another. Each iPad pairs once — several tablets can stay paired at the same time.

A newly paired tablet appears in the popover immediately, so an unexpected pairing is visible and can be removed on the spot.

Command line

The same CLI as on Linux is embedded in the app bundle. Add it to your PATH if you want it:

sudo ln -s "/Applications/SpadeIDE Agent.app/Contents/Helpers/spade-agent" \
  /usr/local/bin/spadeide

spadeide status
spadeide devices
spadeide unpair <id|name>
spadeide remote on|off|status

See the Linux page for the full command and flag reference — they are identical.

Ports

Port	Bind	Purpose
`7422/tcp`	All interfaces	TLS listener for your iPads
`7423/tcp`	`127.0.0.1` only	Control API used by the menu-bar app, token-gated
`5353/udp`	Multicast	Bonjour, via the system responder

macOS may ask whether to allow incoming connections the first time the agent starts. Allow it, or the iPad will not find the Mac on your own network.

Do not port-forward 7422 from your router. Use remote access instead — the agent dials out, so nothing needs to be exposed.

Remote access

Off by default. Toggle Remote access in the popover, or from the command line:

spadeide remote on
spadeide remote status
spadeide remote off

While it is off the agent makes no outbound connections at all. With it on it holds one connection to the introducer and heartbeats; no file data crosses it unless a remote iPad actually connects and the network refuses a direct tunnel. See hosting your own introducer.

Files on disk

Path	Contents
`~/.spade-agent/state.json`	Paired devices, remote-access setting
`~/.spade-agent/certs/`	TLS certificate and key — the agent's pinned identity
`~/.spade-agent/identity`	Ed25519 key behind the agent id
`~/.spade-agent/control.token`	Control-API token, mode 0600
`~/.spade-agent/agent.log`	Log, mode 0600

Deleting certs/ gives the agent a new identity, and every paired iPad will refuse to connect until you pair again. That is certificate pinning doing its job.

Uninstalling

osascript -e 'quit app "SpadeIDE Agent"'
rm -rf "/Applications/SpadeIDE Agent.app"
rm -rf ~/.spade-agent        # pairings and identity too