---
name: mac-mini-server
category: Infrastructure
description: >
  Turn a Mac Mini into a headless dev server with Tailscale VPN, Docker, SSH multiplexing, cron automation, and browser automation. Covers fresh install through production workloads. Field-tested patterns from running real automation 24/7.
---

# Mac Mini as a Headless Dev Server

## Why a Mac Mini

A Mac Mini sitting on your desk or in a closet gives you:
- A 24/7 server for crons, automations, and background jobs
- Native macOS for browser automation (no Linux font rendering issues)
- Docker Desktop for containerized services
- Tailscale for secure remote access from anywhere
- SSH for command-line access from any machine on your network

Cost: ~$600 one-time. No monthly hosting fees. Runs silent, draws 10W idle.

## The Architecture

```
Your Laptop (anywhere)
    │
    ├── SSH (LAN or Tailscale) ──→ Mac Mini
    │                                ├── Cron jobs (scheduled automation)
    │                                ├── Docker Desktop
    │                                │   └── Your containers
    │                                ├── Background services (APIs, workers)
    │                                ├── Chrome (headless CDP)
    │                                │   └── Browser automation
    │                                └── Node.js / Python scripts
    │
    └── Tailscale (VPN mesh) ──→ Mac Mini (from anywhere)
        └── HTTPS reverse proxy via Tailscale Serve
```

## Setup Order

Follow this order. Each step depends on the previous.

1. **Fresh Mac Install** — Xcode, Homebrew, Node.js, prevent sleep
2. **SSH Access** — Keys, multiplexing, file transfer patterns
3. **Tailscale** — VPN mesh, Serve mode for HTTPS
4. **Docker** — Desktop install, remote access patterns
5. **Background Services & Crons** — launchd, pm2, scheduled automation
6. **Browser Automation** — Headless Chrome via CDP

---

## Step 1: Fresh Mac Mini Install

### Prerequisites

- Mac Mini with macOS (Apple Silicon or Intel)
- Monitor + keyboard for initial setup (can remove after)
- Ethernet connection (more reliable than WiFi for a server)

### Install Sequence

```bash
# 1. Xcode Command Line Tools (required for everything)
xcode-select --install

# 2. Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add to PATH (Apple Silicon)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 3. Node.js via fnm (Fast Node Manager)
brew install fnm
echo 'eval "$(fnm env --use-on-cd)"' >> ~/.zshrc
source ~/.zshrc
fnm install --lts
fnm default lts-latest

# 4. Essential tools
brew install git gh tailscale

# 5. Docker Desktop
brew install --cask docker
# Open Docker Desktop once to complete setup, then it auto-starts on boot
```

### Prevent Sleep (Critical for a Server)

A sleeping Mac Mini drops SSH connections and stops crons.

```bash
# Disable sleep entirely
sudo pmset -a sleep 0
sudo pmset -a disablesleep 1
sudo pmset -a displaysleep 0

# Verify
pmset -g | grep sleep
# Should show: sleep 0, disablesleep 1

# Enable auto-restart after power failure
sudo pmset -a autorestart 1
```

### Enable Remote Login

```
System Preferences → General → Sharing → Remote Login → ON
```

Or via terminal:
```bash
sudo systemsetup -setremotelogin on
```

### Verify

```bash
node --version    # v20+ or v22+
npm --version     # 10+
git --version     # 2.39+
docker --version  # 24+
```

---

## Step 2: SSH Access

### Find Your Mac Mini on the Network

```bash
# From your laptop, on the same network:
dns-sd -B _ssh._tcp .
# Look for your Mac Mini's hostname

# Or use its .local address:
ssh youruser@Your-Mac-mini.local
```

### SSH Key Setup (passwordless login)

```bash
# On your laptop — generate key if you don't have one
ssh-keygen -t ed25519 -C "your-email@example.com"

# Copy to Mac Mini
ssh-copy-id youruser@Your-Mac-mini.local

# Test — should not ask for password
ssh youruser@Your-Mac-mini.local
```

### SSH Config (Connection Multiplexing)

