Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
#!/usr/bin/env bash
# Runtime/state lifecycle used by the public tunnel and local `mso web` fallback.
GATEWAY_EXPECTED_VERSION="$(node -p 'require(process.argv[1]).version' "$ROOT/package.json")" || gateway_fail "cannot read MSO version"
gateway_runtime_from_state() {
local state="$1" identity owned instance stored_env
RUNTIME_IDENTITY='null'; RUNTIME_INSTANCE_ID=''; RUNTIME_OWNED=false; RUNTIME_STARTED_NOW=false
owned="$(jq -r '.runtimeOwned // false' <<<"$state")"
identity="$(jq -c '.runtimeIdentity // null' <<<"$state")"
instance="$(jq -r '.runtimeIdentity.instanceId // empty' <<<"$state")"
stored_env="$(jq -c '.envFile // null' <<<"$state")"
if [ "$owned" = true ] && [ "$identity" != null ] && [ -n "$instance" ]; then
# Legacy state may be migrated by one explicit local-start using the same env.
[ "$stored_env" = null ] || [ "$(jq -cS . <<<"$stored_env")" = "$(jq -cS . <<<"$GATEWAY_ENV_IDENTITY")" ] \
|| gateway_fail "recorded runtime belongs to another env-file identity; use its original --env or stop it first"
if gateway_runtime_identity_matches "$identity"; then
RUNTIME_IDENTITY="$identity"; RUNTIME_INSTANCE_ID="$instance"; RUNTIME_OWNED=true
fi
fi
}
gateway_service_owns_local_listener() {
local port hex file line addr state inode cgroup pid fd link working tcp tcp6
command -v systemctl >/dev/null 2>&1 || return 1
systemctl is-active --quiet mso.service 2>/dev/null || return 1
working="$(systemctl show -p WorkingDirectory --value mso.service 2>/dev/null || true)"
[ -n "$working" ] && [ "$(readlink -f -- "$working" 2>/dev/null || true)" = "$GATEWAY_CANONICAL_ROOT" ] || return 1
cgroup="$(systemctl show -p ControlGroup --value mso.service 2>/dev/null || true)"
[ -n "$cgroup" ] && [ -r "/sys/fs/cgroup$cgroup/cgroup.procs" ] || return 1
port="$(node - "$LOCAL_URL" <<'NODE'
const u=new URL(process.argv[2]); process.stdout.write(u.port);
NODE
)"
[[ "$port" =~ ^[0-9]{1,5}$ ]] || return 1
printf -v hex '%04X' "$port"
tcp="${MSO_GATEWAY_PROC_NET_TCP:-/proc/net/tcp}"
tcp6="${MSO_GATEWAY_PROC_NET_TCP6:-/proc/net/tcp6}"
inode=''
for file in "$tcp" "$tcp6"; do
[ -r "$file" ] || continue
while read -r line; do
set -- $line; [ "$#" -ge 10 ] || continue
addr="${2:-}"; state="${4:-}"
[ "$state" = 0A ] || continue
if [[ "$addr" = *:"$hex" ]]; then inode="${10:-}"; [ -n "$inode" ] && break 2; fi
done <"$file"
done
[[ "$inode" =~ ^[0-9]+$ ]] || return 1
while read -r pid; do
[[ "$pid" =~ ^[0-9]+$ ]] && [ "$pid" -gt 1 ] || continue
[ "$(stat -c '%u' "/proc/$pid" 2>/dev/null || true)" = "$(id -u)" ] || continue
[ "$(readlink -f -- "/proc/$pid/cwd" 2>/dev/null || true)" = "$GATEWAY_CANONICAL_ROOT" ] || continue
for fd in "/proc/$pid"/fd/*; do
link="$(readlink "$fd" 2>/dev/null || true)"
[ "$link" = "socket:[$inode]" ] && return 0
done
done <"/sys/fs/cgroup$cgroup/cgroup.procs"
return 1
}
gateway_assert_managed_runtime_trusted() {
[ "$RUNTIME_OWNED" = true ] && return 0
if [ "${NODE_ENV:-}" = test ] && [ -n "${MSO_GATEWAY_CURL:-}" ] && [ -n "${MSO_GATEWAY_PROC_NET_TCP:-}" ]; then return 0; fi
gateway_service_owns_local_listener || gateway_fail "refusing managed tunnel: healthy loopback listener is not proven to belong to this checkout's mso.service"
}
gateway_start_runtime_if_needed() {
local next host port pid identity instance node_exe current_exe i parent_ticks gate
[ "$RUNTIME_OWNED" = true ] && gateway_health_url_ok "$LOCAL_URL" "$RUNTIME_INSTANCE_ID" && return 0
if gateway_health_ok; then
RUNTIME_IDENTITY='null'; RUNTIME_INSTANCE_ID=''; RUNTIME_OWNED=false; RUNTIME_STARTED_NOW=false
return 0
fi
next="$ROOT/scripts/server.mjs"
[ -f "$next" ] || gateway_fail "MSO runtime is down and the production entry point is missing; run: mso update"
[ -f "$ROOT/.next/BUILD_ID" ] || gateway_fail "MSO runtime is down and no production build exists; run: mso update"
IFS=$'\t' read -r host port < <(gateway_loopback_host_port)
[ "$host" = "127.0.0.1" ] || [ "$host" = "localhost" ] \
|| gateway_fail "detached fallback supports 127.0.0.1/localhost; start MSO manually for $host"
[[ "$port" =~ ^[0-9]{1,5}$ ]] || gateway_fail "invalid local port: $port"
instance="$(node -e 'process.stdout.write(require("crypto").randomBytes(16).toString("hex"))')"
node_exe="$(readlink -f -- "$(command -v node)")"
gateway_private_file "$RUNTIME_LOG"; : >"$RUNTIME_LOG"
parent_ticks="$(gateway_proc_start_ticks $$)" || gateway_fail "cannot identify runtime-launch parent"
gate="$STATE_ROOT/.runtime-release.$$.$RANDOM"
RUNTIME_PENDING_GATE="$gate"; RUNTIME_PENDING_PID=0; RUNTIME_PENDING_TICKS=''
(
cd "$ROOT" || exit 1
nohup /bin/bash "$ROOT/scripts/lib/gateway-held-child.sh" "$$" "$parent_ticks" "$gate" \
env MSO_RUNTIME_INSTANCE_ID="$instance" node "$next" --hostname 127.0.0.1 --port "$port" \
>>"$RUNTIME_LOG" 2>&1 &
printf '%s\n' "$!"
) >"$STATE_ROOT/.runtime-pid.$$"
pid="$(cat "$STATE_ROOT/.runtime-pid.$$")"; rm -f "$STATE_ROOT/.runtime-pid.$$"
gateway_track_pending_runtime "$pid" || { kill "$pid" 2>/dev/null || true; gateway_runtime_pending_gate_cleanup; gateway_fail "runtime held child could not be tracked"; }
printf '1\n' | mso_private_state_atomic_write "$gate" >/dev/null \
|| { gateway_stop_pending_runtime; gateway_fail "runtime release gate could not be persisted"; }
identity=''
for i in $(seq 1 30); do
if gateway_pid_alive "$pid"; then
current_exe="$(readlink -f -- "/proc/$pid/exe" 2>/dev/null || true)"
if [ "$current_exe" = "$node_exe" ]; then
identity="$(gateway_capture_identity "$pid" 2>/dev/null || true)"
[ -n "$identity" ] && break
fi
else break; fi
sleep 0.05
done
if [ -z "$identity" ]; then gateway_stop_pending_runtime; gateway_fail "runtime did not start as the expected Node process"; fi
gateway_runtime_pending_gate_cleanup
identity="$(jq -c --arg instance "$instance" '.cmdHash=null | .instanceId=$instance' <<<"$identity")"
if ! gateway_wait_health "$instance"; then
gateway_stop_identity "$identity"
gateway_fail "runtime did not become this launch's MSO health instance; see $RUNTIME_LOG"
fi
RUNTIME_IDENTITY="$identity"; RUNTIME_INSTANCE_ID="$instance"; RUNTIME_OWNED=true; RUNTIME_STARTED_NOW=true
RUNTIME_PENDING_PID=0; RUNTIME_PENDING_TICKS=''
GATEWAY_PENDING_CLEANUP=1
}
gateway_write_state() {
local provider="$1" mode="$2" url="$3" tunnel_identity="$4"
jq -nc --arg scopeId "$GATEWAY_SCOPE_ID" --arg root "$GATEWAY_CANONICAL_ROOT" \
--arg provider "$provider" --arg mode "$mode" --arg url "$url" --arg local "$LOCAL_URL" \
--argjson envFile "$GATEWAY_ENV_IDENTITY" --argjson tunnelIdentity "$tunnel_identity" \
--argjson runtimeIdentity "$RUNTIME_IDENTITY" --argjson runtimeOwned "$RUNTIME_OWNED" \
--arg startedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
'{scopeId:$scopeId,root:$root,provider:$provider,mode:$mode,url:$url,localUrl:$local,envFile:$envFile,
tunnelIdentity:$tunnelIdentity,runtimeIdentity:$runtimeIdentity,runtimeOwned:$runtimeOwned,startedAt:$startedAt}' \
| mso_private_state_atomic_write "$STATE_FILE" >/dev/null
}
gateway_active_state() {
local state identity rc
if state="$(gateway_state_read)"; then :; else rc=$?; return "$rc"; fi
identity="$(jq -c '.tunnelIdentity // null' <<<"$state")"
[ "$identity" != null ] && gateway_identity_matches "$identity" || return 1
printf '%s' "$state"
}
gateway_cmd_local_start_locked() {
local state tunnel provider mode url
state="$(gateway_state_read)"
gateway_runtime_from_state "$state"
gateway_start_runtime_if_needed
tunnel="$(jq -c '.tunnelIdentity // null' <<<"$state")"
if [ "$tunnel" != null ] && gateway_identity_matches_retry "$tunnel"; then
provider="$(jq -r '.provider // "cloudflare-quick"' <<<"$state")"
mode="$(jq -r '.mode // "temporary"' <<<"$state")"
url="$(jq -r --arg local "$LOCAL_URL" '.url // $local' <<<"$state")"
else
tunnel=null; provider=local; mode=local; url="$LOCAL_URL"
fi
if [ "$RUNTIME_STARTED_NOW" = true ] || [ "$RUNTIME_OWNED" = true ]; then
if ! gateway_write_state "$provider" "$mode" "$url" "$tunnel"; then
[ "$RUNTIME_STARTED_NOW" = true ] && gateway_stop_identity "$RUNTIME_IDENTITY"
gateway_fail "could not persist local runtime state; newly started runtime was rolled back"
fi
GATEWAY_PENDING_CLEANUP=0
fi
gateway_info "runtime: healthy MSO at $LOCAL_URL"
}
gateway_persist_quiesced_state() {
local state="$1" tunnel provider mode url
tunnel="$(jq -c '.tunnelIdentity // null' <<<"$state")"
provider="$(jq -r '.provider // "local"' <<<"$state")"
mode="$(jq -r '.mode // "local"' <<<"$state")"
url="$(jq -r --arg local "$LOCAL_URL" '.url // $local' <<<"$state")"
RUNTIME_IDENTITY=null; RUNTIME_INSTANCE_ID=''; RUNTIME_OWNED=false; RUNTIME_STARTED_NOW=false
gateway_write_state "$provider" "$mode" "$url" "$tunnel"
}
gateway_cmd_runtime_assert_update_safe_locked() {
local state runtime owned
state="$(gateway_state_read)"
runtime="$(jq -c '.runtimeIdentity // null' <<<"$state")"
owned="$(jq -r '.runtimeOwned // false' <<<"$state")"
if [ "$owned" = true ] && [ "$runtime" != null ]; then
gateway_info "runtime: update-owned"
return 0
fi
if gateway_health_ok; then
gateway_fail "a loopback MSO runtime is active but is not gateway-owned; stop it before an offline update"
fi
gateway_info "runtime: update-safe"
}
# The proof for a service-owned listener stays strict; this seam exists only so the
# update path can be exercised in tests without owning a real unit.
gateway_service_owned_or_test_allowed() {
gateway_service_owns_local_listener && return 0
[ "${NODE_ENV:-}" = test ] && [ -n "${MSO_GATEWAY_TEST_SERVICE_LISTENER:-}" ]
}
gateway_cmd_runtime_stop_locked() {
local state runtime owned
gateway_recovery_marker_path >/dev/null
state="$(gateway_state_read)"
runtime="$(jq -c '.runtimeIdentity // null' <<<"$state")"
owned="$(jq -r '.runtimeOwned // false' <<<"$state")"
if [ "$owned" = true ] && [ "$runtime" != null ]; then
if gateway_runtime_process_matches "$runtime"; then
# PID + start ticks + Node executable prove this is the same recorded
# process even if its HTTP listener is already unhealthy. Persist recovery
# intent before terminating it; a failed state write is then retryable.
gateway_mark_recovery_pending
gateway_stop_identity "$runtime"
gateway_wait_runtime_stopped "$runtime" || gateway_fail "owned runtime did not stop; recovery marker preserved"
gateway_persist_quiesced_state "$state" \
|| gateway_fail "runtime stopped but quiesced state did not persist; recovery marker preserved for retry"
gateway_info "runtime: stopped-owned"
return 0
fi
if ! gateway_runtime_process_matches "$runtime" && ! gateway_health_ok; then
# Natural exit: persist restore intent before dropping ownership.
gateway_mark_recovery_pending; gateway_persist_quiesced_state "$state" \
|| gateway_fail "could not reconcile stale owned runtime; recovery marker preserved"
gateway_info "runtime: recovered-stale-owned"; return 0
fi
gateway_fail "recorded runtime ownership no longer matches a safely recoverable MSO instance; refusing offline rebuild"
fi
if gateway_health_ok; then
# A healthy loopback listener proven to be THIS checkout's own mso.service is not a
# fallback runtime: the service lifecycle keeps it through the build and
# scripts/self-update.sh replaces it by signalling its same-UID MainPID, so there is
# nothing to quiesce. Any listener not proven to be this checkout's unit still fails
# closed below, and the offline preflight (runtime-assert-update-safe) stays strict.
if gateway_service_owned_or_test_allowed; then
gateway_info "runtime: service-owned"
return 0
fi
gateway_fail "a loopback MSO runtime is active but is not gateway-owned; stop it before an offline update"
fi
if gateway_recovery_pending; then gateway_info "runtime: recovery-pending"; else gateway_info "runtime: already-down"; fi
}
gateway_cmd_stop_locked() {
local state tunnel runtime owned
state="$(gateway_state_read)"
tunnel="$(jq -c '.tunnelIdentity // null' <<<"$state")"
runtime="$(jq -c '.runtimeIdentity // null' <<<"$state")"
owned="$(jq -r '.runtimeOwned // false' <<<"$state")"
if [ "$tunnel" != null ]; then
gateway_stop_identity "$tunnel" || gateway_fail "tunnel process could not be proven stopped; lifecycle state was preserved"
fi
if [ "$owned" = true ] && [ "$runtime" != null ]; then
gateway_stop_identity "$runtime" || gateway_fail "runtime process could not be proven stopped; lifecycle state was preserved"
fi
mso_private_state_remove_file "$STATE_FILE" >/dev/null 2>&1 || true
gateway_info "gateway stopped; MSO remains loopback-only"
}
gateway_cmd_status() {
local json=0 observed rc state legacy mode
while [ $# -gt 0 ]; do
case "$1" in
--json) json=1 ;;
*) gateway_fail "usage: mso gateway status [--json]" ;;
esac
shift
done
if observed="$(gateway_observe_state)"; then rc=0; else rc=$?; fi
if [ "$json" = 1 ]; then
printf '%s\n' "$observed"
else
state="$(jq -r .state <<<"$observed")"
legacy="$(jq -r .legacyState <<<"$observed")"
if [ "$legacy" = running ]; then gateway_info "gateway: running"
else gateway_info "gateway: $legacy"; fi
gateway_info "state: $state"
gateway_info "provider: $(jq -r .provider <<<"$observed")"
gateway_info "ownership: $(jq -r .ownership <<<"$observed")"
gateway_info "supervisor: $(jq -r .supervisor <<<"$observed")"
gateway_info "process-health: $(jq -r .processHealth <<<"$observed")"
gateway_info "local-health: $(jq -r .localHealth <<<"$observed")"
gateway_info "public-health: $(jq -r .publicHealth <<<"$observed")"
gateway_info "provider-health: $(jq -r .providerHealth <<<"$observed")"
gateway_info "public: $(jq -r '.public // "--"' <<<"$observed")"
gateway_info "local: $(jq -r .local <<<"$observed")"
mode="$(jq -r '.mode // empty' <<<"$observed")"
[ -z "$mode" ] || gateway_info "mode: $mode"
[ "$mode" != temporary ] || gateway_info "note: Quick Tunnel is preview-only; live Terminal SSE is not supported"
fi
[ "$rc" = 0 ] || return "$rc"
state="$(jq -r .state <<<"$observed")"
gateway_status_exit_code "$state"
}
gateway_cmd_url() {
local observed state public rc
if observed="$(gateway_observe_state)"; then rc=0; else rc=$?; fi
[ "$rc" = 0 ] || return "$rc"
state="$(jq -r .state <<<"$observed")"
public="$(jq -r '.public // empty' <<<"$observed")"
case "$state" in
managed-running|external-running) [ -n "$public" ] && { printf '%s\n' "$public"; return 0; } ;;
esac
gateway_fail "gateway has no healthy public route; run: mso gateway status"
}