Mac Executor Setup Guide¶

Complete, standalone guide for setting up a Mac as a dedicated autonomous iOS development agent using Claude Code with a Max subscription. Follow end-to-end from a fresh Mac to a running executor.

Overview¶

What We're Building¶

A poll-claim-execute-report loop that runs 24/7 with full MCP access:

                                    GitHub Issues
                                    (agent-ready)
                                         |
                                         v
+------------------+            +------------------+
|   Orchestrator   |  creates   |    Issue Queue   |
|   (Claude-3)     | ---------> | across all repos |
+------------------+            +------------------+
                                         |
                                    polls every 60s
                                         |
                                         v
                                +------------------+
                                |   Mac Executor   |
                                |  (this machine)  |
                                +------------------+
                                    |     |     |
                              claim    Claude   MCP
                              issue    Code     Tools
                                    |     |     |
                                    v     v     v
                              +--------+  +--------+
                              | GitHub |  |  PR +  |
                              |  API   |  | Report |
                              +--------+  +--------+
                                              |
                                    Discord + Slack
                                    notifications

MCP Servers Included¶

Server	Purpose	Access
GitHub	Issues, PRs, code search	Read + Write (PRs, comments)
RevenueCat	Subscription metrics	Read-only
App Store Connect	Builds, versions, apps	Read-only
Cuti-E	Conversations, feedback	Read-only
Context7	Library documentation	Read-only
Claude Memory	Decisions, learnings	Read + Write
Infra Health	Health, runners	Read-only
Discord	Notifications	Write
Slack	Notifications	Write

Time Estimate¶

~2 hours from fresh Mac to running executor (assuming tools are already downloaded).

Hardware Requirements¶

Requirement	Minimum
Mac model	Any Apple Silicon (M1/M2/M3/M4)
macOS	Ventura 13.0+ (for modern pf and launchd)
RAM	8 GB
Disk	50 GB free (Xcode ~35 GB + simulators)
Power	Always plugged in (lid can be closed)
Network	Ethernet or stable Wi-Fi

Security Model (Three Layers)¶

Layer	Mechanism	What It Blocks	Scope
1. Tailscale ACL	`tag:sandbox` on control plane	Outbound tunnels to any Tailscale node	Network-level
2. macOS pf firewall	Kernel packet filter (IPv4 + IPv6)	Private ranges, LAN, link-local, ULA, multicast	Kernel-level
3. Claude Code permissions	`bypassPermissions` + executor-settings.json	Tool allow/deny lists prevent production writes	App-level

Prerequisites¶

# Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Required tools
brew install gh jq git node

# Claude Code
npm install -g @anthropic-ai/claude-code

# Tailscale
brew install --cask tailscale

Step 1: Install Xcode¶

Install Xcode from the Mac App Store
Accept the license:
```
sudo xcodebuild -license accept
```

Set active developer directory:

sudo xcode-select --switch /Applications/Xcode.app

Install iOS Simulator runtime:
Open Xcode > Settings > Platforms
Download the latest iOS runtime

Verify:

xcodebuild -version
xcrun simctl list devices available | grep iPhone

Step 2: macOS Configuration¶

# Hostname
sudo scutil --set HostName mac-executor
sudo scutil --set LocalHostName mac-executor
sudo scutil --set ComputerName "Mac Executor"

# Disable sleep
sudo pmset -a disablesleep 1
sudo pmset -a displaysleep 0
sudo pmset -a sleep 0
sudo pmset -a autorestart 1

Disable automatic updates: System Settings > General > Software Update > disable all toggles.

Enable Screen Sharing and Auto-Login (see full guide in previous docs).

Step 3: Tailscale (Layer 1)¶

open -a Tailscale
sudo tailscale up --advertise-tags=tag:sandbox

Verify tag:sandbox is applied with tailscale status.

Step 4: Clone mac-executor¶

mkdir -p ~/repos
cd ~/repos
git clone https://github.com/Stig-Johnny/mac-executor.git
cd mac-executor

Step 5: pf Firewall (Layer 2)¶

sudo ./setup/install-pf.sh
./setup/verify-pf.sh

Step 6: Claude Code Authentication¶

From Screen Sharing or directly on the Mac:

claude login

Sign in with your Max subscription account.

Step 7: GitHub Authentication¶

gh auth login

Optional: create a classic PAT for cross-owner repos and save to ~/.claude/executor-secrets.json.

Step 8: Discord + Slack Webhooks¶

# Discord (required)
cat > ~/.claude/discord-webhook.json << 'EOF'
{
  "webhook_url": "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
}
EOF
chmod 600 ~/.claude/discord-webhook.json

# Slack (optional)
cat > ~/.claude/slack-webhook.json << 'EOF'
{
  "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
}
EOF
chmod 600 ~/.claude/slack-webhook.json

Step 9: Agent Labels¶

./setup/setup-labels.sh

Creates six labels on each repo: agent-ready, agent-claimed, agent-failed, agent-opus, requires-human-approval, manual-merge.

Step 10: Install Executor¶

chmod +x executor.sh
./setup/install-executor.sh

Step 11: End-to-End Test¶

# Create test issue
gh issue create --repo Stig-Johnny/nutri-e \
  --title "test: verify mac-executor (safe to close)" \
  --label "agent-ready" \
  --body "Test issue. Just add a comment to CHANGELOG.md."

# Watch logs
tail -f ~/.claude/executor-logs/executor.log

# Health check
curl -s http://localhost:8090 | jq .

Maintenance¶

# Status
launchctl list | grep mac-executor
curl -s http://localhost:8090 | jq .

# Stop/Start
launchctl unload ~/Library/LaunchAgents/ai.invotek.mac-executor.plist
launchctl load ~/Library/LaunchAgents/ai.invotek.mac-executor.plist

# Update code
cd ~/repos/mac-executor && git pull origin main
launchctl unload ~/Library/LaunchAgents/ai.invotek.mac-executor.plist
launchctl load ~/Library/LaunchAgents/ai.invotek.mac-executor.plist

# After network change
sudo ./setup/install-pf.sh
./setup/verify-pf.sh