Installation and updates
| Environment | Installation | Requirements |
|---|---|---|
| Computer connected to Android | Release ZIP and ADB launcher | Host adb, Android API 26+, ARM64/ARMv7/x86_64 |
| Android controller connected to a target device | nl2sh-helper APK | Controller Android API 26+; target ARM64/ARMv7/x86_64 with TCP ADB or Android 11+ Wireless debugging |
| Computer bootstrap | Bash / PowerShell / CMD installer | Host network access and adb |
| Android Termux | TUR, signed APT, or local deb | Termux package manager |
| Developer | Cross-compile source | Stable Rust, Node.js 22+, Android NDK |
Release installation
Download nl2sh-android.zip and SHA256SUMS from GitHub Releases, compare the ZIP SHA-256, and extract the entire archive. It includes bin/arm64-v8a/nl2sh, bin/armeabi-v7a/nl2sh, and bin/x86_64/nl2sh; launchers select the ABI automatically. Desktop Linux binaries cannot replace Android builds.
sha256sum nl2sh-android.zip
cd nl2sh-android
./android-run-linux.sh
On Windows compare Get-FileHash ./nl2sh-android.zip -Algorithm SHA256, extract, and run android-run-windows.bat. Prepare the device using ADB / native Android.
nl2sh-helper
If another Android device is your controller, download a signed APK from nl2sh-helper Releases, which requires repository access, and install it on the controller. In the helper, choose TCP ADB if it is already enabled on the target, or use a pairing code or QR code for a target running Android 11+ Wireless debugging. Accept the ADB authorization prompt on the target for a first TCP connection. For pairing codes, enter the temporary address, port, and code shown on the target.
Connecting reuses a healthy installed runtime without checking releases or restarting it. First installation and explicit updates select ARM64, ARMv7 or x86_64 from an authenticated release manifest, verify the binary size/digest/signature, and deploy to /data/local/tmp/nl2sh. The native service reports its actual Web port. Explicit update, restart and stop actions are separate. Failed updates restore the previous verified binary and ownership. Open the returned browser address and configure model credentials in Web Quick Start. The controller must reach the actual port; Web has no login and listens on all IPv4 interfaces, so use a trusted network. See the helper guide.
On Android 11+, the helper also offers Local mode: pair through this device’s Wireless debugging, install/run nl2sh as shell, and open 127.0.0.1 at the actual Web port. If online installation or update fails, it can use a complete cached release only after revalidating signatures, size, digest, and ABI. A cache does not replace an equal or newer installed version, and the UI reports that the latest version is unconfirmed. Bridge installation still requires network access.
Bootstrap installation
Pass the API key through your private terminal environment and never commit it.
export NL2SH_API_KEY='your-api-key'
curl -fsSL https://raw.githubusercontent.com/nl2sh/nl2sh/master/install-android.sh \
| bash -s -- --provider deepseek --model deepseek-flash
$env:NL2SH_API_KEY = 'your-api-key'
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/nl2sh/nl2sh/master/install-android.ps1))) `
-Provider deepseek -Model deepseek-flash
set "NL2SH_API_KEY=your-api-key"
curl.exe -fsSL https://raw.githubusercontent.com/nl2sh/nl2sh/master/install-android.bat -o "%TEMP%\install-nl2sh.bat"
call "%TEMP%\install-nl2sh.bat" --provider deepseek --model deepseek-flash
Installers download the ZIP and checksums from one Release. The default directory is nl2sh-android under the current directory. Reruns reuse a complete installation; explicit provider/model/endpoint arguments update those fields only. Incomplete directories are refused. Linux pipe installation reconnects the controlling terminal for launch; without one, run the launcher interactively later.
Providers include openrouter, openai, deepseek, moonshot/kimi, siliconflow, ollama, and custom. Custom services require --endpoint / -Endpoint.
Gitee mirror
Explicitly select Gitee: replace the script URL with https://gitee.com/nl2sh/nl2sh/raw/master/install-android.sh (or .ps1 / .bat) and pass --repository https://gitee.com/nl2sh/nl2sh (-Repository in PowerShell). Release assets must also be mirrored; source alone is insufficient. There is no implicit fallback after GitHub fails.
Updates
Direct Android builds support nl2sh update or TUI /update: download the ABI-specific executable, verify its signed compatibility manifest, exact size, SHA-256, detached GPG signature and ELF ABI, and atomically replace it. Restart to use the new program. Launchers deploy their local package according to its digest, so download the updated host package too; launching an old package can overwrite the device update. Termux package-manager builds use pkg upgrade nl2sh.
Continue with daily startup, Termux, or source builds.
x86_64 devices and emulators require a new release archive containing that ABI. For an existing two-ABI installation, back up configuration and extract the new archive into a new directory. Launchers prefer native x86_64 without relying on ARM translation. Self-update uses nl2sh-android-x86_64 and its manifest/signature; Termux packages continue to use package-manager updates.
When reusing an older directory without bin/x86_64/nl2sh, installers issue a warning while allowing existing ARM installations to continue. For x86_64, back up config.toml and select a new directory with Bash/CMD --install-dir or PowerShell -InstallDir, using a release that contains x86_64. Script help lists all three ABIs and the native x86_64 preference.
/api/info reports installation update ownership and whether the embedded runtime policy is verified, absent in an unsigned source build, or invalid. Helper-managed installations use Helper for updates; a damaged ownership marker blocks self-update until inspected.