Skip to main content

​
Running the Fased Agent macOS app with a remote gateway

The macOS app ships as FasedAgent.app. This guide shows the SSH-tunnel path for reaching a gateway on another host without exposing the raw gateway port publicly.

​
Overview

​
Quick Setup

​
Step 1: Add SSH Config

Edit ~/.ssh/config and add: 
Host remote-gateway
    HostName <REMOTE_IP>          # e.g., 172.27.187.184
    User <REMOTE_USER>            # e.g., jefferson
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa
Replace <REMOTE_IP> and <REMOTE_USER> with your values.

​
Step 2: Copy SSH Key

Copy your public key to the remote machine (enter password once): 
ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

​
Step 3: Set Gateway Token

launchctl setenv FASED_GATEWAY_TOKEN "<your-token>"

​
Step 4: Start SSH Tunnel

ssh -N remote-gateway &

​
Step 5: Restart the macOS app

# Quit the app (⌘Q), then reopen the current bundle:
open /path/to/FasedAgent.app
The app will now connect to the remote gateway through the SSH tunnel.

​
Auto-Start Tunnel on Login

To have the SSH tunnel start automatically when you log in, create a Launch Agent.

​
Create the PLIST file

Save this as ~/Library/LaunchAgents/ai.fased.ssh-tunnel.plist: 
<?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>ai.fased.ssh-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>remote-gateway</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

​
Load the Launch Agent

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.fased.ssh-tunnel.plist
The tunnel will now:
  • Start automatically when you log in
  • Restart if it crashes
  • Keep running in the background
Legacy note: remove any leftover com.fased.ssh-tunnel LaunchAgent if present.

​
Troubleshooting

Check if tunnel is running: 
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789
Restart the tunnel: 
launchctl kickstart -k gui/$UID/ai.fased.ssh-tunnel
Stop the tunnel: 
launchctl bootout gui/$UID/ai.fased.ssh-tunnel

​
How It Works

ComponentWhat It Does
LocalForward 18789 127.0.0.1:18789Forwards local port 18789 to remote port 18789
ssh -NSSH without executing remote commands (just port forwarding)
KeepAliveAutomatically restarts tunnel if it crashes
RunAtLoadStarts tunnel when the agent loads
The macOS app connects to ws://127.0.0.1:18789 on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the gateway is running. Keep the remote gateway on loopback unless you intentionally switch to a tailnet bind or trusted proxy design.