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 while keeping the raw gateway port closed to the public internet.

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.

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

Component	What It Does
`LocalForward 18789 127.0.0.1:18789`	Forwards local port 18789 to remote port 18789
`ssh -N`	SSH without executing remote commands (just port forwarding)
`KeepAlive`	Automatically restarts tunnel if it crashes
`RunAtLoad`	Starts 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.

Gateway overview

Run and repair

Configuration

Secrets and auth

Networking

Security and sandboxing

Protocols and APIs

Web interfaces

Security evidence

Remote Gateway Setup

Running the Fased Agent macOS app with a remote gateway

Overview

Quick Setup

Step 1: Add SSH Config

Step 2: Copy SSH Key

Step 3: Set Gateway Token

Step 4: Start SSH Tunnel

Step 5: Restart the macOS app

Create the PLIST file

Load the Launch Agent

Troubleshooting

How It Works

​Running the Fased Agent macOS app with a remote gateway

​Overview

​Quick Setup

​Step 1: Add SSH Config

​Step 2: Copy SSH Key

​Step 3: Set Gateway Token

​Step 4: Start SSH Tunnel

​Step 5: Restart the macOS app

​Auto-Start Tunnel on Login

​Create the PLIST file

​Load the Launch Agent

​Troubleshooting

​How It Works

Running the Fased Agent macOS app with a remote gateway

Overview

Quick Setup

Step 1: Add SSH Config

Step 2: Copy SSH Key

Step 3: Set Gateway Token

Step 4: Start SSH Tunnel

Step 5: Restart the macOS app

Auto-Start Tunnel on Login

Create the PLIST file

Load the Launch Agent

Troubleshooting

How It Works