Skip to content

setup-mac.md

Latest commit

 

History

History
167 lines (118 loc) · 5.4 KB

setup-mac.md

File metadata and controls

167 lines (118 loc) · 5.4 KB
Raw

Setup: the Mac

For the agent reading this: You are running on the Mac. Work through these phases with the user. The Linux box should already be set up via setup-linux-box.md — you'll need a few values from it (the box's Syncthing Device ID, the SSH hostname, the username). Confirm each phase before moving on.

This guide connects your Mac to the box: Herdr remote for working on it, Syncthing for file mirroring, and an SSH-over-Cloudflare alias so you can reach the box from any network.

Placeholders — replace everywhere:

  • example.com → the user's domain
  • <user> → the box's Linux username
  • ssh-dev.example.com → the SSH hostname configured on the box's tunnel

Phase 0 — Prerequisites

# Install Homebrew if needed: https://brew.sh
brew install cloudflared syncthing

You'll also need your IDE and Herdr installed.

✅ Checkpoint: cloudflared --version and syncthing --version both work.

Phase 1 — SSH to the box through Cloudflare

You must not ssh ssh-dev.example.com directly — that name resolves to Cloudflare's edge, which won't answer raw SSH, and the connection just hangs. Instead, route SSH through the Cloudflare Access proxy.

Add to ~/.ssh/config on the Mac:

Host ai-box
    HostName ssh-dev.example.com
    User <user>
    ProxyCommand cloudflared access ssh --hostname %h

Then connect:

ssh ai-box

The first time, a browser opens for the Cloudflare Access login (your email). After that it's just ssh ai-box from anywhere.

✅ Checkpoint: ssh ai-box drops you into a shell on the box.

Phase 2 — Herdr in remote mode

Herdr is what makes the box feel local. Point it at the box over the SSH connection you just verified.

  1. Open Herdr and choose remote mode.
  2. Use the ai-box SSH host (the alias from Phase 1) as the connection target.
  3. Open your project folder on the box (e.g. ~/remote-projects/<project>).

Now commands, terminals, and agents you start run on the box, while you drive them from the Mac. Closing the Mac doesn't stop work running on the box (especially if you started it inside tmux — see the box guide).

Tip: keep long-running agents inside tmux on the box so a dropped connection or a closed laptop never kills them.

✅ Checkpoint: A command run via Herdr (e.g. hostname) reports the box's name, not the Mac's.

Phase 3 — Syncthing pairing (file mirror)

This keeps a project folder on the Mac identical to the one on the box, so edits the agent makes on the box appear in your Mac IDE within seconds.

Start Syncthing on the Mac:

brew services start syncthing
# Web UI: http://127.0.0.1:8384

Reach the box's Syncthing UI (it's localhost-only on the box) by tunneling it over your SSH alias:

ssh -L 8384:127.0.0.1:8384 ai-box
# now open http://127.0.0.1:8384 on the Mac — but note BOTH UIs use 8384.

If both UIs collide on 8384, forward the box to a different local port, e.g. ssh -L 8385:127.0.0.1:8384 ai-box and open http://127.0.0.1:8385 for the box.

Pair the two devices:

  1. In the Mac UI → Add Remote Device → paste the box's Device ID (from syncthing --device-id on the box).

  2. In the box UI → accept the Mac as a device.

  3. Share the folder: on the box, share ~/remote-projects; on the Mac, accept it and point it at your local projects folder (e.g. ~/remote-projects).

  4. Add a .stignore (both sides) to skip junk:

    node_modules
.git
dist
build
*.log
.DS_Store

✅ Checkpoint: Create a file on the box → it appears on the Mac within seconds (and vice-versa).

Phase 4 — View apps running on the box

Any dev server the box exposes via Caddy + the tunnel is reachable from the Mac (or any device) over HTTPS — no VPN, no same-network requirement:

https://review-dev.example.com      → box's localhost:3001
https://storybook-dev.example.com   → box's localhost:6006

Just open the URL in a browser. (You'll hit the Cloudflare Access login the first time per device.)

✅ Checkpoint: A browser on the Mac loads an app served from the box.

You're done — the daily loop

  1. Open IDE + Herdr on the Mac → connected to the box.
  2. Start an agent / build / dev server → it runs on the box.
  3. File changes mirror back via Syncthing → visible in your Mac IDE.
  4. Open https://<app>-dev.example.com to see running apps.
  5. Close the Mac whenever. The box keeps working. Reconnect later, anywhere.

Troubleshooting quick hits

  • ssh ai-box hangs → you're hitting the edge directly. Make sure the ProxyCommand cloudflared access ssh line is in ~/.ssh/config.
  • Browser login loops → your Cloudflare Access policy must allow your email; check Zero Trust → Access → Applications on the box's domain.
  • Files not syncing → both devices must show Connected in Syncthing; check the folder is shared and accepted on both sides.
  • App URL gives 502 → the dev server isn't running on the box, or it's bound to 127.0.0.1 instead of 0.0.0.0. See the box guide, Phase 4.
  • Syncthing UIs collide → forward the box UI to a different local port (8385).

⬅️ Box not set up yet? Start with setup-linux-box.md.