Add to `~/.ssh/config` on your laptop:

```
Host mini
  HostName Your-Mac-mini.local    # or Tailscale IP
  User youruser
  ControlMaster auto              # reuse connections
  ControlPersist 600              # keep socket 10 minutes
  ServerAliveInterval 60          # prevent drops
  ForwardAgent yes                # forward SSH keys
```

Now `ssh mini` connects instantly. Subsequent SSH/SCP commands in the same 10-minute window reuse the socket — no new handshake.

### File Transfer Patterns

```bash
# Laptop → Mac Mini
scp ./file.txt mini:/path/to/destination/

# Mac Mini → Laptop
scp mini:/path/to/file.txt ./local/

# Sync a directory
rsync -avz --progress ./project/ mini:~/projects/project/

# Quick function (add to your .zshrc)
tomin() { scp "$1" mini:~/"${2:-.}"; }
frommin() { scp mini:~/"$1" "${2:-.}"; }
```

### Critical SSH Gotcha: Non-Interactive Shells

When you SSH to run a command (not an interactive session), `~/.zshrc` is NOT sourced. This means `node`, `npm`, `brew` — anything installed via Homebrew — won't be on PATH.

```bash
# This FAILS — node not found
ssh mini 'node --version'

# This WORKS — source zshrc first
ssh mini 'source ~/.zshrc && node --version'

# For scripts, always start with:
#!/bin/zsh
source ~/.zshrc
# ... rest of script
```

This is the #1 gotcha with Mac Mini automation. Every cron, every remote command must source the shell config.

---

## Step 3: Tailscale (Remote Access from Anywhere)

Tailscale creates a VPN mesh between your devices. Your Mac Mini gets a stable IP accessible from anywhere — coffee shop, client site, phone.

### Install

```bash
brew install tailscale

# Start and authenticate
sudo tailscale up
# Opens browser for auth — sign in with your Tailscale account
```

### Find Your Tailscale IP

```bash
tailscale ip -4
# Example: 100.x.y.z
```

Update your SSH config to use this IP for remote access:

```
Host mini
  HostName 100.x.y.z    # Tailscale IP — works from anywhere
  User youruser
  ControlMaster auto
  ControlPersist 600
  ServerAliveInterval 60
```

### Tailscale Serve (HTTPS Reverse Proxy)

Expose local services over HTTPS with a valid cert — no Nginx, no Let's Encrypt, no port forwarding.

```bash
# Expose a local service (e.g., port 3000) over HTTPS
sudo tailscale serve https / http://127.0.0.1:3000

# Your service is now at:
# https://your-mac-mini.tailnet-name.ts.net/

# Expose with a path prefix
sudo tailscale serve https /api http://127.0.0.1:8080

# Check what's being served
tailscale serve status
```

**Serve vs Funnel:**
- **Serve** — accessible only to devices on your Tailscale network (private)
- **Funnel** — accessible from the public internet (use sparingly)

```bash
# Public access (careful!)
sudo tailscale funnel https / http://127.0.0.1:3000

# Private only (recommended)
sudo tailscale serve https / http://127.0.0.1:3000
```

### Tailscale Gotchas

- Tailscale must be running on BOTH devices (laptop + Mac Mini)
- If the Mac Mini sleeps, Tailscale disconnects (see Step 1: Prevent Sleep)
- First connection after wake takes 2-3 seconds to re-establish
- `tailscale status` shows all connected devices

---

## Step 4: Docker on Mac Mini

### Setup

Docker Desktop should already be installed from Step 1. Two gotchas for headless use:

**Gotcha 1: Docker must be running.** Docker Desktop needs to be open (or set to start on login). Without the GUI session, the Docker daemon doesn't start.

```
Docker Desktop → Settings → General → Start Docker Desktop when you log in → ON
```

**Gotcha 2: Keychain access over SSH.** Docker Desktop stores credentials in the macOS keychain, which may not be accessible over SSH.

