🖥️ Mac Remote Controller

Control your Mac from any device on your local network — keyboard, mouse, media, screen streaming and more.

---

📋 Table of Contents

• Requirements
• macOS Permissions
• Install Dependencies
• HTTPS Setup
• Trust Certificate on iPhone
• Run the Server
• Connect from iPhone
• File Structure
• Troubleshooting

---

🧰 Requirements

• macOS (Apple Silicon or Intel)
• Python 3.10+
• Homebrew
• iPhone / iPad on the same WiFi network

---

⚠️ macOS Permissions

These must be granted before running the server — otherwise key presses, mouse control and screen capture won't work.

Accessibility

1. System Settings → Privacy & Security → Accessibility
2. Click + and add Terminal (or your Python binary e.g. /usr/local/bin/python3)
3. Toggle it ON

Screen Recording

1. System Settings → Privacy & Security → Screen Recording
2. Add Terminal or Python → Toggle ON

💡 On first run macOS may auto-prompt you — click "Open System Settings" and enable from there.

---

📦 Install Dependencies

pip3 install -r requirements.txt
brew install cliclick

---

🔐 HTTPS Setup

The server runs over HTTPS so that browser APIs work correctly on iPhone. The server now uses your Mac's stable Bonjour hostname instead of depending on the changing WiFi IP.

Your Mac's local URL is:

https://pratiks-MacBook.local:5001

The server automatically reads the macOS LocalHostName, creates certs/ca.pem if needed, and signs certs/cert.pem for:

• localhost
• pratiks-MacBook.local
• the current LAN IP as a fallback

Run the server once to create or refresh the certificates:

python3 server.py

If your WiFi IP changes later, just restart the server. You do not need to repeat the iPhone certificate trust flow as long as certs/ca.pem is the same.

To see or change the .local name on macOS:

scutil --get LocalHostName

Or use System Settings → General → Sharing → Edit → Local hostname.

What each file does

File	Purpose	Share?
certs/ca.pem	Root CA — AirDrop this to iPhone once	✅ Safe to share
certs/ca-key.pem	CA private key — keep this secret	❌ Never share
certs/cert.pem	Server certificate — used at runtime	❌ Keep on Mac
certs/key.pem	Server private key — used at runtime	❌ Never share

---

📲 Trust Certificate on iPhone

This is a one-time setup per device as long as certs/ca.pem is preserved.

1. AirDrop certs/ca.pem to your iPhone

Open Finder to your project folder:

open /path/to/remote/certs

AirDrop ca.pem to your iPhone (not ca-key.pem).

2. Install the profile on iPhone

Settings → General → VPN & Device Management → tap the downloaded profile → tap Install → enter passcode → tap Install again on the warning screen.

3. Enable full trust ⚠️ (most commonly missed step)

Settings → General → About → Certificate Trust Settings → find Remote Mac Controller → toggle ON → tap Continue.

Without this step Safari will still reject the certificate even after installation.

---

🚀 Run the Server

python3 server.py

You'll see:

==========================================================
  Remote Mac Controller
==========================================================
  URL: https://pratiks-MacBook.local:5001
  Fallback URL: https://192.168.1.4:5001
  Clipboard: copied
  Press Ctrl+C to stop
==========================================================

The .local URL is automatically copied to your clipboard. Use the fallback IP only if .local does not resolve on the current network.

---

📱 Connect from iPhone

1. Make sure iPhone and Mac are on the same WiFi (or iPhone hotspot)
2. Open Safari on iPhone
3. Go to https://pratiks-MacBook.local:5001 — type the full https:// prefix
4. You should see "Connected to Mac" in green

💡 Add to Home Screen — tap Share → "Add to Home Screen" for a fullscreen PWA experience with no browser chrome.

---

📁 File Structure

remote/
├── server.py               ← Flask + SocketIO backend
├── requirements.txt        ← Python dependencies
├── README.md               ← This file
├── certs/
│   ├── ca.pem              ← Root CA (AirDrop to iPhone)
│   ├── ca-key.pem          ← CA private key (never share)
│   ├── cert.pem            ← Server certificate
│   └── key.pem             ← Server private key
├── templates/
│   ├── index.html          ← Main iPhone controller UI
│   ├── apps.html           ← App launcher UI
│   ├── remote_preview.html         ← Remote with screen preview
│   └── remote_preview_trackpad.html ← Remote with trackpad
├── media/                  ← App icons and assets
└── logs/
    └── remote.log          ← Rotating server logs

---

🛠️ Troubleshooting

Problem	Fix
Keys not working	Grant Accessibility permission (see macOS Permissions)
Screen recording not working	Grant Screen Recording permission
iPhone shows certificate warning	Complete the Trust Certificate steps above — especially Step 3
.local address does not open	Make sure both devices are on the same WiFi/subnet. Guest, hotel, or office WiFi can block Bonjour/mDNS. Try the printed fallback IP.
Safari drops https:// and fails	You missed the Certificate Trust Settings toggle (Step 3 above)
Can't connect from iPhone	Ensure same WiFi; always type full https:// prefix
Port already in use	Change SERVER_PORT in server.py
osascript errors	Re-grant Accessibility, restart Terminal
IP changed after reconnect	Use https://pratiks-MacBook.local:5001; the server refreshes the fallback IP cert automatically on restart.
Mouse/click not working	Install cliclick via brew install cliclick

---