Clarify Cloud Ports and use the established VPN onboarding page

Packages/macOS/CmuxCloud/Sources/CmuxCloud/Tree/CloudPortsStatusAction.swift

@@ -0,0 +1,10 @@
+import Foundation
+
+/// The action exposed by an actionable Ports status callout.
+public enum CloudPortsStatusAction: Equatable, Sendable {
+    case none
+    case refresh
+    case setupVPN
+    case openMachine
+    case openShell
+}

Packages/macOS/CmuxCloud/Sources/CmuxCloud/Tree/CloudPortsStatusPresentation.swift

@@ -0,0 +1,131 @@
+import CmuxSurfaceCatalogModel
+import Foundation
+
+/// One immutable Ports reason shared by native status rows and their actions.
+public struct CloudPortsStatusPresentation: Equatable, Sendable {
+    public let state: CloudPortDiscoveryState
+    public let isVPNGuidance: Bool
+
+    public init(state: CloudPortDiscoveryState, isVPNGuidance: Bool = false) {
+        self.state = state
+        self.isVPNGuidance = isVPNGuidance
+    }
+
+    public static var vpnGuidance: Self {
+        Self(state: .available, isVPNGuidance: true)
+    }
+
+    public static func make(info: SurfaceMachineInfo) -> Self {
+        if info.portDiscoveryState == .notRequested {
+            switch info.linkState {
+            case .asleep: return Self(state: .unavailable(.machineAsleep))
+            case .error: return Self(state: .unavailable(.link))
+            case .unavailable: return Self(state: .unavailable(.transport))
+            default: break
+            }
+        }
+        return Self(state: info.portDiscoveryState)
+    }
+
+    public var title: String {
+        if isVPNGuidance {
+            return String(localized: "cloud.ports.vpnOff.title", defaultValue: "Optional: Cloud VPN")
+        }
+        switch state {
+        case .notRequested:
+            return String(localized: "cloudTree.ports.notRequested.title", defaultValue: "Ports not checked yet")
+        case .loading:
+            return String(localized: "cloudTree.ports.loading", defaultValue: "Discovering ports…")
+        case .available:
+            return String(localized: "cloudTree.ports.available.title", defaultValue: "Listening services")
+        case .loopbackOnly:
+            return String(localized: "cloudTree.ports.loopback.title", defaultValue: "Loopback services available")
+        case .empty(.noListeningService):
+            return String(localized: "cloudTree.ports.empty", defaultValue: "No ports yet")
+        case .empty(.otherInterfaceOnly):
+            return String(localized: "cloudTree.ports.binding.title", defaultValue: "Services use another interface")
+        case .unavailable(.privateAddress):
+            return String(localized: "cloudTree.ports.privateAddress", defaultValue: "Private address unavailable")
+        case .unavailable(.machineAsleep):
+            return String(localized: "cloudTree.ports.asleep", defaultValue: "Open the machine to discover ports")
+        case .unavailable(.link):
+            return String(localized: "cloudTree.ports.link.title", defaultValue: "Cloud link unavailable")
+        case .unavailable:
+            return String(localized: "cloudTree.ports.unavailable", defaultValue: "Port discovery unavailable. Refresh to retry.")
+        case .stale:
+            return String(localized: "cloudTree.ports.stale", defaultValue: "Port list may be out of date")
+        case .unsupported:
+            return String(localized: "cloudTree.ports.unsupported", defaultValue: "Ports are not supported by this provider.")
+        }
+    }
+
+    public var message: String {
+        if isVPNGuidance {
+            return String(
+                localized: "cloud.ports.vpnOff.explanation",
+                defaultValue: "Ports open in cmux without setup. To use private addresses in other apps, set up Cloud VPN."
+            )
+        }
+        switch state {
+        case .notRequested:
+            return Self.routeNote
+        case .loading:
+            return String(localized: "cloudTree.ports.loading.detail", defaultValue: "Checking services through cmux’s authenticated Cloud link. No system VPN is needed.")
+        case .available:
+            return Self.routeNote
+        case .loopbackOnly:
+            return String(localized: "cloudTree.ports.loopback.detail", defaultValue: "These services open in cmux without Cloud VPN. They listen on the machine’s loopback address, so other apps cannot reach them through its private IP, even with VPN connected.")
+        case .empty(.noListeningService):
+            return String(localized: "cloudTree.ports.empty.noService", defaultValue: "Start a web server on this machine, then refresh.")
+        case .empty(.otherInterfaceOnly):
+            return String(localized: "cloudTree.ports.binding.detail", defaultValue: "cmux’s browser route connects to 127.0.0.1 on the machine. Bind the service to 127.0.0.1 or 0.0.0.0, then refresh. Turning on Cloud VPN does not change this route.")
+        case .unavailable(.privateAddress):
+            return String(localized: "cloudTree.ports.privateAddress.detail", defaultValue: "cmux’s authenticated route needs this machine’s private address. Refresh to retrieve it. Turning on Cloud VPN does not assign a missing address.")
+        case .unavailable(.machineAsleep):
+            return String(localized: "cloudTree.ports.asleep.detail", defaultValue: "Wake the machine to check its services. cmux’s in-app forwarding does not need Cloud VPN.")
+        case .unavailable(.link):
+            return String(localized: "cloudTree.ports.link.detail", defaultValue: "Port discovery could not connect to this machine. Existing cmux ports may still work. Refresh to reconnect; Cloud VPN is not required.")
+        case .unavailable(.transport):
+            return String(localized: "cloudTree.ports.unavailable.detail", defaultValue: "The port scan failed; this does not mean no service is listening. Existing cmux ports may still work. Refresh to retry; Cloud VPN is not required.")
+        case .unavailable(.hub):
+            return String(localized: "cloudTree.ports.hub.detail", defaultValue: "This build cannot start cmux’s authenticated Cloud forward. Update cmux, then retry.")
+        case .stale:
+            return String(localized: "cloudTree.ports.stale.detail", defaultValue: "The last scan could not be refreshed. Listed services may have changed; refresh to check again. cmux forwarding does not need Cloud VPN.")
+        case .unsupported:
+            return String(localized: "cloudTree.ports.unsupported.detail", defaultValue: "This provider has no supported in-app port route. Open a shell to access the service inside the machine. Cloud VPN does not add provider support.")
+        }
+    }
+
+    public static var routeNote: String {
+        String(localized: "cloudTree.ports.routeNote", defaultValue: "cmux forwards ports without Cloud VPN. Web browsers and other Mac apps need Cloud VPN to reach services bound to the machine’s private address.")
+    }
+
+    public var action: CloudPortsStatusAction {
+        if isVPNGuidance { return .setupVPN }
+        switch state {
+        case .unavailable(.machineAsleep): return .openMachine
+        case .unsupported: return .openShell
+        case .loading, .available, .loopbackOnly: return .none
+        default: return .refresh
+        }
+    }
+
+    public var actionTitle: String? {
+        switch action {
+        case .none: return nil
+        case .refresh: return String(localized: "cloudTree.menu.refresh", defaultValue: "Refresh")
+        case .setupVPN: return String(localized: "cloudTree.ports.setupVPN", defaultValue: "Set Up VPN…")
+        case .openMachine: return String(localized: "cloudTree.ports.action.wake", defaultValue: "Wake Machine")
+        case .openShell: return String(localized: "machines.menu.openShell", defaultValue: "Open Shell")
+        }
+    }
+
+    public var style: CloudTreePlaceholder.Style {
+        if isVPNGuidance { return .dimmed }
+        switch state {
+        case .loading: return .connecting
+        case .unavailable(.machineAsleep), .notRequested, .available, .loopbackOnly, .empty, .unsupported: return .dimmed
+        case .unavailable, .stale: return .error
+        }
+    }
+}