```bash
# If docker commands fail with keychain errors over SSH:
# Option 1: Use docker cp + docker restart instead of docker compose up --build
docker cp ./file.js container-name:/app/file.js
docker restart container-name

# Option 2: Pre-build on the Mac Mini with a screen session
ssh mini
screen -S docker
docker compose up --build
# Ctrl-A, D to detach
```

### Common Docker Patterns for Mac Mini

```bash
# Run a service in the background
docker compose up -d

# Check running containers
docker ps

# View logs
docker logs container-name -f --tail 50

# Deploy a file change without full rebuild
docker cp ./updated-file.js my-container:/app/updated-file.js
docker restart my-container
```

---

## Step 5: Background Services & Crons

A headless Mac Mini shines as a host for background services, scheduled jobs, and long-running processes.

### Option A: launchd (macOS Native)

launchd is the macOS init system. It starts services on boot and restarts them if they crash.

```bash
# Create a plist for your service
cat > ~/Library/LaunchAgents/com.myapp.api.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.myapp.api</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/node</string>
        <string>/Users/youruser/projects/myapp/server.js</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/youruser/logs/myapp.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/youruser/logs/myapp-error.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
        <key>PORT</key>
        <string>8080</string>
    </dict>
</dict>
</plist>
EOF

# Load and start the service
launchctl load ~/Library/LaunchAgents/com.myapp.api.plist

# Check status
launchctl list | grep myapp

# Stop and unload
launchctl unload ~/Library/LaunchAgents/com.myapp.api.plist
```

**Key launchd gotcha:** Use absolute paths for everything — the binary, the script, log files. launchd does not load your shell profile.

### Option B: pm2 (Node.js Process Manager)

Simpler than launchd for Node.js services:

```bash
npm install -g pm2

# Start a service
pm2 start server.js --name api

# Start a Python script
pm2 start script.py --name worker --interpreter python3

# Auto-start on boot
pm2 startup    # generates a launchd config
pm2 save       # saves current process list

# Management
pm2 list              # see all processes
pm2 logs api          # tail logs
pm2 restart api       # restart a process
pm2 monit             # real-time dashboard
```

### Cron Jobs (Scheduled Automation)

Use crontab for scheduled tasks:

```bash
# Edit crontab
crontab -e

# Example: run a script every day at 9am
0 9 * * * /bin/zsh -c 'source ~/.zshrc && node ~/scripts/daily-report.js >> ~/logs/daily-report.log 2>&1'

# Example: health check every 5 minutes
*/5 * * * * /bin/zsh -c 'source ~/.zshrc && curl -sf http://localhost:8080/health || pm2 restart api' >> ~/logs/healthcheck.log 2>&1
```

### Cron Script Pattern

Every cron script should follow this pattern:

```bash
#!/bin/zsh
source ~/.zshrc    # CRITICAL — makes node/npm/docker available

# Your automation logic here
node /path/to/script.js

# Or run a Python script
python3 /path/to/automation.py

# Or interact with Docker
docker exec my-container /app/run-task.sh
```

### Background Service Gotchas

- Cron scripts MUST source `~/.zshrc` (see SSH gotcha in Step 2)
- launchd plists must use absolute paths — no `~`, no `$HOME`
- Log everything — background jobs fail silently without logs
- Set generous timeouts for long-running tasks (API calls, AI processing)
- Use `pm2 startup` to survive reboots — it generates a launchd plist under the hood
- If Mac Mini sleeps, all crons and services stop (see Step 1: Prevent Sleep)

---

## Step 6: Browser Automation (Headless Chrome)

Run browser automation on the Mac Mini for web scraping, testing, or scheduled interactions with web apps.

### Setup Chrome CDP

```bash
# Install Chrome if not present
brew install --cask google-chrome

# Launch Chrome with CDP (Chrome DevTools Protocol) enabled
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --no-first-run \
  --disable-background-timer-throttling \
  --disable-backgrounding-occluded-windows &

# Verify CDP is accessible
curl -s http://localhost:9222/json/version | python3 -m json.tool
```

### Using Playwright or Puppeteer

Connect your automation framework to the running Chrome instance:

