This document lists bash scripts Outer Loop runs on the target machine: the SSH server for normal server sessions, and this Mac for localhost sessions.

Bundled Target-Side Executables

Executable	Where it runs	Bundled artifact	Source code
outer-socket-bridge	Remote Linux SSH hosts, uploaded on demand for Unix socket forwarding	OuterLoop/Resources/LinuxHelpers/outer-socket-bridge-linux-x86_64	OuterLoop/RootBridgeHelper/outer-socket-bridge.c
outer-socket-bridge	Remote Linux SSH hosts, uploaded on demand for Unix socket forwarding	OuterLoop/Resources/LinuxHelpers/outer-socket-bridge-linux-aarch64	OuterLoop/RootBridgeHelper/outer-socket-bridge.c
outer-socket-bridge	Localhost sessions, when opening root-owned Unix sockets	Built macOS helper copied into Outer Loop.app/Contents/MacOS/outer-socket-bridge	OuterLoop/RootBridgeHelper/outer-socket-bridge.c

Current bundled Linux helper hashes:

64ce381eb8d36eb18dfc0e9d4c47fef2160a84ad036bb9e7ac5e768dad281d8a  OuterLoop/Resources/LinuxHelpers/outer-socket-bridge-linux-x86_64
97a6e5fe3a04fed82be981a8b596c9f8a3e7d718d25f74b2bded838db68f3dbf  OuterLoop/Resources/LinuxHelpers/outer-socket-bridge-linux-aarch64

Build script for the Linux helper artifacts:

OuterLoop/Scripts/build_socket_bridge_helpers.sh

Remote SSH Session Commands

These commands are executed through SSH exec channels on the remote server. Runtime substitutions are written as uppercase placeholder tokens.

Resolve Home Directory

Used when the app needs the remote home directory.

printf %s "$HOME"

Detect System Profile

Used to identify the remote operating system and hardware profile.

emit() {
    key="$1"
    shift
    value="$*"
    if [ -n "$value" ]; then
        printf '%s=%s\n' "$key" "$value"
    fi
}

emit_file() {
    key="$1"
    path="$2"
    if [ -r "$path" ]; then
        value="$(tr -d '\000' < "$path" 2>/dev/null | head -n 1)"
        emit "$key" "$value"
    fi
}

emit kernel "$(uname -s 2>/dev/null)"
emit machine "$(uname -m 2>/dev/null)"

