Agent Pilot Mac Host

Agent Pilot Host connects a Mac coding agent to the Agent Pilot iPhone app. Version 1.1 uses one-time enrollment and role-bound device credentials.

Secure setup

Copy the command shown by the iPhone app into the real macOS Terminal:

npx -y @agentpilot/[email protected] setup --agent claudeDesktop --pair ABCD2345EFGH

The 12-character code expires after five minutes and can be claimed once. setup exchanges it over HTTPS for a Mac-only 256-bit credential, removes the code from memory, installs a stable runtime under ~/.agent-pilot/runtime, and registers the login LaunchAgent.

Do not run this command in a Linux coding sandbox. The Host requires macOS, launchctl, Accessibility permission, and the real desktop Agent process.

Files and network boundaries

• ~/.agent-pilot/config.json is mode 600 and stores the Mac device credential.
• ~/.agent-pilot/host.json is mode 600 and never stores pairing codes or credentials.
• Relay credentials are sent only as Authorization: Bearer ... headers.
• The local connector and diagnostics servers listen on 127.0.0.1 only.
• /publish, /register, /status, and the local WebSocket require a separate local bearer token.
• The diagnostics panel does not render pairing codes, tokens, or pairing QR codes.

Commands

agent-pilot-host status
agent-pilot-host install
agent-pilot-host uninstall

The default delivery mode uses AppleScript. Grant Accessibility permission under:

System Settings -> Privacy & Security -> Accessibility

Development

Use a device credential issued by a local Relay v0.2 instance:

PILOT_RELAY_URL='ws://127.0.0.1:8787/relay' \
PILOT_RELAY_TOKEN='issued-device-token' \
PILOT_LOCAL_LINK_TOKEN='separate-local-token' \
PILOT_DELIVERY_MODE='dry-run' \
npm start

Verify before publishing:

npm test
npm audit --omit=dev
npm pack --dry-run