Packages/macOS/CmuxCloud/Sources/CmuxCloud/Tree/CloudTreeLayoutMetrics.swift

@@ -1,4 +1,5 @@
 import CoreGraphics
+import CmuxFoundation
 
 /// Geometry shared by the Cloud outline's document and row content.
 ///
@@ -36,4 +37,13 @@ public struct CloudTreeLayoutMetrics: Equatable, Sendable {
     ) -> CGFloat {
         max(0, rowWidth - leadingContentWidth - trailingContentWidth - referenceInset)
     }
+    /// Horizontal origin shared by AppKit cell frames and wrapping Ports status measurements.
+    public func contentLeading(level: Int, style: CloudTreeStyle, magnification: Int = GlobalFontMagnification.storedPercent) -> CGFloat {
+        GlobalFontMagnification.scaledSize(8 + CGFloat(max(0, level)) * style.indentPerLevel, percent: magnification)
+            + GlobalFontMagnification.scaledSize(style.rowGrid.disclosureSlot + style.rowGrid.disclosureGap, percent: magnification)
+    }
+
+    public func portsContentWidth(columnWidth: CGFloat, level: Int, style: CloudTreeStyle) -> CGFloat {
+        max(1, columnWidth - contentLeading(level: level, style: style) - style.rowGrid.trailingPadding)
+    }
 }

Packages/macOS/CmuxCloud/Sources/CmuxCloud/Tree/CloudTreePlaceholder.swift

