Mac agent setup

Install Cmdora on your Mac

Use this guide after installing Cmdora on iPhone. The Mac agent runs from the menu bar, starts the local coordinator, and shows the pairing code for your phone.

Download Mac agent

1. Requirements

  • macOS 13 Ventura or newer.
  • Cmdora for iPhone on iOS 17 or newer.
  • Your iPhone and Mac on the same Wi-Fi network, or on the same private network such as Tailscale.
  • Codex CLI is required only for AI coding tasks. Terminal sessions, folder browsing, builds, and quick commands work without Codex.
  • For AI tasks, install Codex CLI using the official OpenAI Codex CLI guide.

2. Install the agent

  1. Download Cmdora.dmg.
  2. Open the DMG and drag Cmdora to Applications.
  3. Open Cmdora from Applications. If macOS asks for confirmation, choose Open.
  4. Look for the Cmdora icon in the menu bar.

3. Configuration

For normal setup, use the Cmdora menu bar app instead of editing environment files.

  • DEVPILOT_PROJECTS: choose Cmdora menu bar app -> Projects -> Add Project Folder. These folders appear on iPhone.
  • DEVPILOT_CREATE_PROJECT_ROOT: choose Cmdora menu bar app -> New Project Folder if you want Cmdora to create new projects under a parent folder.
  • Coordinator address: Cmdora starts the local coordinator automatically. The pairing panel shows a LAN address like http://<your-mac-lan-ip>:8080.
  • Agent token: Cmdora generates it automatically. The pairing panel shows the token for manual entry as <your-token>.
Manual values shown by the pairing panel
Server URL: http://<your-mac-lan-ip>:8080
Agent ID: <your-agent-id>
Token: <your-token>
Project folder: <your-project-folder>

4. Start and verify

  1. In the Mac menu bar, choose Cmdora -> Show Pairing Code.
  2. On iPhone, open Cmdora and tap +.
  3. Tap Scan QR Code and scan the code shown on the Mac.
  4. Save the remote. The Mac should appear in the Cmdora list.
  5. Open the Mac. You should see the project folders selected in the Mac menu bar. Pick a folder and open Terminal.
Quick checks: if macOS asks about incoming connections, click Allow or the iPhone will not connect. If the QR code is unavailable, confirm that Wi-Fi is on and the Mac has a LAN IP address. If the iPhone cannot connect, make sure both devices are on the same network and that the Server URL uses the Mac LAN IP, not 127.0.0.1.