```javascript
// Playwright — connect to existing Chrome
const { chromium } = require('playwright');
const browser = await chromium.connectOverCDP('http://localhost:9222');
const page = browser.contexts()[0].pages()[0];
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });

// Puppeteer — connect to existing Chrome
const puppeteer = require('puppeteer');
const browser = await puppeteer.connect({
  browserURL: 'http://localhost:9222'
});
const page = (await browser.pages())[0];
await page.goto('https://example.com');
```

### Session Persistence

Save login cookies so cron jobs don't need to re-authenticate:

```javascript
// Save cookies after manual login
const cookies = await page.context().cookies();
fs.writeFileSync('cookies.json', JSON.stringify(cookies));

// Restore cookies in a cron script
const cookies = JSON.parse(fs.readFileSync('cookies.json'));
await page.context().addCookies(cookies);
await page.goto('https://app.example.com/dashboard');
```

### Auto-Start Chrome on Boot

Create a launchd plist so Chrome with CDP is always available:

```bash
cat > ~/Library/LaunchAgents/com.chrome.cdp.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.chrome.cdp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</string>
        <string>--remote-debugging-port=9222</string>
        <string>--no-first-run</string>
        <string>--disable-background-timer-throttling</string>
        <string>--disable-backgrounding-occluded-windows</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.chrome.cdp.plist
```

### Headless Gotchas

- Chrome must be running BEFORE your automation script tries to connect
- CDP port 9222 is only accessible locally (not exposed via Tailscale unless you set up a serve)
- Login sessions expire -- build re-login flows into your automation scripts
- Some sites detect headless browsers -- use the full Chrome binary, not Puppeteer's bundled Chromium
- On a headless Mac Mini (no display), Chrome still runs fine -- macOS has a virtual framebuffer

---

## Useful Shell Functions

Add these to the Mac Mini's `~/.zshrc` or your laptop's `~/.zshrc`:

```bash
# SSH to Mac Mini and attach tmux session
miniwork() {
  local session="${1:-main}"
  ssh mini -t "tmux attach-session -t $session 2>/dev/null || tmux new-session -s $session"
}

# Quick Mac Mini status check
ministatus() {
  ssh mini 'source ~/.zshrc && echo "=== Uptime ===" && uptime && echo "\n=== Disk ===" && df -h / && echo "\n=== Memory ===" && vm_stat | head -5 && echo "\n=== Docker ===" && docker ps --format "table {{.Names}}\t{{.Status}}" 2>/dev/null && echo "\n=== Ports ===" && lsof -i -P -n 2>/dev/null | grep LISTEN | awk "{print \$1, \$9}" | sort -u'
}

# Transfer file to Mac Mini
tomin() { scp "$1" mini:~/"${2:-.}"; }

# Get file from Mac Mini
frommin() { scp mini:~/"$1" "${2:-.}"; }

# Tail pm2 logs
minilogs() {
  ssh mini 'source ~/.zshrc && pm2 logs --lines 50'
}
```

---

## Verification Checklist

After setup, verify everything works:

```bash
# From your laptop:
ssh mini 'source ~/.zshrc && node --version'       # Node.js
ssh mini 'docker ps'                                 # Docker
ssh mini 'tailscale status'                          # Tailscale
ssh mini 'source ~/.zshrc && pm2 list'               # Background services
ssh mini 'curl -s http://localhost:9222/json/version' # Chrome CDP

# From outside your network (via Tailscale):
ssh youruser@100.x.y.z 'echo "Tailscale works"'    # Remote SSH
curl https://your-mac-mini.tailnet.ts.net/           # Tailscale Serve
```

---

## Anti-Patterns

| Wrong | Right |
|-------|-------|
| Let Mac Mini sleep | `sudo pmset -a sleep 0 -a disablesleep 1` |
| Run commands via SSH without sourcing zshrc | Always `source ~/.zshrc` first |
| Use `docker compose up --build` over SSH | Use `docker cp` + `docker restart` |
| Expose ports directly to the internet | Use Tailscale Serve for HTTPS |
| Store credentials in scripts | Use environment variables or secret managers |
| Assume WiFi is reliable for a server | Use Ethernet |
| Skip the ControlMaster SSH config | Multiplexing makes everything instant |
| Run crons as root | Run as your user account |

