deepseek-harness-android

DeepSeek Harness Android

English | 中文

app/ is an independent Capacitor Android application for running DeepSeek Harness in a local Ubuntu userspace. Once the runtime is ready, opening the app starts Harness and enters the in-app conversation directly; no external browser is required. Harness service controls, Ubuntu installation and reset, terminals, runtime source details, and optional Shizuku-backed device shell access live under Settings.

Build requirements

• Node.js ^22.19.0 || >=24.0.0, matching the current DeepSeek Harness engine range. Node.js 11.9 cannot build supported Capacitor releases or the current DeepSeek Harness upstream.
• JDK 23.0.1, with JAVA_HOME set explicitly when the system default still points to Java 8.
• Android SDK 35 and a compatible Android NDK.
• The pinned ARM64 PRoot runner and loader used by the release. The current release artifacts come from the Operit2 Android runtime toolchain at commit dc4c3a9405dc7ed3ef69b2ac9a6ace65374d77cf.

The Android WebView does not run Node.js. The installed Ubuntu environment must contain Node.js in the exact supported range ^22.19.0 || >=24.0.0; Node.js 23 is not supported by the current Harness.

Local workflow

pnpm install --frozen-lockfile
pnpm run build
pnpm run android:sync

The 0.1.8 CI release is a self-contained ARM64 APK. The workflow builds the mobile Harness conversation frontend, injects it into an Ubuntu 24.04 ARM64 image containing Node.js 24.19.0 and @deepseek-ai/dsh 0.1.0-rc.6, then embeds the verified rootfs.bundle and runtime-manifest.json in the matching APK. The same runtime files are also published as separate Release assets for inspection and explicitly configured remote installation. Installing the official APK therefore works offline and does not require entering a manifest URL or digest.

The bundled manifest pins the rootfs byte length, architecture, compression, and SHA-256. Embedded installation verifies those values before extraction. When a remote source is explicitly configured, its manifest digest and HTTPS destination are validated as well; archives use an app-private rootfs-<sha256>.part file so interrupted transfers can resume across app or process restarts. A resumed response must be HTTP 206 with the exact expected Content-Range; HTTP 200 or 416 causes a clean restart from byte zero. Network, TLS, timeout, and incomplete-transfer failures enter an explicit error state while retaining a valid bounded partial file. The UI does not report extraction until acquisition and archive verification have completed.

scripts/build-embedded-runtime.py remains the deterministic image builder used by CI and also supports an explicitly constructed embedded development build. Embedded and remote acquisition share the same size, digest, extraction, and atomic-promotion checks. Do not put API keys, passwords, database credentials, signing passwords, or tokens in .env, Gradle files, source code, manifests, URLs, or logs.

The packaged / route is the mobile conversation UI, with sessions, tasks, files, model and reasoning controls, agent presets, public Harness settings, and plugin lifecycle management. The former desktop landing page is not packaged as another entry point. Third-party Cordis plugin pages can be opened from Settings through an on-demand compatibility workbench whose assets are not loaded during normal conversation use.

The native runner files are generated or imported separately and never committed. A release APK packages both lib/arm64-v8a/libdsh_proot.so and lib/arm64-v8a/libdsh_proot_loader.so; both are required. The existing prepare:runner flow remains available for a separately pinned runner source, but it does not replace the provenance and license review for the exact two binaries shipped in an APK.

The runtime manifest fields, CI pinning flow, and security boundaries are documented in docs/ARCHITECTURE.md. See docs/RELEASE_CHECKLIST.md before distributing an APK or runtime asset.

Security checkpoints

• Native bridge inputs have explicit type, length, format, and state validation.
• The app has no user-facing login or Android device-credential gate. The conversation opens directly, while management operations remain in the app's Settings surface. This does not weaken the separate loopback transport credential described below.
• Embedded and downloaded artifacts require exact digests and byte limits; downloads additionally require HTTPS, resumable digest-named staging files, strict Range-response validation, and atomic promotion.
• Archive extraction prevents traversal and does not create device nodes. The exact compressed stream consumed by the extractor is counted and hashed again before promotion, independently enforcing the manifest's compressed size and SHA-256 during decompression.
• Before launching Ubuntu, the app probes the packaged PRoot runner and its seccomp compatibility, then requires individually validated bind mounts for the generated resolver file, /dev, and /proc. Startup fails closed if a required source, guest target, or compatibility probe is unavailable.
• Harness binds only to Android loopback; no business service is exposed on 0.0.0.0.
• Every Harness start generates a non-persistent 256-bit credential. A rootfs preload authenticates both HTTP and WebSocket upgrades before upstream handlers run, and the non-exported internal WebView answers the Basic-auth challenge transparently. An open TCP port alone is not considered ready: two loopback probes separated by a stability interval must return HTTP 401 with the exact expected Basic realm and UTF-8 challenge. The credential is never placed in the URL or audit log.
• Shizuku access requires the declared ShizukuProvider, a visible permission grant, an explicit successful UserService connection, and a user-opened terminal session. Settings exposes a Connect Shizuku action whenever permission exists but the service is disconnected. Binder or UserService loss clears active sessions, and connected is true only while a live authorized UserService binder is available.
• Reset is confined to the app-private runtime root and does not follow symbolic links.
• Owner-only audit files rotate daily and retain at least 90 days of fixed event/result codes.
• No credential, URL, command, session identifier, terminal content, or sensitive user data is written to application audit files.

Licensing

The original application source is MIT licensed. That does not replace or weaken the licenses of packaged runtime components. Direct dependency and runtime redistribution obligations are summarized in THIRD_PARTY_NOTICES.md. In particular, the PRoot runner is GPL-2.0-or-later and the referenced Operit2 source/build material is AGPL-3.0. A distributor must provide the applicable license texts, complete corresponding source for the exact shipped artifacts (including modifications and the scripts needed to build them), and clear source-acquisition instructions for as long as the applicable licenses require. The current provenance record identifies a source revision and binary digests; it does not claim a bit-for-bit reproducible rebuild.