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
docs(termux): add one-pass Android installer
Rahman7bacd2147b47
diff --git a/README.md b/README.mdindex 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.mdindex 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.mdnew file mode 100644index 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.shnew file mode 100755index 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'