# Hard-Won Lessons

Every lesson here was learned from real deployments. These aren't theoretical — they're fixes for problems that cost hours to debug.

---

## SSH & Shell (The #1 Pain Point)

### Always source zshrc for remote commands

Non-interactive SSH doesn't load your shell config. Node, npm, Docker, and anything installed via Homebrew won't be on PATH.

```bash
# WRONG — "command not found" for everything
ssh user@mini 'node --version'
ssh user@mini 'docker ps'

# RIGHT — source zshrc first
ssh user@mini 'source ~/.zshrc 2>/dev/null; node --version'
```

### Suppress SSH noise

Double-sided `2>/dev/null` keeps output clean:

```bash
# Inner: suppresses oh-my-zsh theme noise
# Outer: suppresses SSH connection banners
ssh user@mini 'source ~/.zshrc 2>/dev/null; YOUR_COMMAND 2>&1' 2>/dev/null
```

### Heredocs with backticks fail via SSH

The shell interprets backticks before they reach the remote host. Write locally, then copy:

```bash
# WRONG — backticks get interpreted as command substitution
ssh user@mini 'cat > ~/file.md << EOF
```bash
code here
```
EOF'

# RIGHT — write locally, scp over
cat > /tmp/file.md << 'LOCALEOF'
Content with `backticks` and "quotes" and $variables
LOCALEOF
scp /tmp/file.md user@mini:~/destination/file.md
```

### Why this happens

SSH runs commands in a non-login, non-interactive shell. macOS uses zsh, and `~/.zshrc` is only sourced for interactive shells. Only `~/.ssh/environment` is read for non-interactive SSH commands.

### Permanent fix

```bash
# On the Mac Mini — add Homebrew to SSH environment:
echo 'PATH=/opt/homebrew/bin:/usr/local/bin:$PATH' >> ~/.ssh/environment

# Enable in sshd_config:
sudo sed -i '' 's/#PermitUserEnvironment no/PermitUserEnvironment yes/' /etc/ssh/sshd_config
sudo launchctl stop com.openssh.sshd
sudo launchctl start com.openssh.sshd
```

---

## Password & Credential Handling

### Special characters in passwords

`printf` and `echo` mangle `%`, `!`, `&`, `@` in different ways. Use a heredoc with single-quoted delimiter (prevents all expansion):

```bash
# WRONG — printf mangles special chars
printf "%s" "MyP@ssw0rd!With%Special&"

# RIGHT — single-quoted heredoc prevents all interpolation
cat > /tmp/pw.txt << 'PWEOF'
MyP@ssw0rd!With%Special&
PWEOF
```

### Reading passwords in scripts

```bash
PW=$(cat /tmp/pw.txt)
# Use $PW in your commands — it preserves all special characters
```

### Never commit credentials

- Use `~/.ssh/environment` for PATH-like config
- Use a secrets manager or encrypted file for API keys
- Delete temp files after use: `rm /tmp/pw.txt`

---

## Docker Over SSH

Docker Desktop requires the macOS keychain, which isn't available in non-interactive SSH sessions.

### The `docker compose up --build` problem

Running `docker compose up --build` over SSH fails with keychain errors. The keychain requires a GUI session.

### Workaround: docker cp + restart

Deploy changes without rebuilding:

```bash
# 1. Copy updated file to Mac Mini
scp server.js user@mini:~/projects/myapp/server.js

# 2. Copy into running container + restart
ssh user@mini 'source ~/.zshrc 2>/dev/null; \
  docker cp ~/projects/myapp/server.js my-container:/app/server.js && \
  docker restart my-container'
```

This is faster than a full rebuild anyway — seconds instead of minutes.

### Docker binary not on PATH

Docker is at `/usr/local/bin/docker`, which may not be on the non-interactive SSH PATH:

```bash
ssh user@mini 'export PATH=/usr/local/bin:$PATH; docker ps'
```