if [ -r /etc/os-release ]; then
    awk -F= '
        function clean(value) {
            gsub(/^"/, "", value)
            gsub(/"$/, "", value)
            return value
        }
        $1 == "ID" { print "osID=" clean($2) }
        $1 == "ID_LIKE" { print "osIDLike=" clean($2) }
        $1 == "NAME" { print "osName=" clean($2) }
    ' /etc/os-release 2>/dev/null
fi

emit_file deviceModel /proc/device-tree/model
emit_file sysVendor /sys/class/dmi/id/sys_vendor
emit_file productName /sys/class/dmi/id/product_name
emit_file boardVendor /sys/class/dmi/id/board_vendor
emit_file biosVendor /sys/class/dmi/id/bios_vendor

if command -v sw_vers >/dev/null 2>&1; then
    emit osName "$(sw_vers -productName 2>/dev/null)"
fi
if command -v sysctl >/dev/null 2>&1; then
    emit macModel "$(sysctl -n hw.model 2>/dev/null)"
fi

Probe Default Outer Shell Socket

Used to discover an already-running default Outer Shell instance.

uid="$(id -u)"
if [ "$uid" = "0" ]; then
    runtime_dir="/run"
else
    runtime_dir="${XDG_RUNTIME_DIR:-/run/user/$uid}"
fi
socket_path="$runtime_dir/org.outershell.OuterShell"
if [ -S "$socket_path" ]; then
    printf '%s\n' "$socket_path"
fi

Install Default Outer Shell

First, Outer Loop detects the remote architecture:

uname -m

Then Outer Loop downloads install.sh and the matching Linux archive from https://outershell.org/outer-shell/latest on the local Mac, streams both files to the remote command on stdin, and runs this generated command. SCRIPT_BYTE_COUNT and ARCHIVE_BYTE_COUNT are exact byte counts for the streamed payload.

set -eu
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
script="$tmp/install.sh"
archive="$tmp/outer-shell.tar.gz"
read_exact() {
    out="$1"
    total="$2"
    : > "$out"
    blocks=$((total / 65536))
    remainder=$((total % 65536))
    if [ "$blocks" -gt 0 ]; then
        dd of="$out" bs=65536 count="$blocks" iflag=fullblock 2>/dev/null
    fi
    if [ "$remainder" -gt 0 ]; then
        dd bs=1 count="$remainder" iflag=fullblock 2>/dev/null >> "$out"
    fi
    actual="$(wc -c < "$out" | tr -d ' ')"
    if [ "$actual" != "$total" ]; then
        echo "Outer Shell upload was truncated" >&2
        exit 1
    fi
}
read_exact "$script" SCRIPT_BYTE_COUNT
read_exact "$archive" ARCHIVE_BYTE_COUNT
chmod 0755 "$script"
OUTERSHELL_INSTALL_ARCHIVE="$archive" sh "$script"
uid="$(id -u)"
if [ "$uid" = "0" ]; then
    runtime_dir="/run"
    allowlist_dir="/etc/outerloop"
    allowlist_path="$allowlist_dir/http-unix.allow"
    allowlist_entry="%T/org.outershell.OuterShell"
    install -d -m 0755 "$allowlist_dir"
    touch "$allowlist_path"
    chown root:root "$allowlist_path"
    chmod 0644 "$allowlist_path"
else
    runtime_dir="${XDG_RUNTIME_DIR:-/run/user/$uid}"
    config_root="${XDG_CONFIG_HOME:-$HOME/.config}"
    allowlist_dir="$config_root/outerloop"
    allowlist_path="$allowlist_dir/http-unix.allow"
    allowlist_entry="%t/org.outershell.OuterShell"
    install -d -m 0700 "$allowlist_dir"
    touch "$allowlist_path"
    chmod 0644 "$allowlist_path"
fi
if ! grep -Fx -- "$allowlist_entry" "$allowlist_path" >/dev/null 2>&1; then
    printf '%s\n' "$allowlist_entry" >> "$allowlist_path"
fi
socket_path="$runtime_dir/org.outershell.OuterShell"
attempts=50
while [ "$attempts" -gt 0 ]; do
    if [ -S "$socket_path" ]; then
        printf '%s\n' "$socket_path"
        exit 0
    fi
    sleep 0.1
    attempts=$((attempts - 1))
done
echo "Outer Shell installed, but $socket_path did not appear." >&2
exit 1

Remote Unix Socket Bridge Commands

These commands are used when browsing http+unix://... URLs on remote Linux hosts.

Detect Helper Architecture

Used before uploading outer-socket-bridge.

uname -m

Install User-Mode Socket Bridge Helper

This installs the helper without sudo into $XDG_RUNTIME_DIR/outerloop-socket-bridge/INSTALL_ID/outer-socket-bridge, or $HOME/.cache/outerloop-socket-bridge/INSTALL_ID/outer-socket-bridge when XDG_RUNTIME_DIR is unavailable. The helper executable bytes are streamed to stdin.

set -eu
install_id='INSTALL_ID'
case "$install_id" in
  ''|*[!ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._-]*)
    echo "invalid install id for outer-socket-bridge install" >&2
    exit 1
    ;;
esac
if [ "$(uname -s)" != "Linux" ]; then
  echo "outer-socket-bridge user install is Linux-only" >&2
  exit 1
fi
base_root="${XDG_RUNTIME_DIR:-}"
if [ -z "$base_root" ]; then
  base_root="${HOME:-}/.cache"
fi
if [ -z "$base_root" ]; then
  echo "could not resolve a user runtime directory for outer-socket-bridge" >&2
  exit 1
fi
case "$base_root" in
  /*)
    ;;
  *)
    echo "outer-socket-bridge user runtime directory is not absolute" >&2
    exit 1
    ;;
esac
base_dir="$base_root/outerloop-socket-bridge"
install_dir="$base_dir/$install_id"
helper_path="$install_dir/outer-socket-bridge"
helper_upload="$(mktemp)"
trap 'rm -f "$helper_upload"; rm -rf "$install_dir/.install"' EXIT
dd of="$helper_upload" bs=1 count=HELPER_BYTE_COUNT 2>/dev/null
actual="$(wc -c < "$helper_upload" | tr -d ' ')"
if [ "$actual" != "HELPER_BYTE_COUNT" ]; then
  echo "outer-socket-bridge upload was truncated" >&2
  exit 1
fi
rm -rf "$install_dir"
install -d -m 0700 "$install_dir"
install -m 0755 "$helper_upload" "$helper_path"
version="$("$helper_path" --version 2>/dev/null || true)"
case "$version" in
  outer-socket-bridge*)
    ;;
  *)
    rm -rf "$install_dir"
    echo "outer-socket-bridge is not current at $helper_path" >&2
    exit 1
    ;;
esac
printf 'OUTER_SOCKET_BRIDGE_HELPER=%s\n' "$helper_path"
"$helper_path" --version

Authorize a User-Accessible Unix HTTP Socket

Runs the uploaded helper to check the requested socket against the target user’s allowlist.

'HELPER_PATH' authorize --socket 'SOCKET_PATH'

Cleanup User-Mode Socket Bridge Helper

set -eu
helper_path='HELPER_PATH'
case "$helper_path" in
  */outerloop-socket-bridge/*/outer-socket-bridge)
    ;;
  *)
    exit 1
    ;;
esac
install_dir="$(dirname "$helper_path")"
base_dir="$(dirname "$install_dir")"
rm -rf -- "$install_dir"
rmdir "$base_dir" 2>/dev/null || true

Remote Root-Owned Unix Socket Bridge Commands

These commands are used for remote Unix sockets under root-owned runtime directories, such as /run or /var/run.

Check Sudo Cache

sudo -n true

Install Root-Mode Socket Bridge Helper

Outer Loop first runs uname -m, then streams the matching outer-socket-bridge Linux helper bytes to stdin. When sudo is not cached, the sudo password is written first on stdin, followed by helper bytes.

uid="$(id -u)"; sudo SUDO_MODE sh -c '
set -eu
invoking_uid="$1"
install_id="$2"
case "$invoking_uid" in
  '"'"''"'"'|*[!0-9]*)
    echo "invalid invoking uid for outer-socket-bridge install" >&2
    exit 1
    ;;
esac
case "$install_id" in
  '"'"''"'"'|*[!ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._-]*)
    echo "invalid install id for outer-socket-bridge install" >&2
    exit 1
    ;;
esac
if [ "$(uname -s)" != "Linux" ]; then
  echo "outer-socket-bridge is Linux-only" >&2
  exit 1
fi
tmp=""
helper_upload="$(mktemp)"
trap '"'"'rm -f "$helper_upload"; rm -rf "$tmp"'"'"' EXIT
dd of="$helper_upload" bs=1 count=HELPER_BYTE_COUNT 2>/dev/null
actual="$(wc -c < "$helper_upload" | tr -d '"'"' '"'"')"
if [ "$actual" != "HELPER_BYTE_COUNT" ]; then
  echo "outer-socket-bridge upload was truncated" >&2
  exit 1
fi
chmod 0755 "$helper_upload"
runtime_dir='"'"'/var/tmp/outerloop-socket-bridge'"'"'
base_dir="$runtime_dir/$invoking_uid"
install_dir="$base_dir/$install_id"
helper_path="$install_dir/outer-socket-bridge"

prepare_directory() {
  dir="$1"
  if [ -e "$dir" ] && { [ ! -d "$dir" ] || [ -L "$dir" ]; }; then
    echo "outer-socket-bridge runtime path is not a directory: $dir" >&2
    exit 1
  fi
  install -d -o root -g root -m 0700 "$dir"
  [ -d "$dir" ] && [ ! -L "$dir" ] || {
    echo "outer-socket-bridge runtime path is invalid: $dir" >&2
    exit 1
  }
  owner="$(stat -c %u "$dir" 2>/dev/null || echo '"'"''"'"')"
  [ "$owner" = "0" ] || {
    echo "outer-socket-bridge runtime path is not root-owned: $dir" >&2
    exit 1
  }
  chmod 0700 "$dir"
}

prepare_directory "$runtime_dir"
prepare_directory "$base_dir"
rm -rf "$install_dir"
prepare_directory "$install_dir"
tmp="$(mktemp -d "$base_dir/.install.XXXXXX")"
install -o root -g root -m 0755 "$helper_upload" "$helper_path"
version="$("$helper_path" --version 2>/dev/null || true)"
case "$version" in
  outer-socket-bridge*)
    ;;
  *)
  rm -rf "$tmp" "$install_dir"
  tmp=""
  echo "outer-socket-bridge is not current at $helper_path" >&2
  exit 1
    ;;
esac
rm -rf "$tmp"
tmp=""
rm -f /usr/local/libexec/outer-socket-bridge /etc/sudoers.d/outer-socket-bridge
printf '"'"'OUTER_SOCKET_BRIDGE_HELPER=%s\n'"'"' "$helper_path"
"$helper_path" --version
' sh "$uid" 'INSTALL_ID'

SUDO_MODE is one of:

-n

-S -p ''

Launch Root Bridge

Runs the installed helper under sudo and keeps the SSH channel open while it proxies framed socket traffic over stdin/stdout.

sudo SUDO_MODE 'HELPER_PATH' bridge --socket 'SOCKET_PATH'

SUDO_MODE is again either -n or -S -p ''.

Cleanup Root-Mode Socket Bridge Helper

sudo -n sh -c '
set -eu
helper_path="$1"
case "$helper_path" in
  '"'"'/var/tmp/outerloop-socket-bridge'"'"'/*/outer-socket-bridge)
    ;;
  *)
    exit 1
    ;;