@@ -10,9 +10,11 @@ public struct CloudTreePlaceholder: Equatable, Sendable {
     public let style: Style
     /// Only wake placeholders set this. Empty resource categories remain inert.
     public let opensMachine: Bool
-    public init(text: String, style: Style, opensMachine: Bool = false) {
+    public let portStatus: CloudPortsStatusPresentation?
+    public init(text: String, style: Style, opensMachine: Bool = false, portStatus: CloudPortsStatusPresentation? = nil) {
         self.text = text
         self.style = style
         self.opensMachine = opensMachine
+        self.portStatus = portStatus
     }
 }

Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Environment/CloudMachinesPlanSummary.swift

@@ -0,0 +1,24 @@
+/// Snapshot of the caller's Cloud Machines plan for the settings section.
+public struct CloudMachinesPlanSummary: Equatable, Sendable {
+    /// Localized display name of the current plan.
+    public let planLabel: String
+    /// Number of machines currently counted against the plan.
+    public let activeMachines: Int
+    /// Active-machine ceiling; nil when the plan has no cap.
+    public let maxMachines: Int?
+    /// Whether the plan permits paid machine provisioning.
+    public let isPaidPlan: Bool
+
+    /// Creates a plan summary.
+    /// - Parameters:
+    ///   - planLabel: Display name of the plan, already localized.
+    ///   - activeMachines: Machines currently counted against the plan.
+    ///   - maxMachines: Active-machine ceiling, or nil when the plan has no cap.
+    ///   - isPaidPlan: Whether the plan is one the backend provisions for.
+    public init(planLabel: String, activeMachines: Int, maxMachines: Int?, isPaidPlan: Bool) {
+        self.planLabel = planLabel
+        self.activeMachines = activeMachines
+        self.maxMachines = maxMachines
+        self.isPaidPlan = isPaidPlan
+    }
+}

Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Environment/SettingsHostActions.swift

@@ -362,6 +362,9 @@ public protocol SettingsHostActions: AnyObject {
     /// Reveals the right-sidebar Machines panel in the active main window.
     func openCloudMachinesPanel()
 
+    /// Opens the optional system-wide VPN explanation and its explicit connection controls.
+    func openCloudVPNSetup()
+
     /// Opens the host's plan management / upgrade flow.
     func openCloudMachinesBilling()
 
@@ -409,28 +412,6 @@ public struct AutomationRulesStatus: Equatable, Sendable {
     }
 }
 
-/// Snapshot of the caller's Cloud Machines plan for the settings section.
-public struct CloudMachinesPlanSummary: Equatable, Sendable {
-    public let planLabel: String
-    public let activeMachines: Int
-    /// Active-machine ceiling; nil when the plan has no cap.
-    public let maxMachines: Int?
-    public let isPaidPlan: Bool
-
-    /// Creates a plan summary.
-    /// - Parameters:
-    ///   - planLabel: Display name of the plan, already localized.
-    ///   - activeMachines: Machines currently counted against the plan.
-    ///   - maxMachines: Active-machine ceiling, or nil when the plan has no cap.
-    ///   - isPaidPlan: Whether the plan is one the backend provisions for.
-    public init(planLabel: String, activeMachines: Int, maxMachines: Int?, isPaidPlan: Bool) {
-        self.planLabel = planLabel
-        self.activeMachines = activeMachines
-        self.maxMachines = maxMachines
-        self.isPaidPlan = isPaidPlan
-    }
-}
-
 /// One right-sidebar tab as the Sidebar section's customization card renders
 /// it. `id` is the host's stable mode identifier (the mode raw value).
 public struct RightSidebarTabSettingsItem: Identifiable, Equatable, Sendable {
@@ -498,6 +479,7 @@ public extension SettingsHostActions {
     var isCloudMachinesAvailable: Bool { false }
     func cloudMachinesPlanSummary() async -> CloudMachinesPlanSummary? { nil }
     func openCloudMachinesPanel() {}
+    func openCloudVPNSetup() {}
     func openCloudMachinesBilling() {}
 
     /// No release-app switch for previews, tests, and package-only hosts.

Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/CloudMachinesSection.swift

@@ -2,8 +2,8 @@ import SwiftUI
 
 /// **Cloud Machines** section — the plan card for persistent cloud VMs.
 /// Deliberately small: machines are managed from the right-sidebar Machines
-/// panel; Settings shows the plan meter and the two entry points (open the
-/// panel, manage the plan). Renders nothing when the host doesn't expose
+/// panel; Settings also exposes the plan and optional system VPN setup.
+/// Renders nothing when the host doesn't expose
 /// Cloud Machines, so the section is invisible to users outside the flag.
 @MainActor
 public struct CloudMachinesSection: View {
@@ -26,11 +26,14 @@ public struct CloudMachinesSection: View {
                     planRow
                     Divider().padding(.horizontal, 14)
                     panelRow
+                    Divider().padding(.horizontal, 14)
+                    vpnRow
                 }
             }
             .settingsSearchAnchors([
                 "setting:cloudMachines:plan",
                 "setting:cloudMachines:open-panel",
+                "setting:cloudMachines:vpn",
             ])
             .task {
                 plan = await hostActions.cloudMachinesPlanSummary()
@@ -82,6 +85,27 @@ public struct CloudMachinesSection: View {
         .id("setting:cloudMachines:open-panel")
     }
 
+    private var vpnRow: some View {
+        HStack(alignment: .firstTextBaseline) {
+            VStack(alignment: .leading, spacing: 2) {
+                Text(String(localized: "cloud.vpn.setup.entry.subtitle", defaultValue: "Optional private IP access for other apps"))
+                Text(String(localized: "cloud.vpn.setup.howItWorks.body", defaultValue: "Connect Safari, Chrome, and other apps to your Cloud machines. Each machine keeps its private IP address and original ports. Only traffic to your Cloud network uses this encrypted connection. cmux terminals, Ports, and Desktop work without it."))
+                    .font(.system(size: 11))
+                    .foregroundColor(.secondary)
+            }
+            Spacer()
+            Button(String(localized: "cloudTree.ports.setupVPN", defaultValue: "Set Up VPN…")) {
+                hostActions.openCloudVPNSetup()
+            }
+            .buttonStyle(.bordered)
+            .controlSize(.small)
+            .accessibilityIdentifier("SettingsCloudVPNSetup")
+        }
+        .padding(.horizontal, 14)
+        .padding(.vertical, 10)
+        .id("setting:cloudMachines:vpn")
+    }
+
     private var planSubtitle: String {
         guard let plan else {
             return hasLoaded

Packages/macOS/CmuxSurfaceCatalogModel/Sources/CmuxSurfaceCatalogModel/CloudPortDiscoveryEmptyReason.swift

@@ -0,0 +1,7 @@
+import Foundation
+
+/// Why a completed Cloud scan produced no listeners usable by the authenticated browser proxy.
+public enum CloudPortDiscoveryEmptyReason: String, Codable, Hashable, Sendable {
+    case noListeningService = "no_listening_service"
+    case otherInterfaceOnly = "other_interface_only"
+}

Packages/macOS/CmuxSurfaceCatalogModel/Sources/CmuxSurfaceCatalogModel/CloudPortDiscoveryState.swift

@@ -0,0 +1,45 @@
+import Foundation
+
+/// The authoritative state of a Cloud machine's demand-driven port scan.
+public enum CloudPortDiscoveryState: Hashable, Codable, Sendable {
+    /// Ports have not been requested yet; expanding the Ports group starts a scan.
+    case notRequested
+    /// A scan is in flight. Existing port rows remain visible while it runs.
+    case loading
+    /// A completed scan found at least one reachable service.
+    case available
+    /// The proxy can open these services; a system VPN cannot reach their loopback-only bindings.
+    case loopbackOnly
+    /// A completed scan found no service that cmux can reach.
+    case empty(CloudPortDiscoveryEmptyReason)
+    /// The scan or the route could not be used to produce a trustworthy result.
+    case unavailable(CloudPortDiscoveryUnavailableReason)
+    /// The last graph is retained, but a reconnect or refresh no longer proves it current.
+    case stale
+    /// The provider does not advertise Cloud port discovery or preview support.
+    case unsupported
+
+    /// Whether the Ports group should keep a status row after real port rows.
+    public var keepsStatusAlongsideRows: Bool {
+        switch self {
+        case .unavailable, .stale, .unsupported, .loading:
+            return true
+        case .notRequested, .available, .loopbackOnly, .empty:
+            return false
+        }
+    }
+
+    /// Stable, nonlocalized value used by socket exports and diagnostics.
+    public var wireValue: String {
+        switch self {
+        case .notRequested: return "not_requested"
+        case .loading: return "loading"
+        case .available: return "available"
+        case .loopbackOnly: return "loopback_only"
+        case .empty(let reason): return "empty_\(reason.rawValue)"
+        case .unavailable(let reason): return "unavailable_\(reason.rawValue)"
+        case .stale: return "stale"
+        case .unsupported: return "unsupported"
+        }
+    }
+}

Packages/macOS/CmuxSurfaceCatalogModel/Sources/CmuxSurfaceCatalogModel/CloudPortDiscoveryUnavailableReason.swift

@@ -0,0 +1,10 @@
+import Foundation
+
+/// Why Cloud port discovery or its in-app route is currently unavailable.
+public enum CloudPortDiscoveryUnavailableReason: String, Codable, Hashable, Sendable {
+    case link
+    case transport
+    case privateAddress = "private_address"
+    case machineAsleep = "machine_asleep"
+    case hub
+}