Or use the zshrc sourcing pattern (preferred):
```bash
ssh user@mini 'source ~/.zshrc 2>/dev/null; docker ps'
```

---

## Headless vs Screen-Required Operations

### Can do headless (over SSH)

- Docker operations (with cp+restart workaround)
- All server management (pm2, systemd, etc.)
- Git operations
- File editing
- Chrome DevTools Protocol (CDP) automation
- Cron management

### Requires Mac Mini screen (at least once)

- `xcode-select --install` (pops a GUI dialog)
- Tailscale first login (opens browser for OAuth)
- Docker Desktop first launch (macOS permissions)
- Any app that needs macOS Keychain access

### Screen access options when Mac Mini is headless

1. **VNC/Screen Sharing**: System Settings → General → Sharing → Screen Sharing → ON
2. **Tailscale VNC**: Access via Tailscale network
3. **Physical access**: HDMI cable + keyboard for initial setup
4. **Apple Remote Desktop**: Enterprise option

---

## Reverse Engineering Web APIs

When a service has no public API, you can often find their internal API:

### Step 1: Extract __NEXT_DATA__

Most Next.js sites expose server-rendered data in a script tag:

```javascript
JSON.stringify(window.__NEXT_DATA__.props.pageProps)
```

This gives you the data structure they use — field names, IDs, formats.

### Step 2: Inspect network requests

Use browser DevTools or a proxy to capture actual API calls. Note:
- Base URL pattern
- Auth headers (Bearer token, cookies, custom headers)
- Request/response format

### Step 3: Decompile webpack bundles

Search the page source for fetch calls, API base URLs, or method names like `createPost`. The bundled JavaScript often contains the full API client.

### Step 4: Test with minimal payload

Start with the bare minimum fields and add until it works. The first attempt usually fails — the error message tells you what's missing.

### Step 5: Check for WAF/CDN protection

If you get 403 errors from CloudFront or Cloudflare:

| Protection | Detection | Solution |
|-----------|-----------|----------|
| AWS WAF | `window.AwsWafIntegration` exists | Make API calls from within the browser context |
| Cloudflare Challenge | `window.__cf_chl_opt` exists | Use browser automation instead of curl |
| Custom fetch wrappers | Page overrides `window.fetch` | Find and use their wrapper function |

The key insight: if direct curl/fetch calls get blocked, make the calls from within a browser session that already has the WAF token cookies.

---

## Cron Jobs on Mac Mini

### Crons stop when Mac Mini sleeps

This is the #1 reason crons fail silently. Verify sleep is disabled:

```bash
pmset -g | grep sleep
# Should show: sleep 0, disablesleep 1
```

If not:
```bash
sudo pmset -a sleep 0 disablesleep 1 displaysleep 0
```

### Cron scripts must source the shell

Every cron script starts the same way:

```bash
#!/bin/zsh
source ~/.zshrc 2>/dev/null
# ... rest of script
```

Without this, nothing works — node, npm, docker, custom tools are all missing.

### Set generous timeouts

Remote API calls, browser automation, and AI processing can take minutes. Default 60-second timeouts will cut off long operations.

### Log everything

Crons fail silently. Redirect output to a log file:

```bash
# In crontab:
0 9 * * * /path/to/script.sh >> ~/logs/myjob.log 2>&1
```

---

## File Transfer Patterns

### Simple copy

```bash
# Laptop → Mac Mini
scp ./file.txt user@mini:~/destination/

# Mac Mini → Laptop
scp user@mini:~/path/to/file.txt ./

# Directory sync
rsync -avz --progress ./project/ user@mini:~/projects/project/
```

### Files with special characters

Backticks, quotes, and dollar signs in file content get mangled by SSH. Always write locally and copy:

```bash
# Write file locally with SINGLE-QUOTED delimiter
cat > /tmp/config.json << 'EOF'
{"key": "value with $pecial chars & stuff"}
EOF

# Copy to Mac Mini
scp /tmp/config.json user@mini:~/config.json
```

### Shell helper functions

