Skip to content

armgit / mso

Public Imported from GitHub
0

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.

feat(install): add detailed platform tabs

Rahman1a41e1e865d6
diff --git a/app/install/page.tsx b/app/install/page.tsx
index 3449a0f0..f67ef7c5 100644
--- a/app/install/page.tsx
+++ b/app/install/page.tsx
@@ -1,6 +1,6 @@
import type { Metadata } from "next";
-import { PLATFORM_SUPPORT } from "@/lib/platform-support";
import { Copy } from "./copy";
+import { PlatformInstallTabs } from "./platform-tabs";
export const metadata: Metadata = {
title: "Install Manef Shell OS",
@@ -77,34 +77,14 @@ export default function InstallPage() {
</header>
<section className="mb-12">
- <h2 className="mb-4 text-lg font-semibold">Supported platforms</h2>
- <div className="grid gap-3 md:grid-cols-2">
- {PLATFORM_SUPPORT.map((platform) => (
- <article key={platform.id} className="rounded-lg border border-border p-4">
- <div className="flex flex-wrap items-baseline justify-between gap-2">
- <h3 className="text-base font-semibold">{platform.label}</h3>
- <span className="rounded-full border border-border px-2 py-0.5 text-xs text-muted-foreground">
- {platform.modeLabel}
- </span>
- </div>
- <p className="mt-2 text-sm leading-relaxed text-muted-foreground">{platform.summary}</p>
- <p className="mt-2 text-xs text-muted-foreground">
- Manages: <span className="font-medium text-foreground">{platform.hostScope}</span>
- </p>
- {platform.installCommand ? <Copy text={platform.installCommand} /> : (
- <p className="mt-3 rounded-md bg-muted px-3 py-2 text-sm text-muted-foreground">
- Open your protected MSO HTTPS URL in Safari, then Share → Add to Home Screen.
- </p>
- )}
- {platform.verifyCommand ? (
- <p className="mt-2 break-words font-mono text-xs text-muted-foreground">{platform.verifyCommand}</p>
- ) : null}
- <ul className="mt-3 space-y-1 text-xs leading-relaxed text-muted-foreground">
- {platform.notes.map((note) => <li key={note}>• {note}</li>)}
- </ul>
- </article>
- ))}
+ <div className="mb-4">
+ <h2 className="text-lg font-semibold">Choose your platform</h2>
+ <p className="mt-1 text-sm leading-relaxed text-muted-foreground">
+ Each tab includes prerequisites, exact commands, step-by-step setup, troubleshooting,
+ verification, and links to the relevant official documentation.
+ </p>
</div>
+ <PlatformInstallTabs />
</section>
<section className="mb-12">
@@ -133,7 +113,8 @@ export default function InstallPage() {
</section>
<section className="mb-12">
- <h2 className="mb-5 text-lg font-semibold">Five steps</h2>
+ <h2 className="mb-2 text-lg font-semibold">Shared MSO flow</h2>
+ <p className="mb-5 text-sm leading-relaxed text-muted-foreground">These are the common product steps after the platform-specific setup above.</p>
<ol className="space-y-8">
{STEPS.map((step) => (
<li key={step.n} className="grid grid-cols-[2rem_1fr] gap-x-3">
diff --git a/app/install/platform-tabs.tsx b/app/install/platform-tabs.tsx
new file mode 100644
index 00000000..79047d33
--- /dev/null
+++ b/app/install/platform-tabs.tsx
@@ -0,0 +1,194 @@
+"use client";
+
+import * as React from "react";
+import { ExternalLink } from "lucide-react";
+import { PLATFORM_INSTALL_GUIDES } from "@/lib/platform-install-guides";
+import { PLATFORM_SUPPORT, type MsoPlatformId } from "@/lib/platform-support";
+import { Copy } from "./copy";
+
+const PLATFORM_IDS = PLATFORM_SUPPORT.map((platform) => platform.id);
+
+function isPlatformId(value: string | null): value is MsoPlatformId {
+ return value !== null && PLATFORM_IDS.includes(value as MsoPlatformId);
+}
+
+const PLATFORM_CHANGE_EVENT = "mso:install-platform-change";
+
+function currentPlatform(): MsoPlatformId {
+ const selected = new URLSearchParams(window.location.search).get("platform");
+ return isPlatformId(selected) ? selected : "linux";
+}
+
+function subscribePlatformChange(onChange: () => void) {
+ window.addEventListener("popstate", onChange);
+ window.addEventListener(PLATFORM_CHANGE_EVENT, onChange);
+ return () => {
+ window.removeEventListener("popstate", onChange);
+ window.removeEventListener(PLATFORM_CHANGE_EVENT, onChange);
+ };
+}
+
+export function PlatformInstallTabs() {
+ const active = React.useSyncExternalStore<MsoPlatformId>(subscribePlatformChange, currentPlatform, () => "linux");
+
+ const select = React.useCallback((id: MsoPlatformId) => {
+ const url = new URL(window.location.href);
+ url.searchParams.set("platform", id);
+ window.history.replaceState(null, "", url);
+ window.dispatchEvent(new Event(PLATFORM_CHANGE_EVENT));
+ }, []);
+
+ const activePlatform = PLATFORM_SUPPORT.find((platform) => platform.id === active) ?? PLATFORM_SUPPORT[0];
+ const guide = PLATFORM_INSTALL_GUIDES[active];
+
+ const selectAndFocus = (id: MsoPlatformId) => {
+ select(id);
+ requestAnimationFrame(() => document.getElementById(`platform-tab-${id}`)?.focus());
+ };
+
+ const move = (current: MsoPlatformId, offset: number) => {
+ const index = PLATFORM_IDS.indexOf(current);
+ const next = PLATFORM_IDS[(index + offset + PLATFORM_IDS.length) % PLATFORM_IDS.length];
+ selectAndFocus(next);
+ };
+
+ return (
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ <div
+ role="tablist"
+ aria-label="MSO installation platform"
+ className="flex overflow-x-auto border-b border-border bg-muted/30 p-1.5"
+ >
+ {PLATFORM_SUPPORT.map((platform) => (
+ <button
+ key={platform.id}
+ id={`platform-tab-${platform.id}`}
+ type="button"
+ role="tab"
+ aria-selected={active === platform.id}
+ aria-controls={`platform-panel-${platform.id}`}
+ tabIndex={active === platform.id ? 0 : -1}
+ onClick={() => select(platform.id)}
+ onKeyDown={(event) => {
+ if (event.key === "ArrowRight") { event.preventDefault(); move(platform.id, 1); }
+ if (event.key === "ArrowLeft") { event.preventDefault(); move(platform.id, -1); }
+ if (event.key === "Home") { event.preventDefault(); selectAndFocus(PLATFORM_IDS[0]); }
+ if (event.key === "End") { event.preventDefault(); selectAndFocus(PLATFORM_IDS[PLATFORM_IDS.length - 1]); }
+ }}
+ className={[
+ "min-h-10 shrink-0 rounded-lg px-3 py-2 text-left text-sm transition-colors",
+ active === platform.id
+ ? "bg-background font-medium text-foreground shadow-sm"
+ : "text-muted-foreground hover:bg-background/70 hover:text-foreground",
+ ].join(" ")}
+ >
+ <span className="block whitespace-nowrap">{platform.label}</span>
+ <span className="mt-0.5 block whitespace-nowrap text-[10px] font-normal text-muted-foreground">
+ {platform.modeLabel}
+ </span>
+ </button>
+ ))}
+ </div>
+
+ <div
+ id={`platform-panel-${active}`}
+ role="tabpanel"
+ aria-labelledby={`platform-tab-${active}`}
+ className="p-4 sm:p-6"
+ >
+ <div className="flex flex-col gap-3 border-b border-border pb-5 sm:flex-row sm:items-start sm:justify-between">
+ <div>
+ <div className="flex flex-wrap items-center gap-2">
+ <h3 className="text-xl font-semibold tracking-tight">{activePlatform.label}</h3>
+ <span className="rounded-full border border-border bg-muted/40 px-2 py-0.5 text-xs text-muted-foreground">
+ {activePlatform.modeLabel}
+ </span>
+ </div>
+ <p className="mt-2 max-w-2xl text-sm leading-relaxed text-muted-foreground">{activePlatform.summary}</p>
+ <p className="mt-2 text-xs text-muted-foreground">
+ MSO manages: <span className="font-medium text-foreground">{activePlatform.hostScope}</span>
+ </p>
+ </div>
+ <p className="max-w-sm rounded-lg border border-border bg-muted/30 px-3 py-2 text-xs leading-relaxed text-muted-foreground">
+ <span className="font-medium text-foreground">Best for:</span> {guide.bestFor}
+ </p>
+ </div>
+
+ <section className="mt-6" aria-labelledby={`requirements-${active}`}>
+ <h4 id={`requirements-${active}`} className="text-sm font-semibold">Before you start</h4>
+ <ul className="mt-3 grid gap-2 md:grid-cols-2">
+ {guide.prerequisites.map((item) => (
+ <li key={item} className="rounded-lg border border-border bg-muted/20 px-3 py-2 text-sm leading-relaxed text-muted-foreground">
+ {item}
+ </li>
+ ))}
+ </ul>
+ </section>
+
+ <section className="mt-7" aria-labelledby={`steps-${active}`}>
+ <div className="flex flex-wrap items-end justify-between gap-2">
+ <div>
+ <h4 id={`steps-${active}`} className="text-sm font-semibold">Step by step</h4>
+ <p className="mt-1 text-xs text-muted-foreground">Follow in order. Commands can be copied directly.</p>
+ </div>
+ {activePlatform.installCommand ? (
+ <span className="text-xs text-muted-foreground">{guide.steps.length} steps</span>
+ ) : null}
+ </div>
+ <ol className="mt-4 space-y-5">
+ {guide.steps.map((step, index) => (
+ <li key={step.title} className="grid grid-cols-[2rem_minmax(0,1fr)] gap-3">
+ <span className="flex size-8 items-center justify-center rounded-full border border-border bg-muted/30 text-xs font-semibold tabular-nums">
+ {index + 1}
+ </span>
+ <div className="min-w-0">
+ <h5 className="text-sm font-semibold">{step.title}</h5>
+ <p className="mt-1 text-sm leading-relaxed text-muted-foreground">{step.body}</p>
+ {step.command ? <Copy text={step.command} /> : null}
+ {step.note ? (
+ <p className="mt-2 rounded-md border border-border bg-muted/20 px-3 py-2 text-xs leading-relaxed text-muted-foreground">
+ <span className="font-medium text-foreground">Note:</span> {step.note}
+ </p>
+ ) : null}
+ </div>
+ </li>
+ ))}
+ </ol>
+ </section>
+
+ <section className="mt-7 grid gap-6 lg:grid-cols-2">
+ <div>
+ <h4 className="text-sm font-semibold">Troubleshooting</h4>
+ <ul className="mt-3 space-y-2">
+ {guide.troubleshooting.map((item) => (
+ <li key={item} className="rounded-lg border border-border px-3 py-2 text-sm leading-relaxed text-muted-foreground">
+ {item}
+ </li>
+ ))}
+ </ul>
+ </div>
+ <div>
+ <h4 className="text-sm font-semibold">Official links & references</h4>
+ <div className="mt-3 space-y-2">
+ {guide.links.map((link) => (
+ <a
+ key={link.href}
+ href={link.href}
+ target="_blank"
+ rel="noreferrer"
+ className="block rounded-lg border border-border px-3 py-2 transition-colors hover:bg-muted/40"
+ >
+ <span className="flex items-center gap-1.5 text-sm font-medium">
+ {link.label}
+ <ExternalLink className="size-3.5 text-muted-foreground" aria-hidden />
+ </span>
+ <span className="mt-1 block text-xs leading-relaxed text-muted-foreground">{link.description}</span>
+ </a>
+ ))}
+ </div>
+ </div>
+ </section>
+ </div>
+ </div>
+ );
+}
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index b768a09e..90c77831 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,10 +8,12 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
**Added**
+- `install` add detailed platform tabs
- `mcp` encode agent bootstrap and capability-parity map
**Fixed**
+- `ai` separate provider connect from selection
- `security` bind Convex snapshot path identity
- `browser` derive isolated Camoufox viewer origin
- `browser` probe cache-isolated Camoufox path
diff --git a/lib/platform-install-guides.ts b/lib/platform-install-guides.ts
new file mode 100644
index 00000000..d9ab5f63
--- /dev/null
+++ b/lib/platform-install-guides.ts
@@ -0,0 +1,178 @@
+import type { MsoPlatformId } from "./platform-support";
+
+export type PlatformGuideStep = {
+ title: string;
+ body: string;
+ command?: string;
+ note?: string;
+};
+
+export type PlatformGuideLink = {
+ label: string;
+ href: string;
+ description: string;
+};
+
+export type PlatformInstallGuide = {
+ id: MsoPlatformId;
+ bestFor: string;
+ prerequisites: readonly string[];
+ steps: readonly PlatformGuideStep[];
+ troubleshooting: readonly string[];
+ links: readonly PlatformGuideLink[];
+};
+
+const INSTALL = "curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash";
+const WINDOWS_INSTALL = "iwr -useb https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install-windows.ps1 | iex";
+const MSO_REPO = "https://github.com/rahmanef63/mso";
+const MSO_PLATFORMS = `${MSO_REPO}/blob/main/docs/PLATFORMS.md`;
+const MSO_INSTALL_DOC = `${MSO_REPO}/blob/main/docs/INSTALL.md`;
+
+export const PLATFORM_INSTALL_GUIDES: Record<MsoPlatformId, PlatformInstallGuide> = {
+ linux: {
+ id: "linux",
+ bestFor: "VPS, home server, workstation, container-like Linux hosts, and always-on production.",
+ prerequisites: [
+ "Use a normal non-root user with sudo when package installation is needed.",
+ "Keep about 2 GB free for dependencies and the production build.",
+ "The installer handles supported Node/Bun/build prerequisites where possible; manual Node/Bun links are included below for recovery.",
+ "Keep the default 127.0.0.1 bind unless you deliberately put a protected HTTPS layer in front.",
+ ],
+ steps: [
+ { title: "Open a terminal as your normal user", body: "Do not switch to root. MSO host actions execute with the runtime user's authority.", command: "whoami\nid -u" },
+ { title: "Run the canonical installer", body: "This installs or updates the checkout, validates the CLI, builds production, creates owner auth on first install, and uses systemd only when it is actually available.", command: INSTALL },
+ { title: "Complete onboarding", body: "Connect an AI provider, choose the model/preset, and optionally add managed apps or reviewed skills.", command: "mso onboard\nmso skills available" },
+ { title: "Verify the host runtime", body: "Doctor should report the actual Linux capabilities instead of assuming the install worked.", command: "mso --version\nmso doctor\nmso -h" },
+ { title: "Open the workspace", body: "Start or open the browser workspace. The raw app stays on loopback by default.", command: "mso web", note: "Local browser: http://127.0.0.1:4005" },
+ { title: "Add protected remote access when needed", body: "Prefer Tailscale Serve or a named HTTPS reverse-proxy/tunnel. Do not publish the raw shell port directly.", command: "tailscale serve 4005", note: "Cloudflare Tunnel is also supported as an optional gateway adapter; see the official link below." },
+ ],
+ troubleshooting: [
+ "Run mso doctor --fix for safe local repairs, then rerun mso doctor.",
+ "If node-pty fails to compile, confirm a C/C++ compiler, make, Python 3, and supported Node are available.",
+ "If login loops on a remote IP, use HTTPS or tunnel to localhost; MSO's session cookie is Secure.",
+ ],
+ links: [
+ { label: "MSO install reference", href: MSO_INSTALL_DOC, description: "Canonical flags, update path, TLS and recovery." },
+ { label: "Node.js downloads", href: "https://nodejs.org/en/download", description: "Official Node download and supported release information." },
+ { label: "Bun installation", href: "https://bun.sh/docs/installation", description: "Official Bun installation and PATH recovery." },
+ { label: "Tailscale Serve", href: "https://tailscale.com/docs/features/tailscale-serve", description: "Private HTTPS access inside your tailnet." },
+ { label: "Cloudflare Tunnel", href: "https://developers.cloudflare.com/tunnel/get-started/", description: "Named HTTPS tunnel for a stable public hostname." },
+ ],
+ },
+ macos: {
+ id: "macos",
+ bestFor: "Developers who want MSO locally on a Mac while preserving the same Linux host semantics as a server.",
+ prerequisites: [
+ "A supported macOS machine with enough RAM/disk for a lightweight Linux VM.",
+ "Lima is the compatibility host. If Lima is missing, the bootstrap can install it through Homebrew when Homebrew already exists.",
+ "If neither Lima nor Homebrew exists, install Homebrew or Lima first using the official links below.",
+ "MSO manages the Lima Linux guest, not native launchd services or arbitrary macOS processes.",
+ ],
+ steps: [
+ { title: "Open Terminal", body: "Use your normal macOS account. You do not need to create a Linux VM manually." },
+ { title: "Optional: prepare Lima manually", body: "Skip this when limactl already works. The MSO installer will reuse an existing instance named mso.", command: "command -v limactl >/dev/null || brew install lima" },
+ { title: "Run the same MSO installer", body: "The public bootstrap detects Darwin, verifies the macOS adapter, creates/starts Lima, then installs MSO inside its Linux guest.", command: INSTALL },
+ { title: "Refresh the current shell if needed", body: "The installer persists ~/.local/bin for future shells; export it manually only when this already-open terminal cannot resolve mso.", command: "export PATH=\"$HOME/.local/bin:$PATH\"\ncommand -v mso" },
+ { title: "Verify the guest-backed host", body: "These commands run through the macOS launcher into the Lima guest.", command: "mso --version\nmso doctor" },
+ { title: "Open MSO", body: "Start the web workspace, then use the forwarded localhost port from Safari/Chrome on macOS.", command: "mso web", note: "Open http://127.0.0.1:4005 if the browser does not open automatically." },
+ { title: "Inspect or recover Lima", body: "Use Lima's CLI when the guest itself needs inspection.", command: "limactl list\nlimactl start mso\nlimactl shell mso" },
+ ],
+ troubleshooting: [
+ "If 'brew: command not found', install Homebrew first or install Lima directly from its official release/documentation.",
+ "If 'mso: command not found' immediately after install, export ~/.local/bin into PATH or open a new terminal.",
+ "If the guest is stopped after a reboot, the mso launcher starts it automatically; limactl start mso is the manual fallback.",
+ ],
+ links: [
+ { label: "Lima installation", href: "https://lima-vm.io/docs/installation/", description: "Official Lima install methods and host requirements." },
+ { label: "Homebrew", href: "https://brew.sh/", description: "Official Homebrew installer used when Lima is absent." },
+ { label: "MSO platform contract", href: MSO_PLATFORMS, description: "Why macOS uses a Linux guest instead of partial native host emulation." },
+ { label: "MSO source", href: MSO_REPO, description: "Repository, issues and current release source." },
+ ],
+ },
+ windows: {
+ id: "windows",
+ bestFor: "Windows 10/11 users who want the full MSO host runtime without maintaining a separate VPS.",
+ prerequisites: [
+ "Windows 10 version 2004+ or Windows 11 for the modern WSL install flow.",
+ "WSL2 is the stable MSO host path; the bootstrap reuses a normal existing distro when possible and ignores docker-desktop distros.",
+ "Use PowerShell. Administrator elevation is needed when Windows itself still needs WSL installed.",
+ "MSO manages the Linux distro inside WSL2, not Windows Service Control Manager or arbitrary Win32 processes.",
+ ],
+ steps: [
+ { title: "Open PowerShell", body: "If WSL is already installed, a normal PowerShell window is enough. If this is the first WSL setup, reopen PowerShell as Administrator." },
+ { title: "Run the Windows bootstrap", body: "It finds an existing Linux distro or installs Ubuntu, then runs the canonical MSO Linux installer inside WSL2.", command: WINDOWS_INSTALL },
+ { title: "Complete first-time WSL setup when prompted", body: "If the command installed WSL/Ubuntu, restart Windows when requested, launch the distro once, create the Linux username/password, then rerun the same MSO PowerShell command.", command: "wsl --status\nwsl -l -v" },
+ { title: "Enter WSL and verify MSO", body: "Use the distro shell for direct diagnostics.", command: "wsl\nexport PATH=\"$HOME/.local/bin:$HOME/.bun/bin:$PATH\"\nmso --version\nmso doctor" },
+ { title: "Start/open the workspace", body: "Run from WSL. WSL2 normally forwards Linux localhost services to Windows localhost.", command: "mso web", note: "Open http://localhost:4005 in Edge/Chrome when it does not open automatically." },
+ { title: "Recover WSL networking/runtime", body: "Update WSL or restart its VM without touching the MSO repository.", command: "wsl --update\nwsl --shutdown", note: "Reopen the distro, then rerun mso doctor." },
+ ],
+ troubleshooting: [
+ "If wsl.exe is missing, follow Microsoft's WSL installation guide and rerun the MSO bootstrap after the required reboot.",
+ "If no distro appears in wsl -l -v, install one with wsl --install -d Ubuntu, complete first launch, then rerun MSO.",
+ "If Windows cannot reach port 4005, verify mso web is running inside WSL and review Microsoft's localhost-forwarding documentation.",
+ ],
+ links: [
+ { label: "Install WSL", href: "https://learn.microsoft.com/windows/wsl/install", description: "Microsoft's official WSL installation guide and requirements." },
+ { label: "WSL networking", href: "https://learn.microsoft.com/windows/wsl/networking", description: "Official localhost forwarding and networking behavior." },
+ { label: "MSO platform contract", href: MSO_PLATFORMS, description: "Windows host scope, WSL2 boundary and shared invariants." },
+ { label: "MSO source", href: MSO_REPO, description: "Repository and current installer source." },
+ ],
+ },
+ android: {
+ id: "android",
+ bestFor: "Portable/local MSO on an Android phone or tablet without root access.",
+ prerequisites: [
+ "Install a current Termux build from F-Droid or the official Termux GitHub releases.",
+ "No Android root access is required.",
+ "The adapter runs Ubuntu in PRoot because native Android/Termux does not provide the exact Linux/Bun/native-module runtime MSO expects.",
+ "Android battery/background policies can suspend long-running processes, so an always-on Linux host remains preferable for production.",
+ ],
+ steps: [
+ { title: "Install and open Termux", body: "Use F-Droid or the official Termux project release links below. Do not mix plugin/app signing sources." },
+ { title: "Run the canonical installer", body: "The public MSO bootstrap detects Termux, repairs/updates required packages, installs/reuses Ubuntu PRoot, creates a non-root guest owner, and installs the Termux-side mso launcher.", command: INSTALL },
+ { title: "Verify the launcher and guest", body: "The mso launcher automatically enters the Ubuntu guest, so normal commands stay identical to Linux.", command: "mso --version\nmso doctor\nmso -h" },
+ { title: "Complete onboarding", body: "Configure your model/provider from the same terminal flow.", command: "mso onboard" },
+ { title: "Open the browser workspace", body: "Run the web command from Termux and open the local URL in your Android browser.", command: "mso web", note: "Open http://127.0.0.1:4005 on the same device." },
+ { title: "Inspect the Ubuntu guest when needed", body: "This is for low-level recovery; routine MSO use should stay on the mso launcher.", command: "proot-distro login mso-ubuntu --user mso" },
+ ],
+ troubleshooting: [
+ "If Termux package operations fail, run apt update && apt full-upgrade -y; use termux-change-repo if the selected mirror is unavailable.",
+ "If curl cannot start after a partial upgrade, reinstall the Termux OpenSSL/curl package set as documented in MSO's TERMUX.md.",
+ "If Android kills the process in the background, adjust battery optimization for Termux or move the always-on host to Linux/VPS.",
+ ],
+ links: [
+ { label: "Termux on F-Droid", href: "https://f-droid.org/packages/com.termux/", description: "F-Droid package page for Termux." },
+ { label: "Official Termux project", href: "https://github.com/termux/termux-app", description: "Official installation notes and GitHub releases." },
+ { label: "PRoot-Distro", href: "https://github.com/termux/proot-distro", description: "Rootless Linux userland used by the Android adapter." },
+ { label: "MSO Android guide", href: `${MSO_REPO}/blob/main/docs/TERMUX.md`, description: "MSO-specific repair, guest and verification details." },
+ ],
+ },
+ ios: {
+ id: "ios",
+ bestFor: "Using MSO from iPhone/iPad as an operator console, PWA, terminal and agent client.",
+ prerequisites: [
+ "You need an MSO host running on Linux, macOS/Lima, Windows/WSL2, or Android/PRoot.",
+ "For remote use, expose MSO through a protected HTTPS hostname. Plain HTTP to a remote server IP cannot persist MSO's Secure session cookie.",
+ "iOS/iPadOS is intentionally a client surface; it does not run the unrestricted persistent Node/Bun host runtime.",
+ ],
+ steps: [
+ { title: "Prepare an MSO host", body: "Install MSO on one of the host-capable platforms first and verify it with mso doctor.", command: "mso doctor" },
+ { title: "Give the host a safe URL", body: "Use Tailscale Serve for private access or a stable HTTPS reverse proxy/named tunnel for public access.", command: "tailscale serve 4005", note: "Keep the raw MSO listener on 127.0.0.1." },
+ { title: "Open MSO in Safari", body: "Navigate to the protected HTTPS MSO URL and sign in with the owner password." },
+ { title: "Approve the iPhone/iPad device", body: "From an already-approved owner terminal/device, approve the pending browser device ID.", command: "mso device pending\nmso device approve <deviceId> \"my iPhone\"" },
+ { title: "Install the PWA", body: "In Safari tap Page Menu/Share → Add to Home Screen → enable Open as Web App → Add. Apple documents this exact flow in the link below." },
+ { title: "Use MSO like an app", body: "Launch it from the Home Screen. The iOS shell, terminal, files, agents and workflows operate against the connected MSO host." },
+ ],
+ troubleshooting: [
+ "If login repeats, verify the URL is HTTPS and do not switch between server IP, tunnel hostname and another origin during device pairing.",
+ "If Add to Home Screen is missing, Apple advises using Share → Edit Actions and enabling Add to Home Screen.",
+ "If the host is unreachable, diagnose the host/tunnel first; the iOS app surface cannot start a remote host that is offline.",
+ ],
+ links: [
+ { label: "Apple: turn a website into an app", href: "https://support.apple.com/guide/iphone/open-as-web-app-iphea86e5236/ios", description: "Official Add to Home Screen / Open as Web App steps." },
+ { label: "Tailscale Serve", href: "https://tailscale.com/docs/features/tailscale-serve", description: "Private HTTPS access from your tailnet." },
+ { label: "Cloudflare Tunnel", href: "https://developers.cloudflare.com/tunnel/get-started/", description: "Stable HTTPS hostname without exposing the raw MSO port." },
+ { label: "MSO platform contract", href: MSO_PLATFORMS, description: "Why iOS/iPadOS is a client rather than a host runtime." },
+ ],
+ },
+};
diff --git a/lib/platform-support.test.ts b/lib/platform-support.test.ts
index 1984f542..22a92461 100644
--- a/lib/platform-support.test.ts
+++ b/lib/platform-support.test.ts
@@ -4,10 +4,12 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { describe, expect, it } from "vitest";
+import { PLATFORM_INSTALL_GUIDES } from "./platform-install-guides";
import { PLATFORM_SUPPORT, platformSupport } from "./platform-support";
const ROOT = path.join(__dirname, "..");
const INSTALL_PAGE = fs.readFileSync(path.join(ROOT, "app/install/page.tsx"), "utf8");
+const PLATFORM_TABS = fs.readFileSync(path.join(ROOT, "app/install/platform-tabs.tsx"), "utf8");
const INSTALLER_PATH = path.join(ROOT, "scripts/install.sh");
const INSTALLER = fs.readFileSync(INSTALLER_PATH, "utf8");
const MACOS_INSTALLER = fs.readFileSync(path.join(ROOT, "scripts/install-macos.sh"), "utf8");
@@ -56,7 +58,25 @@ describe("MSO platform support contract", () => {
"android",
"ios",
]);
- expect(INSTALL_PAGE).toContain("PLATFORM_SUPPORT.map((platform)");
+ expect(INSTALL_PAGE).toContain("<PlatformInstallTabs />");
+ expect(PLATFORM_TABS).toContain("PLATFORM_SUPPORT.map((platform)");
+ });
+
+ it("keeps every platform tab detailed and link-backed", () => {
+ for (const platform of PLATFORM_SUPPORT) {
+ const guide = PLATFORM_INSTALL_GUIDES[platform.id];
+ expect(guide.id).toBe(platform.id);
+ expect(guide.prerequisites.length).toBeGreaterThanOrEqual(3);
+ expect(guide.steps.length).toBeGreaterThanOrEqual(5);
+ expect(guide.troubleshooting.length).toBeGreaterThanOrEqual(3);
+ expect(guide.links.length).toBeGreaterThanOrEqual(4);
+ for (const link of guide.links) expect(link.href).toMatch(/^https:\/\//);
+ }
+ expect(PLATFORM_TABS).toContain('role="tablist"');
+ expect(PLATFORM_TABS).toContain('role="tabpanel"');
+ expect(PLATFORM_TABS).toContain('url.searchParams.set("platform", id)');
+ expect(PLATFORM_TABS).toContain("Step by step");
+ expect(PLATFORM_TABS).toContain("Official links & references");
});
it("prevents macOS from silently disappearing from install UX", () => {