fastshell
A lightweight, cross-platform shell runtime SDK for mobile AI agents — providing 180+ Linux-compatible commands, pipelines, glob expansion, Python execution, and built-in SQLite.
Why
Mobile platforms lack a native Bash environment. AI coding agents rely on shell commands and Python but cannot run on mobile without a compatible runtime. fastshell fills this gap with a self-contained, embeddable SDK.
Features
- 180+ built-in commands —
ls,grep,sed,awk,jq,curl,git,tar,sha256sum... - Built-in SQLite —
sqlite3 db.sqlite "SELECT ...", zero system dependency (bundled via rusqlite) - Device integration —
camera,clipboard,contacts,location,notify,open,say,screencapture... via plugin trait - Pipeline support — True concurrent execution, each stage runs in its own thread with streaming channels
- Glob expansion —
ls *.rs,cat src/**/*.rs - Regex — Full regex in
grepandsed s/// - Python engine — Embedded RustPython (MIT, pure Rust, feature
python-rustpython):ast/unittest/frozen stdlib, no dlopen/JNI/C-TLS crash surface. Desktop prefers systempython3. - JavaScript execution —
node/jsruns JavaScript in the host app's WebView engine (Android V8 / iOS JavaScriptCore),renderrenders HTML to a screenshot,jscheck/node -cstatic-check JS/TS syntax via oxc (pure Rust, optional featurejs-oxc). - Virtual filesystem — Sandbox isolation, path escape prevention
- Thread-safe SDK —
Arc<Mutex<Runtime>>, timeout enforcement - Cross-platform — Single codebase compiles to Android, iOS, macOS, Linux
In The Wild
aacode — a mobile AI coding assistant, running on fastshell:
- The entire shell sandbox, 180+ commands, embedded Python, device bridge, and native C-ABI agent interface are powered by fastshell.
- Available via APK direct download. Google Play and other app stores are still in the listing process.
Installation
[]
= "0.3.3"
Quick Start
Rust
use ;
let mut sdk = new;
sdk.init?;
let result = sdk.execute;
assert_eq!;
println!;
// Direct file API
sdk.write_file?;
assert_eq!;
// Python
let r = sdk.execute_python;
// 5050
Embedded RustPython (feature python-rustpython)
On mobile, fastshell embeds RustPython 0.5.0 — a Python 3
interpreter written in pure Rust. It compiles straight into the static library:
no libpython.so, no dlopen, no on-disk stdlib extraction (the CPython pure-Python
standard library is frozen into the binary via freeze-stdlib).
The previous Chaquopy CPython integration was removed: in-process embedded CPython crashed on real devices (pthread/bionic TLS,
unittest/threading). RustPython eliminates that entire crash class by construction.
Supported out of the box: ast syntax checks, unittest, json, re, os,
file I/O in the sandbox cwd, big integers, correct float division semantics.
C extension modules (numpy etc.) are not supported (same as any embedded option).
Licensing note: RustPython's LGPL malachite dependencies are replaced by
clean-room Apache-2.0 shims — see num_bigint/README.md and vendor/README.md.
The full dependency tree is permissive (closed-source apps can link statically).
On desktop, the system python3 is preferred; set FASTSHELL_PYTHON=rustpython
to force the embedded engine (useful for testing the mobile code path).
Python calling Shell
# Run a shell command
=
# Pipelines work
=
# Async shell
= await
, = await
# os.system also works
=
All 180+ built-in commands, pipelines, and globs are available. On desktop, unknown commands fall through to the system shell. On mobile, subprocess fallthrough is disabled by default — all execution stays in-process.
Mobile (FFI)
// Android JNI / iOS C FFI
const char* result = ;
const char* output = ;
;
API
Permission System (Mobile)
fastshell does not make authorization decisions. Instead, it uses a special exit code to delegate to the host app:
1. Script runs "curl http://example.com"
2. fastshell checks: is "network:example.com" granted?
3. If not → returns { exit_code: 100, stderr: "PERMISSION_NEEDED:network:example.com" }
4. Host app detects exit_code=100 → shows native dialog: "Allow network access to example.com?"
5. User taps "Allow" → host calls sdk.set_permission("network:example.com", true) → retries command
Resource types:
| Resource | Triggered by |
|---|---|
network:<host> |
curl, wget, ping, ssh, nslookup |
network:* |
Grant all network access at once |
Flow:
let result = sdk.execute;
if result.exit_code == 100
Device Plugin
fastshell provides 22 device capability commands (camera, clipboard, contacts, location, notify, open...).
These commands do nothing by default — the host app must implement the DevicePlugin trait and register it.
┌──────────────────────────────┐ ┌────────────────────────────┐
│ fastshell SDK │ │ Host App (Kotlin/Swift) │
│ │ │ │
│ shell: "camera" → command │ │ impl DevicePlugin { │
│ checks: plugin registered? │──→ │ fn take_photo(path) { │
│ calls: plugin.take_photo() │ │ // AVCaptureSession │
│ │ │ // or CameraX │
│ returns result to AI agent │←── │ } │
└──────────────────────────────┘ └────────────────────────────┘
Host app integration:
use DevicePlugin;
;
sdk.register_plugin;
Permission model: Same as network — first call returns exit_code=100 with PERMISSION_NEEDED:camera:photo.
Host app shows native permission dialog, calls set_permission, retries.
Command compatibility: Common macOS/Linux names are aliased — pbcopy / pbpaste,
notify-send, xdg-open, screencapture, say, arecord — AI agents use familiar commands without retraining.
Mobile Integration Notes
Single-Process Guarantee
On mobile (allow_subprocess = false), fastshell is 100% single-process — all commands, pipelines,
and Python execution run within the host app's process. No fork(), no child processes. This avoids:
- Android 12+ Phantom Process Killer — kills apps with >32 total processes (all apps combined)
- iOS
fork()prohibition — iOS forbids process forking entirely
Pipeline Concurrency
Pipelines now use true threading — each stage runs in its own thread with mpsc streaming channels:
ls -la | grep foo | wc -l
Thread 1 Thread 2 Thread 3
VFS Root Directory
| Platform | Recommended path |
|---|---|
| Android | /data/data/<pkg>/files/fastshell |
| iOS | <app>/Documents/fastshell (NOT Library/Caches) |
| Desktop | Any writable path |
Network Configuration
| Platform | Requirement |
|---|---|
| iOS | Add NSAllowsArbitraryLoads to Info.plist, or configure per-domain exceptions via NSAppTransportSecurity |
| Android | Add android:usesCleartextTraffic="true" to AndroidManifest.xml |
Without these, HTTP requests from curl/wget will fail silently on mobile.
Keep-Alive (Android)
Host app should implement a Foreground Service with a persistent notification to prevent Android from killing the process in background. See dontkillmyapp.com for vendor-specific instructions.
Subprocess Fallthrough
| Platform | Default | Behavior |
|---|---|---|
| Android / iOS | allow_subprocess = false |
Unknown commands return "command not found (subprocess disabled)" |
| macOS / Linux | allow_subprocess = true |
Unknown commands forwarded to system shell |
Built-in commands (ls, grep, curl, git, etc.) work everywhere regardless of this setting.
Build from Source
Requires Rust stable toolchain.
# 1. Build for your target (optional features: python-rustpython = embedded Python, js-oxc = JS/TS syntax checking)
# Linux x86_64 cross-compile (requires cargo-zigbuild)
# 2. Run tests (~500 fastshell tests; 687 across the workspace with aacode-rs)
Note: Android target requires Android NDK r27c (a .cargo/config.toml with the
NDK linker paths, see this repo's root). macOS, iOS, and Linux targets build without NDK.
Linking the library into your project:
# macOS / Linux
target/aarch64-apple-darwin/release/libfastshell.dylib
# iOS
target/aarch64-apple-ios/release/libfastshell.a
# Android
target/aarch64-linux-android/release/libfastshell.so
Build artifacts per platform (reference; sizes measured with the full
git,python-rustpython feature set — leaner without them):
| Platform | Output File | Format | Approx Size |
|---|---|---|---|
| macOS Apple Silicon | libfastshell.dylib |
dynamic library | ~14 MB |
| iOS arm64 | libfastshell.a |
static library (link-time GC applies) | ~90 MB .a |
| Android arm64 | libaacode_rs.a → libfastshell_jni.so |
staticlib + NDK CMake link (recommended, see fastshell_c/) |
~218 MB .a → ~48 MB .so |
| Linux x86_64 | libfastshell.so |
shared library (.so) | ~14 MB |
For mobile apps the staticlib + host-side C/CMake link path is recommended
(fastshell_c/ for Android): dead-code elimination (--gc-sections) shrinks the
final .so dramatically, and one archive carries fastshell + the aacode-rs agent
- RustPython + git2.
Commands
File Operations
ls cd pwd mkdir rm cp mv cat find tree touch chmod file stat du basename dirname realpath
Text Processing
grep (egrep/fgrep) rg sed awk sort uniq wc head tail cut tr diff tee xargs column paste rev comm xxd printf seq shuf
Network
curl wget ping ssh
Compression
gzip gunzip tar zip unzip
Crypto / Encoding
base64 sha256sum sha512sum md5sum
JSON
jq
System
ps kill pgrep pkill env printenv date sleep which uname hostname whoami id df
Control Flow
true false test expr timeout
Database
sqlite3 (built-in, bundled — no system dependency)
JavaScript
node js render jscheck (node -c syntax-checks without executing)
Device (requires plugin)
camera screencapture photolib record arecord play say speech contacts location clipboard pbpaste pbcopy sensor notify notify-send share open xdg-open auth battery vibrate screen device
Version Control
git
Architecture
fastshell/
├── src/
│ ├── vfs/ # Layer 1 — Virtual sandbox filesystem
│ ├── shell/ # Layer 1 — 180+ built-in shell commands (pure Rust)
│ ├── python/ # Layer 1 — Python engine (subprocess / CPython)
│ ├── js/ # Layer 1 — JS/TS static syntax checking (oxc, feature js-oxc)
│ ├── bridge/ # Layer 2 — Script execution, I/O, pipeline, glob
│ └── sdk/ # Layer 3 — Public API + platform FFI (JNI / C)
├── docs/ # Documentation (API, commands, integration, plugin, security, etc.)
├── tests/ # Integration tests
└── vendor/ # Embedded CPython 3.12 libraries
Design Principles
- Lightweight — Pure Rust implementation, no BusyBox dependency, no GPL licensing issues
- Compatible — Commands behave identically to Linux; AI agents need no retraining
- Secure — VFS sandbox isolation, path escape prevention, command timeout control, single-process on mobile
- Cross-platform — Unified API, same Rust core across Android / iOS / macOS / Linux
- Permission-driven — Network access requires host app authorization; fastshell never decides on its own
License
Apache 2.0 © xiefujin (490021684@qq.com)