```bash
# Add to ~/.zshrc
tomin() { scp "$1" mini:~/"${2:-.}"; }
frommin() { scp mini:~/"$1" "${2:-.}"; }
```

---

## Network Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Connection refused" on SSH | Remote Login not enabled | System Settings → Sharing → Remote Login → ON |
| "Permission denied (publickey)" | SSH key not copied | `ssh-copy-id user@mini` |
| Mac Mini unreachable after move | IP changed | Use `.local` hostname or Tailscale IP |
| "Host key verification failed" | macOS reinstalled | `ssh-keygen -R hostname` |
| Commands fail with "not found" | PATH not loaded | Source `~/.zshrc` (see SSH section) |
| Docker commands fail | Keychain not accessible | Use `docker cp` + `docker restart` pattern |
| Crons stop running | Mac Mini asleep | Disable sleep with `pmset` |

# Tailscale Patterns

Advanced Tailscale patterns for running services on a headless Mac Mini.

---

## Three Access Modes

| Mode | Who can access | URL format | Use case |
|------|---------------|------------|----------|
| **Off** | Local network only | `192.168.x.x:port` | Development |
| **Serve** | Your Tailnet devices only | `https://hostname.tailnet.ts.net` | Private services |
| **Funnel** | Anyone on the internet | `https://hostname.tailnet.ts.net` | Webhooks, public APIs |

**Start with Serve.** Upgrade to Funnel only when you need external access (webhooks, Slack bots, etc.).

---

## Serve Mode (Private HTTPS)

Expose a local service to your Tailnet with a valid HTTPS certificate — no Nginx, no Let's Encrypt, no port forwarding.

```bash
# Expose port 3000 over HTTPS
sudo tailscale serve https / http://127.0.0.1:3000

# Now accessible from any device on your Tailnet:
# https://your-mac-mini.tailnet-name.ts.net/

# Check what's being served
tailscale serve status

# Stop serving
sudo tailscale serve https / off
```

### Multiple services on one hostname

Use path prefixes to expose multiple services on the same hostname:

```bash
# API on /api
sudo tailscale serve https /api http://127.0.0.1:8080

# Dashboard on /dashboard
sudo tailscale serve https /dashboard http://127.0.0.1:3000

# Webhook receiver on /webhooks
sudo tailscale serve https /webhooks http://127.0.0.1:9000
```

All three are accessible at:
```
https://your-mac-mini.tailnet.ts.net/api
https://your-mac-mini.tailnet.ts.net/dashboard
https://your-mac-mini.tailnet.ts.net/webhooks
```

### Static file serving

Serve a directory directly:

```bash
# Serve a built Next.js export
sudo tailscale serve https /docs /path/to/docs/out
```

---

## Funnel Mode (Public HTTPS)

Makes your service accessible from the public internet. Required for:
- Slack bot webhooks
- GitHub webhooks
- Any external service that needs to call your Mac Mini

```bash
# Expose publicly
sudo tailscale funnel https / http://127.0.0.1:3000

# Verify it's active
tailscale serve status
# Should show: Funnel on: https://your-hostname.tailnet.ts.net
```

### Funnel requirements

1. **HTTPS must be enabled** in Tailscale admin console (Settings → DNS → Enable HTTPS)
2. **ACLs must allow funnel** for the node
3. **Only ports 443, 8443, 10000** are supported for Funnel
4. The local service port is proxied through Tailscale's HTTPS on port 443

### When to use Funnel vs a cloud service

| Use Funnel | Use a cloud service |
|-----------|-------------------|
| Webhook receiver (Slack, GitHub) | High-availability production API |
| Development/staging preview | Customer-facing service |
| Personal automation endpoint | Service that needs 99.9% uptime |
| Internal tools shared with a team | Anything with SLA requirements |

Funnel depends on your Mac Mini being awake and connected. If it sleeps or loses internet, the URL goes down.

---

## SSH Over Tailscale

Tailscale gives every device a stable IP that works from anywhere:

