Light-Heart-Labs · gabsprogrammer · Apr 15, 2026 · Apr 15, 2026
diff --git a/README.md b/README.md
@@ -31,6 +31,8 @@ If AI is becoming critical infrastructure, it shouldn’t be rented. Self-hostin
 > | **Linux** (NVIDIA + AMD) | **Supported** — install and run today |
 > | **Windows** (NVIDIA + AMD) | **Supported** — install and run today |
 > | **macOS** (Apple Silicon) | **Supported** — install and run today |
+> | **Android** (Termux) | **Preview** — shell-only local chat bootstrap |
+> | **iOS** (a-Shell) | **Preview** — local shell chat with Qwen3-0.6B |
 >
 > **Tested Linux distros:** Ubuntu 24.04/22.04, Debian 12, Fedora 41+, Arch Linux, CachyOS, openSUSE Tumbleweed. Other distros using apt, dnf, pacman, or zypper should also work — [open an issue](https://github.com/Light-Heart-Labs/DreamServer/issues) if yours doesn't.
 >
@@ -127,6 +129,91 @@ See the [macOS Quickstart](dream-server/docs/MACOS-QUICKSTART.md) for details.
 
 </details>
 
+<details>
+<summary><b>Android (Termux preview)</b></summary>
+
+Install **Termux** on Android first.
+
+- Recommended: install from [F-Droid](https://f-droid.org/packages/com.termux/).
+- If you already have an old Google Play build, replace it before continuing. The official Termux project treats Play Store builds as outdated/deprecated and recommends F-Droid or current GitHub/F-Droid distribution instead.
+
+```bash
+termux-change-repo
+apt update && apt full-upgrade -y
+pkg install -y git
+termux-setup-storage
+git clone https://github.com/Light-Heart-Labs/DreamServer.git
+cd DreamServer
+./install.sh
+./dream-mobile.sh status
+./dream-mobile.sh local
+./dream-mobile.sh chat
+```
+
+This Android path is a **beta mobile preview**. It detects Termux, builds a native local `llama.cpp` runtime, downloads `Qwen3-0.6B`, and gives you both shell chat and a lightweight localhost UI on Android. It can also export generated files into shared storage when `termux-setup-storage` has been granted.
+
+Current Android preview scope:
+
+- local chat in the shell with `./dream-mobile.sh chat`
+- localhost mobile UI with `./dream-mobile.sh local`
+- model switching between supported mobile GGUF presets
+- local file export into Android Downloads when shared storage is enabled
+
+Current Android preview limits:
+
+- still **beta**
+- not the full desktop Dream Server stack
+- no Docker services, dashboard parity, workflows, voice, or full agent stack on Android yet
+
+See the [Mobile Shell Quickstart](dream-server/docs/MOBILE-SHELL-QUICKSTART.md) for details.
+
+</details>
+
+<details>
+<summary><b>iOS (a-Shell preview)</b></summary>
+
+Before running the commands below, install [a-Shell on the App Store](https://apps.apple.com/us/app/a-shell/id1473805438) on your iPhone.
+
+```sh
+lg2 clone https://github.com/Light-Heart-Labs/DreamServer.git
+cd DreamServer
+sh ./install.sh
+sh ./dream-mobile.sh status
+sh ./dream-mobile.sh chat
+```
+
+This preview path is a **lite beta** for iPhone shell use. It is intentionally narrow: install Dream Server inside `a-Shell`, download `Qwen3-0.6B-Q4_0.gguf`, and chat with the model locally in the shell.
+
+What `sh ./install.sh` does on iPhone:
+
+1. Detects `a-Shell`.
+2. Downloads the mobile `Qwen3-0.6B-Q4_0.gguf` model into `data/models/mobile/`.
+3. Points the iOS preview at the prebuilt `llama-cli.wasm` runtime under `dream-server/mobile-runtime/ios-ashell/bin/`.
+4. Leaves you with a small shell surface: `install`, `status`, and `chat`.
+
+What `sh ./dream-mobile.sh status` shows:
+
+- whether the model download is present
+- whether the wasm runtime path is configured
+- the current chat defaults used on iPhone
+
+What `sh ./dream-mobile.sh chat` does:
+
+- launches the prebuilt `llama-cli.wasm` through `a-Shell`'s `wasm` runner
+- loads the downloaded GGUF model
+- starts the fast local interactive chat loop on the iPhone
+
+Current scope:
+
+- local chat in the shell
+- lite beta path only, not feature-parity with desktop Dream Server
+- no full Dream Server Docker stack on iOS yet
+- no dashboard, workflows, agents, or WebUI in iPhone shell mode
+
+See the [iOS a-Shell guide](dream-server/docs/IOS-ASHELL-SHORTCUTS.md) for the focused iPhone flow.
+
+</details>
+
 ---
 
 ## What's In The Box

diff --git a/dream-mobile.sh b/dream-mobile.sh
@@ -0,0 +1,38 @@
+#!/bin/sh
+
+# Root wrapper for Dream Server mobile preview.
+# On iOS / a-Shell, jump straight to the dedicated CLI to avoid extra wrapper
+# layers and shell-specific quirks.
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+CONFIG_FILE="$SCRIPT_DIR/dream-server/.dream-mobile.env"
+IOS_CONTAINER_PATTERN='^(/private)?/var/mobile/Containers/Data/Application/'
+IOS_CLI="$SCRIPT_DIR/dream-server/installers/mobile/ios-ashell-cli.sh"
+INNER="$SCRIPT_DIR/dream-server/dream-mobile.sh"
+
+if [ -f "$CONFIG_FILE" ] && grep -q 'DREAM_MOBILE_PLATFORM="ios-ashell"' "$CONFIG_FILE" 2>/dev/null; then
+    exec sh "$IOS_CLI" "$@"
+fi
+
+if [ "${TERM_PROGRAM:-}" = "a-Shell" ] || [ "${TERM_PROGRAM:-}" = "a-Shell mini" ] || [ -n "${ASHELL:-}" ]; then
+    exec sh "$IOS_CLI" "$@"
+fi
+
+if printf '%s\n' "$SCRIPT_DIR" | grep -Eq "$IOS_CONTAINER_PATTERN"; then
+    exec sh "$IOS_CLI" "$@"
+fi
+
+if printf '%s\n' "${HOME:-}" | grep -Eq "$IOS_CONTAINER_PATTERN"; then
+    exec sh "$IOS_CLI" "$@"
+fi
+
+if [ "$(uname -s 2>/dev/null || echo unknown)" = "Darwin" ] && [ -d /private/var/mobile/Containers/Data/Application ]; then
+    exec sh "$IOS_CLI" "$@"
+fi
+
+if [ ! -f "$INNER" ]; then
+    echo "Dream Server mobile wrapper not found: $INNER" >&2
+    exit 1
+fi
+
+exec sh "$INNER" "$@"
diff --git a/dream-server/.gitignore b/dream-server/.gitignore
@@ -7,6 +7,7 @@
 .profiles
 .target-model
 .target-quantization
+.dream-mobile.env
 
 # Secret files (security)
 *.key

diff --git a/dream-server/README.md b/dream-server/README.md
@@ -17,8 +17,10 @@
 > | **Linux** (NVIDIA + AMD) | **Supported** — install and run today |
 > | **macOS** (Apple Silicon) | **Supported** — install and run today |
 > | **Windows** (NVIDIA + AMD) | **Supported** — install and run today |
+> | **Android** (Termux) | **Preview** — shell-only local chat bootstrap |
+> | **iOS** (a-Shell) | **Preview** — lite beta local shell chat |
 >
-> All three platforms are fully supported with one-command installers. See [`docs/SUPPORT-MATRIX.md`](docs/SUPPORT-MATRIX.md) for detailed tier status.
+> Linux, Windows, and macOS are the fully supported desktop paths. Android / Termux and iOS / a-Shell are preview paths. See [`docs/SUPPORT-MATRIX.md`](docs/SUPPORT-MATRIX.md) for detailed status.
 
 See [`docs/SUPPORT-MATRIX.md`](docs/SUPPORT-MATRIX.md) for current support tiers and platform status.
 Launch-claim guardrails: [`docs/PLATFORM-TRUTH-TABLE.md`](docs/PLATFORM-TRUTH-TABLE.md)
@@ -87,6 +89,61 @@ llama-server runs natively with Metal GPU acceleration; all other services run i
 
 See [`docs/WINDOWS-QUICKSTART.md`](docs/WINDOWS-QUICKSTART.md) for details.
 
+### Android (Termux preview)
+
+Install **Termux** on Android first.
+
+- Recommended: install from [F-Droid](https://f-droid.org/packages/com.termux/).
+- If you already have an old Google Play build, replace it before continuing.
+
+```bash
+termux-change-repo
+apt update && apt full-upgrade -y
+pkg install -y git
+termux-setup-storage
+git clone https://github.com/Light-Heart-Labs/DreamServer.git
+cd DreamServer
+./install.sh
+./dream-mobile.sh status
+./dream-mobile.sh local
+./dream-mobile.sh chat
+```
+
+On Termux, `./install.sh` switches into a **beta mobile preview** built for Android: it installs build dependencies, compiles the local `llama.cpp` chat runtime, downloads `Qwen3-0.6B`, and leaves you with both `./dream-mobile.sh chat` and `./dream-mobile.sh local`. If shared Android storage has been granted through `termux-setup-storage`, the preview can also export generated files into Downloads.
+
+Android preview scope:
+
+- shell chat
+- localhost mobile UI
+- mobile GGUF model switching
+- export into Downloads when Android shared storage is enabled
+
+Android preview limits:
+
+- still beta
+- not full desktop feature parity
+- no Docker stack, workflows, voice, or desktop dashboard parity yet
+
+See [`docs/MOBILE-SHELL-QUICKSTART.md`](docs/MOBILE-SHELL-QUICKSTART.md) for the current scope and limitations.
+
+### iOS (a-Shell preview)
+
+Before running the commands below, install [a-Shell on the App Store](https://apps.apple.com/us/app/a-shell/id1473805438) on your iPhone.
+
+```bash
+lg2 clone https://github.com/Light-Heart-Labs/DreamServer.git
+cd DreamServer
+sh ./install.sh
+sh ./dream-mobile.sh status
+sh ./dream-mobile.sh chat
+```
+
+On iOS, the preview is now a **lite beta** focused on local shell chat only. `sh ./install.sh` detects `a-Shell`, downloads `Qwen3-0.6B-Q4_0.gguf`, points the preview at the bundled `llama-cli.wasm` runtime, and leaves you with a small iPhone shell surface: `install`, `status`, and `chat`.
+
+This iPhone path does **not** try to mirror the full desktop Dream Server stack yet. It is for local shell chat on-device, not for dashboard, Docker services, workflows, or agent parity with Windows, macOS, and Linux.
+
+See [`docs/IOS-ASHELL-SHORTCUTS.md`](docs/IOS-ASHELL-SHORTCUTS.md) for the current iPhone flow.
+
 ---
 
 ## What's Included

diff --git a/dream-server/docs/IOS-ASHELL-SHORTCUTS.md b/dream-server/docs/IOS-ASHELL-SHORTCUTS.md
@@ -0,0 +1,62 @@
+# iOS a-Shell Preview
+
+Last updated: 2026-04-13
+
+## Goal
+
+Keep the iOS shell path intentionally small and stable:
+
+- install the local preview on `a-Shell`
+- load the local `Qwen3-0.6B` runtime
+- talk to the model with a fast interactive chat
+
+This is a **lite beta** path for iPhone shell use. It is not the same experience as the full Dream Server desktop install on Windows, macOS, or Linux.
+
+## Install on iPhone
+
+First, install [a-Shell on the App Store](https://apps.apple.com/us/app/a-shell/id1473805438) on your iPhone.
+
+Inside `a-Shell`:
+
+```sh
+lg2 clone https://github.com/Light-Heart-Labs/DreamServer.git
+cd DreamServer
+sh ./install.sh
+sh ./dream-mobile.sh status
+sh ./dream-mobile.sh chat
+```
+
+By default, `sh ./install.sh` downloads `Qwen3-0.6B-Q4_0.gguf` into `data/models/mobile/`.
+
+If you want to skip the model download on a specific run:
+
+```sh
+sh ./install.sh --no-model-download
+```
+
+## Available commands
+
+The iOS preview now exposes only these shell commands:
+
+- `install`
+- `status`
+- `chat`
+
+This keeps the `a-Shell` path focused on the part that is currently working well: local chat.
+
+Out of scope for this lite beta:
+
+- full Docker stack
+- Dashboard / WebUI
+- workflows, agents, and voice services
+- desktop feature parity
+
+## Runtime note
+
+The iOS preview uses:
+
+- the downloaded GGUF model file
+- the linked `llama-cli.wasm` runtime under `mobile-runtime/ios-ashell/bin/`
+- the `wasm` runner exposed by `a-Shell`
+
+That is how Dream Server can chat locally on iPhone without needing a separate native app.
diff --git a/dream-server/docs/IOS-ASHELL-WASM-RUNTIME.md b/dream-server/docs/IOS-ASHELL-WASM-RUNTIME.md
@@ -0,0 +1,84 @@
+# iOS a-Shell WASM Runtime
+
+Last updated: 2026-04-11
+
+## Goal
+
+Use the same `dream-mobile.sh` CLI on iOS with a real local `Qwen3-0.6B` backend by placing a `llama-cli.wasm` runtime at:
+
+```text
+mobile-runtime/ios-ashell/bin/llama-cli.wasm
+```
+
+## What exists now
+
+The repo now includes a working host-side build chain:
+
+```sh
+bash dream-server/installers/mobile/build-ios-ashell-wasm-sdk.sh
+bash dream-server/installers/mobile/build-ios-ashell-wasm-runtime.sh
+```
+
+That build chain:
+
+- bootstraps a custom `wasi-sdk` sysroot with `WASI_SDK_EXCEPTIONS=ON`
+- clones a pinned `llama.cpp` checkout
+- generates a tiny prompt-only WASI runner
+- drives the official `wasi-sdk` Docker image plus the custom exported sysroot
+- now injects an explicit `__cpp_exception` wasm tag object into the runner link
+- now stubs `dlopen` / `dlsym` / `dlclose` for the WASI path
+- copies the output into the exact path that the iOS preview already checks
+
+## Published-image blocker
+
+If you try to skip the custom sysroot helper and use only a published `wasi-sdk` image, the link still fails for the `a-Shell` path because the required C++ exception runtime support is incomplete without an exceptions-enabled sysroot.
+
+The first blocker we hit on published images was:
+
+- `__cxa_allocate_exception`
+- `__cxa_throw`
+- `__wasm_lpad_context`
+- `_Unwind_CallPersonality`
+
+The successful host build now pairs the runner with:
+
+- `wasm32-wasip1`
+- `-fwasm-exceptions`
+- `-lunwind`
+- an explicit `__cpp_exception` tag object
+- a custom sysroot built with `WASI_SDK_EXCEPTIONS=ON`
+- WASI-safe dynamic loading stubs for the static CPU backend path
+
+This is why the iPhone can already:
+
+- download `Qwen3-0.6B-Q4_0.gguf`
+- report `Downloaded:true`
+- keep a stable `prompt` / `chat` shell contract
+
+## What success looks like
+
+Once `mobile-runtime/ios-ashell/bin/llama-cli.wasm` is present in the repo state that the iPhone pulls, the iOS flow does not need a new interface. The existing commands can switch over:
+
+```sh
+sh ./dream-mobile.sh status
+sh ./dream-mobile.sh prompt "oi"
+sh ./dream-mobile.sh chat
+```
+
+And `status` should move from:
+
+```text
+Engine:    rules
+Wasm ready:false
+```
+
+to:
+
+```text
+Engine:    wasm
+Wasm ready:true
+```
+
+## Practical note
+
+These builders are meant to run on a desktop host with Docker, not inside `a-Shell`.