Local Network Setup

This is the simplest connection mode. Your iPhone connects directly to the Mac over your local WiFi. Latency is minimal and no internet is required.

When to use this

• iPhone and Mac are on the same WiFi network.
• You're at home, office, or any trusted network.
• You want the lowest latency and simplest setup.

Step 1: Check your network

Both devices must be on the same WiFi network and subnet. Things that can prevent this:

• Corporate or hotel WiFi that isolates devices (client isolation).
• VPN running on either device that changes the network path.
• Mac firewall blocking incoming connections on the server port.

Step 2: Find your Mac's IP

The Mac app shows your IP in the menu bar panel. Alternatively:

ipconfig getifaddr en0

This returns something like 192.168.1.42.

Step 3: Start the server

If using the Mac app, click Start Server from the menu bar. The default port is 8765.

If using the standalone server:

cd MacServer && npm start

You can customize the port with the PORT environment variable:

PORT=9000 npm start

Step 4: Connect from iPhone

Option A: QR code (fastest)

• Click the QR icon in the Mac app's menu bar. Scan with the iPhone app.

Option B: Bonjour auto-discovery

• The server broadcasts via Bonjour/mDNS. Your Mac should appear in the iPhone app's server list.

Option C: Manual entry

• Enter 192.168.x.x and port 8765 (or your custom port) in the iPhone app.
• Enter the API key if set.
• Tap Connect.

Step 5: Verify

Once connected, create or select a session and send a test prompt. Terminal output should appear within 1-2 seconds.

Tips

• Mac sleep: the Mac app can prevent sleep while the server is running. Enable "Prevent Sleep While Running" in Settings if your Mac keeps going to sleep during long tasks. This blocks idle-timeout sleep only — closing the lid, manual sleep, or low battery still puts the Mac to sleep, so for true 24/7 remote use plug into power and use clamshell mode (external display + keyboard) or run on a desktop / always-on host.
• Static IP: if your Mac's IP changes frequently (DHCP), consider assigning a static IP in System Settings > Network, or use Bonjour discovery instead of a manual IP.
• Firewall: if macOS Firewall is enabled, allow incoming connections for the Tactic Remote app (or the node process if using standalone server).