esac
install_dir="$(dirname "$helper_path")"
base_dir="$(dirname "$install_dir")"
runtime_dir="$(dirname "$base_dir")"
rm -rf -- "$install_dir"
rmdir "$base_dir" "$runtime_dir" 2>/dev/null || true
' sh 'HELPER_PATH'

Localhost Session Commands

For localhost sessions, the target machine is the Mac running Outer Loop. TCP and normal user-accessible Unix socket forwarding is handled through app-side networking code and does not run a target-side shell command. The target-side commands below are used for Outer Shell and root-owned Unix sockets.

Probe Default Local Outer Shell

Outer Loop checks whether the launch agent is loaded:

/bin/launchctl print "gui/USER_ID/org.outershell.OuterShell"

It then expects the socket at the Darwin user temp directory plus org.outershell.OuterShell.

Install Default Local Outer Shell

Outer Loop downloads install.sh and the matching macOS archive from https://outershell.org/outer-shell/latest, stages both in a temporary directory, sets OUTERSHELL_INSTALL_ARCHIVE, and runs:

HOME="REAL_USER_HOME_DIRECTORY" OUTERSHELL_INSTALL_ARCHIVE="STAGED_ARCHIVE_PATH" /bin/sh "STAGED_INSTALL_SCRIPT_PATH"

After a successful install, Outer Loop also updates the local allowlist file directly:

~/Library/Application Support/dev.outergroup.OuterLoop/http-unix.allow

with this entry:

%t/org.outershell.OuterShell

Authorize Local User-Accessible Unix HTTP Socket

This runs the bundled macOS outer-socket-bridge helper without sudo.

'OUTER_LOOP_APP_HELPER_PATH/outer-socket-bridge' authorize --socket 'SOCKET_PATH'

Launch Local Root-Owned Unix Socket Bridge

This runs the bundled macOS outer-socket-bridge helper under sudo and keeps stdin/stdout open for framed socket traffic.

/usr/bin/sudo SUDO_MODE -p '' 'OUTER_LOOP_APP_HELPER_PATH/outer-socket-bridge' bridge --socket 'SOCKET_PATH'

SUDO_MODE is one of:

-n

-S

When -S is used, Outer Loop writes the sudo password followed by a newline to stdin before bridge traffic starts.