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
# Cloudflare tunnel start path. The application port always remains loopback-only.
GATEWAY_NAMED_CONFIG_HELPER="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/gateway-named-config.mjs"
gateway_parse_start_args() {
GATEWAY_CONFIG=""; GATEWAY_TUNNEL=""; GATEWAY_MODE=temporary; GATEWAY_PROVIDER=cloudflare-quick
shift || true
while [ $# -gt 0 ]; do
case "$1" in
--config) [ -n "${2-}" ] || gateway_fail "--config needs a path"; GATEWAY_CONFIG="$2"; shift 2 ;;
--tunnel) [ -n "${2-}" ] || gateway_fail "--tunnel needs a name or UUID"; GATEWAY_TUNNEL="$2"; shift 2 ;;
*) gateway_fail "usage: mso gateway start [--config <cloudflared.yml> --tunnel <name|uuid>]" ;;
esac
done
}
gateway_validate_named_config() {
node "$GATEWAY_NAMED_CONFIG_HELPER" "$ROOT" "$GATEWAY_CONFIG" "$GATEWAY_PUBLIC_URL" "$LOCAL_URL" "${NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE:-}"
}
gateway_validate_named_tunnel() {
local mode public mode_decimal
[ -n "$GATEWAY_CONFIG" ] && [ -n "$GATEWAY_TUNNEL" ] || gateway_fail "named mode requires BOTH --config and --tunnel"
[[ "$GATEWAY_TUNNEL" =~ ^[A-Za-z0-9_-]{1,80}$ ]] || gateway_fail "invalid tunnel name/UUID"
[ -f "$GATEWAY_CONFIG" ] && [ ! -L "$GATEWAY_CONFIG" ] || gateway_fail "config must be a regular non-symlink file"
[ "$(stat -c '%u' "$GATEWAY_CONFIG")" = "$(id -u)" ] || gateway_fail "cloudflared config must be owned by current user"
# Convert validated octal stat output before applying the permission mask.
mode="$(stat -c '%a' "$GATEWAY_CONFIG")"; [[ "$mode" =~ ^[0-7]{1,4}$ ]] && mode_decimal="$(printf '%d' "0$mode")" && [ "$((mode_decimal & 18))" -eq 0 ] \
|| gateway_fail "cloudflared config must not be group/world-writable (got mode $mode)"
public="$(gateway_validate_public_origin "${OS_PUBLIC_ORIGIN:-}" 2>/dev/null || true)"
[ -n "$public" ] || gateway_fail "named mode requires OS_PUBLIC_ORIGIN=https://your-domain (use: mso gateway domain set https://...)"
GATEWAY_MODE=named; GATEWAY_PROVIDER=cloudflare-named; GATEWAY_PUBLIC_URL="$public"
gateway_validate_named_config || gateway_fail "named config must be dedicated to OS_PUBLIC_ORIGIN -> the MSO loopback port, end in http_status:404, and reference a private owner-owned credentials-file"
}
gateway_spawn_tunnel() {
local pid identity
gateway_private_file "$PROVIDER_LOG"; : >"$PROVIDER_LOG"
# The parent intentionally has OS_LOGIN_PASSWORD, session secrets and BYOK keys
# for the Next runtime. The held-child helper scrubs that environment and cannot
# exec cloudflared until this parent has persisted the child lifetime identity.
if [ "$GATEWAY_MODE" = temporary ]; then
[ -z "${OS_PUBLIC_ORIGIN:-}" ] || gateway_info "warning: temporary gateway leaves existing OS_PUBLIC_ORIGIN unchanged"
gateway_spawn_held_tunnel "$CLOUDFLARED" tunnel --no-autoupdate --url "$LOCAL_URL" || return 1
pid="$TUNNEL_SPAWN_PID"
identity="$(gateway_wait_spawn_identity "$pid" "$CLOUDFLARED" tunnel --no-autoupdate --url "$LOCAL_URL" 2>/dev/null || true)"
else
gateway_spawn_held_tunnel "$CLOUDFLARED" tunnel --config "$GATEWAY_CONFIG" --no-autoupdate run "$GATEWAY_TUNNEL" || return 1
pid="$TUNNEL_SPAWN_PID"
identity="$(gateway_wait_spawn_identity "$pid" "$CLOUDFLARED" tunnel --config "$GATEWAY_CONFIG" --no-autoupdate run "$GATEWAY_TUNNEL" 2>/dev/null || true)"
fi
[ -n "$identity" ] || { gateway_stop_pending_tunnel; return 1; }
gateway_pending_gate_cleanup
TUNNEL_IDENTITY="$identity"
# Keep our spawned child's lifetime until state commits: argv/exe can still change.
GATEWAY_PENDING_CLEANUP=1
}
# A script launcher can exec its interpreter without changing PID/start ticks.
# After readiness, persist the final executable/argv identity, not its startup wrapper.
gateway_refresh_tunnel_identity() {
local pid="$TUNNEL_PENDING_PID" identity
if [ "$GATEWAY_MODE" = temporary ]; then
identity="$(gateway_wait_spawn_identity "$pid" "$CLOUDFLARED" tunnel --no-autoupdate --url "$LOCAL_URL" 2>/dev/null || true)"
else
identity="$(gateway_wait_spawn_identity "$pid" "$CLOUDFLARED" tunnel --config "$GATEWAY_CONFIG" --no-autoupdate run "$GATEWAY_TUNNEL" 2>/dev/null || true)"
fi
[ -n "$identity" ] && [ "$(jq -r .startTicks <<<"$identity")" = "$TUNNEL_PENDING_TICKS" ] \
&& gateway_identity_matches "$identity" || return 1
TUNNEL_IDENTITY="$identity"
}
gateway_cleanup_failed_start() {
# Until durable commit, the PID/start-ticks handshake proves this is OUR child
# even if an interpreter exec or process-title update changed its argv identity.
if [ "${TUNNEL_PENDING_PID:-0}" -gt 1 ] 2>/dev/null; then gateway_stop_pending_tunnel
elif [ "${TUNNEL_IDENTITY:-null}" != null ]; then gateway_stop_identity "$TUNNEL_IDENTITY"; fi
if [ "${RUNTIME_STARTED_NOW:-false}" = true ]; then gateway_stop_identity "$RUNTIME_IDENTITY"
else gateway_stop_pending_runtime; fi
}
gateway_cmd_start_locked() {
local state active rc requested_named=false
if [ -n "${GATEWAY_CONFIG:-}${GATEWAY_TUNNEL:-}" ]; then
gateway_validate_named_tunnel
requested_named=true
fi
if active="$(gateway_active_state)"; then
[ "$requested_named" != true ] \
|| gateway_fail "gateway is already active; run: mso gateway stop — then retry the named tunnel start"
gateway_reconcile_active_tunnel "$active"
return 0
else rc=$?; fi
[ "$rc" = 1 ] || return "$rc"
gateway_resolve_cloudflared
state="$(gateway_state_read)"
gateway_assert_port_loopback_only
gateway_runtime_from_state "$state"
gateway_start_runtime_if_needed
gateway_assert_port_loopback_only
gateway_assert_managed_runtime_trusted
LOCAL_HEALTH_IDENTITY="$(gateway_health_url_identity "$LOCAL_URL" "${RUNTIME_INSTANCE_ID:-}")" \
|| { gateway_cleanup_failed_start; gateway_fail "selected local runtime did not return a stable MSO health identity"; }
TUNNEL_IDENTITY=null; GATEWAY_PUBLIC_URL="${GATEWAY_PUBLIC_URL:-}"
gateway_spawn_tunnel || { gateway_cleanup_failed_start; gateway_fail "cloudflared failed to start with the expected argv"; }
if [ "$GATEWAY_MODE" = temporary ]; then
gateway_discover_quick_url || { gateway_cleanup_failed_start; gateway_fail "Quick Tunnel did not return a public URL; see $PROVIDER_LOG"; }
fi
GATEWAY_PUBLIC_URL="$(gateway_validate_public_origin "$GATEWAY_PUBLIC_URL" 2>/dev/null || true)"
[ -n "$GATEWAY_PUBLIC_URL" ] || { gateway_cleanup_failed_start; gateway_fail "tunnel produced an invalid public origin"; }
gateway_probe_public || { gateway_cleanup_failed_start; gateway_fail "public endpoint did not return the MSO health contract; see $PROVIDER_LOG"; }
gateway_refresh_tunnel_identity || { gateway_cleanup_failed_start; gateway_fail "ready tunnel no longer matches its spawned process"; }
if ! gateway_write_state "$GATEWAY_PROVIDER" "$GATEWAY_MODE" "$GATEWAY_PUBLIC_URL" "$TUNNEL_IDENTITY"; then
gateway_cleanup_failed_start
gateway_fail "could not persist gateway state; newly launched processes were rolled back"
fi
GATEWAY_PENDING_CLEANUP=0
TUNNEL_PENDING_PID=0; TUNNEL_PENDING_TICKS=''
gateway_info "gateway started"
gateway_info "public: $GATEWAY_PUBLIC_URL"
gateway_info "local: $LOCAL_URL (still loopback-only)"
[ "$GATEWAY_MODE" != temporary ] || gateway_info "warning: Quick Tunnel is preview-only; live Terminal SSE may not work"
gateway_info "open: mso web"
gateway_info "stop: mso gateway stop"
}