mac-reverse-ssh-bridge

name

mac-reverse-ssh-bridge

description

Prepare, verify, start, stop, and troubleshoot a safe reverse SSH workflow where a macOS machine dials out to a VPS and exposes only the Mac's localhost SSH service to the VPS loopback address. Use when Codex needs to help Tuzi/Hermes or another remote agent access a user's Mac without opening public router ports, including Remote Login checks, authorized_keys setup, reverse tunnel commands, autossh/launchd drafts, network/VPN diagnosis, and maintenance after reboot or network changes.

Mac Reverse SSH Bridge

Core Rule

Keep the Mac private. Use a Mac-initiated reverse SSH tunnel bound to the VPS loopback address:

ssh -N -R 127.0.0.1:<remote_port>:127.0.0.1:22 <vps_alias_or_user_host>

Never bind the reverse port to 0.0.0.0. Never open router ports, disable the macOS firewall, install invasive remote-control software, print private keys, print passwords, dump Keychain contents, or print full authorized_keys.

Quick Workflow

1. Identify the Mac user, hostname, macOS version, default shell, Remote Login state, local SSH listener, ~/.ssh permissions, VPS alias/host, and current network reachability.
2. Create ~/.ssh with 700 if needed, append only the provided public key to authorized_keys if absent, and set authorized_keys to 600.
3. If Remote Login is off or cannot be checked without sudo, do not enable it automatically; tell the user the exact sudo systemsetup -setremotelogin on command.
4. Test local SSH with ssh <mac_user>@127.0.0.1; on first use, tell the user to answer yes to the host-key prompt.
5. Verify Mac-to-VPS reachability with nc -vz <vps_host> 22 and ssh -o BatchMode=yes <vps_alias> true.
6. Start the tunnel only after local SSH and VPS SSH are reachable.
7. Verify from the VPS that 127.0.0.1:<remote_port> is listening and reachable.
8. Provide Tuzi's VPS-side command:

ssh -i /home/ubuntu/.ssh/tuzi_mac_access_ed25519 -p <remote_port> <mac_user>@127.0.0.1

Use The Helper Script

Prefer scripts/mac_reverse_ssh_bridge.sh for repeatable checks. Read or patch it only if the user needs behavior beyond its flags.

Common commands:

scripts/mac_reverse_ssh_bridge.sh diagnose --vps gc --remote-port 22222
scripts/mac_reverse_ssh_bridge.sh prepare --public-key '<public_key_line>'
scripts/mac_reverse_ssh_bridge.sh start --vps gc --remote-port 22222
scripts/mac_reverse_ssh_bridge.sh status --vps gc --remote-port 22222
scripts/mac_reverse_ssh_bridge.sh stop --remote-port 22222

The script redacts identity-file paths and never prints authorized_keys contents.

Troubleshooting

If direct IP or alias SSH times out before authentication:

• Check whether ssh -G <alias> points to the expected host, user, and port.
• Run nc -vz <host> 22; timeout means network path, VPN/proxy, ISP, or cloud security group, not Mac SSH auth.
• Check public egress with curl -4 https://ifconfig.me and look for tunnel interfaces such as utun*.
• Try disabling VPN/proxy, switching to a phone hotspot, or allowing the current egress IP in the cloud security group.

If SSH reaches the VPS but returns Permission denied (publickey):

• Use the configured SSH alias so the correct identity file and user are applied.
• Do not print the identity file or private key.

If -R fails:

• Keep the bind address as 127.0.0.1.
• Try remote ports 22223 or 22224 if 22222 is occupied.
• Keep ExitOnForwardFailure=yes so failed forwarding does not appear successful.

Persistence

Default to manual tunnels. They are safer and easier to reason about.

Offer autossh as the next step only after manual tunnel testing succeeds:

autossh -M 0 -N \
  -o ExitOnForwardFailure=yes \
  -o ServerAliveInterval=30 \
  -o ServerAliveCountMax=3 \
  -R 127.0.0.1:<remote_port>:127.0.0.1:22 \
  <vps_alias_or_user_host>

Only draft launchd plist content when asked. Do not install, bootstrap, enable, or start launchd persistence unless the user explicitly asks for that live change.

Reporting

Default to terminal output only. Write a report file only if the user asks for one.

When reporting status, include:

• Remote Login state
• Whether local SSH works
• Whether the public key is present, without printing full authorized_keys
• Whether the tunnel is running
• The Mac-side tunnel command
• The VPS-side Tuzi command
• Any required user action, with the minimum commands

Detailed Reference

For command templates and security notes, read references/workflow.md only when the task needs more detail than this file.