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.

docs(termux): add one-pass Android installer

Rahman7bacd2147b47
diff --git a/README.md b/README.md
index 203c5ec0..baf5741f 100644
--- a/README.md
+++ b/README.md
@@ -56,7 +56,7 @@ mso --continue # resume your last session
```
The application binds to **127.0.0.1** by default. Use a VPN or protected HTTPS proxy for remote access.
-[Full installation and WSL guide](./docs/INSTALL.md) · [CLI reference](./docs/CLI.md)
+[Full installation and WSL guide](./docs/INSTALL.md) · [Android / Termux one-paste install](./docs/TERMUX.md) · [CLI reference](./docs/CLI.md)
<details>
<summary><strong>Update, reset or uninstall — preview before changing anything</strong></summary>
diff --git a/docs/README.md b/docs/README.md
index 8ab59c62..dd4959b4 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -26,6 +26,7 @@ evidence and review freshness. The repository quality gate runs both automatical
| [`COMPARISON.md`](./COMPARISON.md) | Generated product comparison methodology, evidence and notes |
| [`COMPETITIVE-ROADMAP.md`](./COMPETITIVE-ROADMAP.md) | Executed comparison plan, deliberate specialist boundaries and next investments |
| [`INSTALL.md`](./INSTALL.md) | Owner installation, TLS, updates, backup and uninstall |
+| [`TERMUX.md`](./TERMUX.md) | Android/Termux bootstrap through Ubuntu PRoot, repair path and verification |
| [`INFRASTRUCTURE-PROVIDERS.md`](./INFRASTRUCTURE-PROVIDERS.md) | Interactive MSO Agent TUI/approval/error contract plus Dokploy/Cloudflare/Hostinger/Composio credentials, tools and deployment boundary |
| [`DEVELOPMENT.md`](./DEVELOPMENT.md) | Development and release workflow |
| [`SECURITY-ASSURANCE.md`](./SECURITY-ASSURANCE.md) | Repeatable security verification lanes, public evidence, and claim boundaries |
diff --git a/docs/TERMUX.md b/docs/TERMUX.md
new file mode 100644
index 00000000..236d6ca2
--- /dev/null
+++ b/docs/TERMUX.md
@@ -0,0 +1,177 @@
+# Install MSO on Android with Termux
+
+> **Supported Android path:** Termux hosts an Ubuntu PRoot environment, and MSO runs inside that normal Linux userspace. The `mso` launcher is still installed into Termux, so normal commands remain `mso`, `mso doctor`, `mso web`, and `mso --continue`.
+
+MSO should not be installed directly into native Android/Termux today. MSO uses Bun plus native Node modules such as `node-pty`; Bun does not currently support Android/Termux as a native target. Ubuntu PRoot avoids the Android libc/platform mismatch and gives MSO the same Linux environment used by the normal installer.
+
+References:
+
+- Termux PRoot-Distro: https://github.com/termux/proot-distro
+- Bun Termux/Android support request (closed as not planned): https://github.com/oven-sh/bun/issues/29778
+
+## One-paste install
+
+Run this in Termux:
+
+```bash
+apt update && apt full-upgrade -y && \
+apt install -y curl ca-certificates proot-distro && \
+curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install-termux.sh | bash
+```
+
+The Termux bootstrap is idempotent. Re-running the same command repairs/upgrades the host packages, reuses the `mso-ubuntu` PRoot environment when it already exists, and runs the normal MSO installer again to update the existing checkout.
+
+The script deliberately does **not** enable YOLO mode.
+
+## What the installer does
+
+1. Runs `apt update` and `apt full-upgrade` in Termux first. This is also the recovery path for partial Termux upgrades where `curl` cannot start because OpenSSL/QUIC libraries no longer match.
+2. Installs `curl`, CA certificates, and `proot-distro` in Termux.
+3. Creates an Ubuntu 24.04 PRoot named `mso-ubuntu`, or reuses it.
+4. Creates a non-root Linux user named `mso` inside the guest.
+5. Installs Linux build/runtime prerequisites inside Ubuntu.
+6. Runs MSO's canonical `scripts/install.sh` inside Ubuntu with `--no-service --no-onboard`.
+7. Installs a small Termux-side launcher at `$PREFIX/bin/mso` that enters the Ubuntu guest automatically.
+8. Verifies `mso --version` and `mso -h` before returning success.
+
+The actual MSO installation remains owned by the normal Linux installer. The Termux script is only an Android compatibility/bootstrap layer.
+
+## After installation
+
+Use MSO directly from the normal Termux prompt:
+
+```bash
+mso --version
+mso doctor
+mso
+mso web
+mso --continue
+```
+
+For first-time provider/account setup:
+
+```bash
+mso onboard
+```
+
+`mso web` is the relevant browser path because a PRoot guest does not provide a normal systemd PID 1. Keep the default loopback bind unless you deliberately configure protected HTTPS access.
+
+## If `curl` is broken before installation
+
+A partial Termux upgrade can leave `curl`, OpenSSL, `libcurl`, or `libngtcp2` out of sync. A typical symptom is:
+
+```text
+CANNOT LINK EXECUTABLE "curl": cannot locate symbol "SSL_set_quic_tls_transport_params"
+```
+
+Repair the package set with `apt` first:
+
+```bash
+apt update
+apt full-upgrade -y
+apt install --reinstall -y openssl libcurl curl ca-certificates
+```
+
+Then verify:
+
+```bash
+curl --version
+openssl version
+```
+
+If repository selection itself is broken, run:
+
+```bash
+termux-change-repo
+```
+
+Choose a working **Main repository**, then repeat the repair commands.
+
+## Why not native Termux?
+
+Native Termux reports Node's platform as `android`, not `linux`. That distinction matters for packages that publish Linux-only native binaries. It is the same class of problem visible when installing tools such as Codex CLI directly in Termux: the JavaScript wrapper may install while an optional Linux ARM64 binary is skipped because npm sees `android/arm64` rather than `linux/arm64`.
+
+MSO has an additional blocker: Bun currently publishes Linux/macOS/Windows targets, not a supported Android/Termux target. Running MSO in Ubuntu PRoot is therefore the stable default rather than maintaining a growing list of native Android binary workarounds.
+
+## Codex CLI note
+
+Codex CLI is **not required** to install MSO. MSO has its own model/provider integration and onboarding.
+
+If you separately want Codex CLI on Android, prefer installing it inside the same Ubuntu PRoot environment rather than native Termux. Native Termux can hit both binary-platform and authentication/networking issues. There have also been Codex TUI reports specific to Android/Termux environments; if a future Codex version regresses in a foreground terminal, `tmux` inside the Linux guest can be used as a TUI workaround, but it is unrelated to the MSO installer itself.
+
+Do not hardcode a stale `@openai/codex-linux-arm64` version into MSO documentation. If a native workaround is ever needed, the wrapper and platform package versions must match exactly.
+
+## PRoot limitations
+
+This Android installation is optimized for MSO CLI and local browser workspace use. It is not equivalent to a normal VPS:
+
+- no normal systemd service is installed;
+- host/service integrations that require systemd may be unavailable;
+- long-running Android processes are still subject to Android background/battery policies;
+- performance is lower than a native Linux host because PRoot translates filesystem/syscall paths in userspace.
+
+For always-on production hosting, install MSO on a normal Linux VPS and use Termux as the client/operator terminal instead.
+
+## Security
+
+MSO can execute commands as its Linux owner. `mso --yolo` automatically approves write and exec actions for that process. Do not make YOLO the default in shared/untrusted environments.
+
+The Android bootstrap creates passwordless `sudo` only for the dedicated `mso` user **inside the isolated PRoot guest** so the canonical MSO installer can install Linux dependencies without interactive password setup. It does not grant Android root access.
+
+## Troubleshooting
+
+### `No mirror or mirror group selected`
+
+If package operations still reach a working mirror, the warning is informational. If downloads fail, run `termux-change-repo` and select a working Main repository.
+
+### `mso: command not found`
+
+Verify the Termux launcher exists:
+
+```bash
+ls -l "$PREFIX/bin/mso"
+```
+
+Then rerun the one-paste installer. It recreates the launcher idempotently.
+
+### Inspect the Ubuntu guest
+
+```bash
+proot-distro login mso-ubuntu --user mso
+```
+
+Inside it:
+
+```bash
+export PATH="$HOME/.local/bin:$HOME/.bun/bin:$PATH"
+mso --version
+mso doctor
+```
+
+### Reset only the Android compatibility environment
+
+Do not remove the PRoot distro as a routine repair: it contains the MSO checkout and private MSO state for that guest. Prefer rerunning the installer. If you intentionally want a destructive fresh start, back up the required MSO state first and consult the PRoot-Distro removal documentation.
+
+## Verification checklist
+
+After installation:
+
+```bash
+mso --version
+mso doctor
+mso -h >/dev/null && echo "MSO CLI OK"
+```
+
+Then start an interactive session:
+
+```bash
+mso
+```
+
+For the browser workspace:
+
+```bash
+mso web
+```
+
+The install is considered healthy when the Termux launcher enters the Ubuntu guest, the MSO CLI resolves there, and `mso doctor` reports no unexpected runtime failure beyond capabilities intentionally unavailable without systemd.
diff --git a/scripts/install-termux.sh b/scripts/install-termux.sh
new file mode 100755
index 00000000..606d510f
--- /dev/null
+++ b/scripts/install-termux.sh
@@ -0,0 +1,92 @@
+#!/data/data/com.termux/files/usr/bin/bash
+# MSO bootstrap for Termux/Android.
+#
+# Supported architecture:
+# Termux host -> Ubuntu PRoot -> normal MSO Linux installer (--no-service)
+#
+# Native Android/Termux is deliberately not used for the MSO runtime because
+# MSO depends on Bun and native Node modules. Keeping the runtime in a normal
+# Linux userspace also avoids Android-specific libc/platform mismatches.
+set -Eeuo pipefail
+umask 077
+
+DISTRO="${MSO_TERMUX_DISTRO:-mso-ubuntu}"
+GUEST_USER="${MSO_TERMUX_USER:-mso}"
+IMAGE="${MSO_TERMUX_IMAGE:-ubuntu:24.04}"
+INSTALL_URL="${MSO_TERMUX_INSTALL_URL:-https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh}"
+TERMUX_BIN="${PREFIX:-/data/data/com.termux/files/usr}/bin"
+
+info() { printf '· %s\n' "$*"; }
+ok() { printf '✓ %s\n' "$*"; }
+fail() { printf '✗ %s\n' "$*" >&2; exit 1; }
+
+case "${PREFIX:-}" in
+ */com.termux/files/usr) ;;
+ *) fail 'run this installer from Termux on Android.' ;;
+esac
+
+command -v apt >/dev/null 2>&1 || fail 'Termux apt is missing.'
+
+info 'repairing/updating Termux packages'
+if ! apt update; then
+ printf '\nRepository update failed. Run `termux-change-repo`, choose a working Main repository, then retry.\n' >&2
+ exit 1
+fi
+DEBIAN_FRONTEND=noninteractive apt full-upgrade -y
+
+# Use apt directly here: when a partial Termux upgrade breaks curl, `pkg` can
+# fail before it gets a chance to repair the affected libraries.
+DEBIAN_FRONTEND=noninteractive apt install -y curl ca-certificates proot-distro
+
+command -v curl >/dev/null 2>&1 || fail 'curl is still unavailable after package repair.'
+command -v proot-distro >/dev/null 2>&1 || fail 'proot-distro installation failed.'
+curl --version >/dev/null 2>&1 || fail 'curl is installed but cannot start; run `apt update && apt full-upgrade -y` again.'
+
+if proot-distro login "$DISTRO" -- /bin/true >/dev/null 2>&1; then
+ info "reusing existing PRoot distro: $DISTRO"
+else
+ info "installing $IMAGE as $DISTRO"
+ proot-distro install "$IMAGE" --name "$DISTRO"
+fi
+
+info 'preparing Ubuntu guest dependencies and non-root MSO owner'
+proot-distro login "$DISTRO" -- bash -lc "
+ set -Eeuo pipefail
+ export DEBIAN_FRONTEND=noninteractive
+ apt-get update
+ apt-get install -y sudo curl ca-certificates git jq coreutils util-linux build-essential python3 passwd
+ if ! id -u '$GUEST_USER' >/dev/null 2>&1; then
+ useradd -m -s /bin/bash '$GUEST_USER'
+ fi
+ printf '%s ALL=(ALL) NOPASSWD:ALL\\n' '$GUEST_USER' > '/etc/sudoers.d/$GUEST_USER'
+ chmod 0440 '/etc/sudoers.d/$GUEST_USER'
+"
+
+info 'installing/updating MSO inside Ubuntu'
+proot-distro login "$DISTRO" --user "$GUEST_USER" -- bash -lc "
+ set -Eeuo pipefail
+ export PATH=\"\$HOME/.local/bin:\$HOME/.bun/bin:\$PATH\"
+ curl -fsSL '$INSTALL_URL' | bash -s -- --no-service --no-onboard
+ command -v mso >/dev/null 2>&1
+ mso --version
+ mso -h >/dev/null
+"
+
+LAUNCHER="$TERMUX_BIN/mso"
+info "installing Termux launcher: $LAUNCHER"
+cat > "$LAUNCHER" <<EOF
+#!$TERMUX_BIN/bash
+set -Eeuo pipefail
+exec proot-distro login "$DISTRO" --user "$GUEST_USER" -- bash -lc 'export PATH="\$HOME/.local/bin:\$HOME/.bun/bin:\$PATH"; exec mso "\$@"' bash "\$@"
+EOF
+chmod 0755 "$LAUNCHER"
+
+ok 'MSO is installed for Termux through Ubuntu PRoot.'
+printf '\nVerify:\n'
+printf ' mso --version\n'
+printf ' mso doctor\n\n'
+printf 'Start:\n'
+printf ' mso\n'
+printf ' mso web\n\n'
+printf 'The PRoot environment has no systemd service. The launcher enters the Ubuntu guest automatically.\n'
+printf 'YOLO mode is intentionally not enabled by this installer; use `mso --yolo` only when you explicitly want automatic write/exec approval.\n'