```bash
# Find your Tailscale IP
tailscale ip -4
# Example: 100.x.y.z

# SSH from anywhere
ssh user@100.x.y.z

# Or use the Tailscale hostname
ssh user@your-mac-mini.tailnet-name.ts.net
```

### SSH config for Tailscale

```
Host mini
  HostName 100.x.y.z           # Tailscale IP — works from anywhere
  User youruser
  ControlMaster auto            # Connection reuse
  ControlPersist 600            # Keep socket for 10 minutes
  ServerAliveInterval 60        # Prevent drops
  ForwardAgent yes              # Forward SSH keys
```

### Why Tailscale IP over .local hostname

| | `.local` hostname | Tailscale IP |
|-|-------------------|-------------|
| Works on same network | Yes | Yes |
| Works from coffee shop | No | Yes |
| Works from phone | No | Yes |
| Works on Windows | Needs Bonjour | Yes |
| Survives IP changes | Yes | Yes |

---

## Multi-Service Architecture

A Mac Mini can run many services behind Tailscale:

```
https://your-mini.tailnet.ts.net/
    ├── /api         → Express server on port 8080
    ├── /dashboard    → Next.js export on port 3000
    ├── /webhooks     → Webhook receiver on port 9000
    └── /grafana      → Grafana on port 3100
```

### Setting this up

```bash
# Start your services
node api/server.js &           # port 8080
npx serve ./dashboard &         # port 3000
node webhooks/server.js &       # port 9000
docker run -d -p 3100:3000 grafana/grafana  # port 3100

# Wire them through Tailscale
sudo tailscale serve https /api http://127.0.0.1:8080
sudo tailscale serve https /dashboard http://127.0.0.1:3000
sudo tailscale serve https /webhooks http://127.0.0.1:9000
sudo tailscale serve https /grafana http://127.0.0.1:3100
```

### Persistent across reboots

Tailscale Serve config persists. Your services need to restart on boot:

```bash
# Option 1: launchd (macOS native)
# Create ~/Library/LaunchAgents/com.myapp.api.plist

# Option 2: pm2 (Node.js process manager)
npm install -g pm2
pm2 start api/server.js --name api
pm2 startup    # generates launchd config
pm2 save       # saves current process list
```

---

## Troubleshooting

### "Tailscale is stopped"

```bash
# macOS — relaunch the app
open /Applications/Tailscale.app

# Or from CLI
tailscale up
```

### Can't reach Mac Mini from another device

1. Check both devices are on the same Tailnet: `tailscale status`
2. Check Mac Mini firewall: System Settings → Network → Firewall
3. Try the Tailscale IP directly: `ping 100.x.y.z`
4. Check the service is actually running: `curl http://localhost:3000`

### Funnel not working

1. Enable HTTPS in Tailscale admin console (Settings → DNS)
2. Check ACLs allow funnel for this node
3. Verify funnel is active: `tailscale serve status`
4. Remember: only ports 443, 8443, 10000 work with Funnel
5. Test from outside your network (phone on cellular, not WiFi)

### Tailscale reconnection after sleep

If the Mac Mini wakes from sleep, Tailscale takes 2-3 seconds to reconnect. This is usually transparent, but time-sensitive webhooks might miss this window.

Fix: Don't let the Mac Mini sleep (see SKILL.md, Step 1: Prevent Sleep).

### Device shows "offline" in Tailscale admin

- Check the Mac Mini has internet
- Check Tailscale app is running
- Try `tailscale up` to force reconnect
- Check for macOS updates that may have disabled background apps

---

## Security Considerations

### Serve mode is safe by default

Only devices on your Tailnet can access Serve endpoints. Your Tailnet requires authentication — no anonymous access.

### Funnel exposes you to the internet

Anyone with the URL can reach your service. Treat Funnel endpoints like any public-facing server:
- Add authentication to your service
- Rate-limit endpoints
- Don't expose databases or admin panels
- Monitor access logs

### Tailscale ACLs

Use ACLs (Access Control Lists) in the Tailscale admin console to restrict which devices can access which services. Default is "allow all within Tailnet" — fine for personal use, tighten for teams.