# fastshell
[](https://crates.io/crates/fastshell)
[](LICENSE)
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 `grep` and `sed s///`
- **Python engine** — Embedded [RustPython](https://github.com/RustPython/RustPython) (MIT, pure Rust, feature `python-rustpython`): `ast`/`unittest`/frozen stdlib, no dlopen/JNI/C-TLS crash surface. Desktop prefers system `python3`.
- **JavaScript execution** — `node`/`js` runs JavaScript in the host app's WebView engine (Android V8 / iOS JavaScriptCore), `render` renders HTML to a screenshot, `jscheck`/`node -c` static-check JS/TS syntax via [oxc](https://github.com/oxc-project/oxc) (pure Rust, optional feature `js-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**](https://github.com/kandada/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**](https://github.com/kandada/aacode/raw/main/mobile_app/aacode-v1.7.24-arm64.apk). Google Play and other app stores are still in the listing process.
## Installation
```toml
[dependencies]
fastshell = "0.3.4"
```
## Quick Start
### Rust
```rust
use fastshell::{Fastshell, Config};
let mut sdk = Fastshell::new();
sdk.init(Config {
sandbox_path: "/tmp/my-sandbox".into(),
command_timeout_ms: 30_000,
python_enabled: true,
allow_subprocess: true,
network_ask_permission: false,
})?;
println!("{}", result.stdout);
// Direct file API
sdk.write_file("hello.txt", "Hello, world!")?;
assert_eq!(sdk.read_file("hello.txt")?, "Hello, world!");
// Python
let r = sdk.execute_python("print(sum(range(1, 101)))");
// 5050
```
### Embedded RustPython (feature `python-rustpython`)
On mobile, fastshell embeds **[RustPython](https://github.com/RustPython/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
```python
import subprocess
# Run a shell command
r = subprocess.run("ls -la", shell=True, capture_output=True, text=True)
print(r.stdout)
# Pipelines work
# Async shell
import asyncio
async def main():
proc = await asyncio.create_subprocess_shell("curl -s https://api.example.com", stdout=asyncio.subprocess.PIPE)
data, _ = await proc.communicate()
print(data.decode())
asyncio.run(main())
# os.system also works
import os
ret = os.system("mkdir -p /tmp/work")
```
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)
```c
// Android JNI / iOS C FFI
const char* result = fastshell_init("/data/sandbox");
const char* output = fastshell_execute("ls -la");
fastshell_free_string(output);
```
## API
```rust
pub struct Config {
pub sandbox_path: String, // sandbox root path (required)
pub python_enabled: bool, // enable Python engine
pub command_timeout_ms: u64, // timeout in ms, 0 = no limit
pub allow_subprocess: bool, // allow fallthrough to system shell
// default: true on desktop, false on mobile
pub network_ask_permission: bool, // prompt user before network access
// default: true on mobile, false on desktop
}
impl Fastshell {
pub fn new() -> Self;
pub fn init(&mut self, config: Config) -> Result<(), String>;
pub fn execute(&self, command: &str) -> CommandResult;
pub fn execute_python(&self, code: &str) -> CommandResult;
pub fn execute_python_script(&self, script_path: &str) -> CommandResult;
pub fn get_cwd(&self) -> String;
pub fn read_file(&self, path: &str) -> Result<String, String>;
pub fn write_file(&self, path: &str, content: &str) -> Result<(), String>;
pub fn list_dir(&self, path: &str) -> Result<Vec<FileEntry>, String>;
pub fn exists(&self, path: &str) -> bool;
pub fn is_dir(&self, path: &str) -> bool;
pub fn set_env(&mut self, key: &str, value: &str);
pub fn get_env(&self, key: &str) -> Option<String>;
pub fn get_info(&self) -> SdkInfo;
pub fn config(&self) -> &Config;
pub fn vfs_root(&self) -> String;
pub fn shutdown(&mut self);
// Permission management (mobile)
pub fn set_permission(&self, resource: &str, allowed: bool);
pub fn check_permission(&self, resource: &str) -> Option<bool>;
pub fn clear_permissions(&self);
// Cancel a running command (for timeout/interrupt)
pub fn cancel_execution(&self);
// Device plugin registration
pub fn register_plugin(&self, plugin: Box<dyn DevicePlugin>);
}
pub struct CommandResult {
pub stdout: String,
pub stderr: String,
pub exit_code: i32,
// exit_code == 100 → permission needed (see below)
}
```
## 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:**
```rust
let result = sdk.execute("curl http://example.com");
if result.exit_code == 100 {
// parse stderr for resource, show native dialog
sdk.set_permission("network:example.com", true);
let result = sdk.execute("curl http://example.com"); // retry
}
```
## 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:**
```rust
use fastshell::sdk::plugin::DevicePlugin;
struct MyPlugin;
impl DevicePlugin for MyPlugin {
fn take_photo(&self, output_path: &str) -> Result<(), String> {
// invoke native camera, save to sandbox
}
fn get_clipboard(&self) -> Result<String, String> { ... }
fn get_location(&self) -> Result<Location, String> { ... }
// ... implement the methods you need
}
sdk.register_plugin(Box::new(MyPlugin));
```
**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:
```
```
### VFS Root Directory
| Android | `/data/data/<pkg>/files/fastshell` |
| iOS | `<app>/Documents/fastshell` (NOT `Library/Caches`) |
| Desktop | Any writable path |
### Network Configuration
| 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](https://dontkillmyapp.com)
for vendor-specific instructions.
### Subprocess Fallthrough
| 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.
## LGPL-free builds (malachite shims) — read this if you depend on fastshell from crates.io
RustPython depends on the **LGPL-3.0-only** `malachite-*` crates. This repository
replaces them with **clean-room Apache-2.0 shims** via a workspace-local
`[patch.crates-io]`:
```toml
[patch.crates-io]
malachite-base = { path = "fastshell/num_bigint/malachite-base" }
malachite-bigint = { path = "fastshell/num_bigint/malachite-bigint" }
malachite-q = { path = "fastshell/num_bigint/malachite-q" }
```
**This patch is local only — it is not published and is not inherited by
dependencies.** Consequences:
- Building **inside this repository** (or as the mobile app does): you get the
Apache shims — **LGPL-free**.
- `cargo add fastshell` from **crates.io**: cargo cannot see the patch, so the
real upstream **LGPL** `malachite` is used.
To stay LGPL-free while using the crates.io crate, add the same
`[patch.crates-io]` (pointing at the shim sources in this repo) to **your own
workspace root**, or depend on `fastshell` via path/git from this repository.
Two vendored, manifest-only forks (`fastshell/vendor/pymath`,
`fastshell/vendor/rustpython-stdlib`) pin `malachite-bigint` to a single `0.9.x`
so downstream builds don't break when upstream publishes a new `0.x`. See
[`docs/lgpl-malachite.md`](docs/lgpl-malachite.md) for the full details.
## Build from Source
Requires Rust stable toolchain.
```bash
# 1. Build for your target (optional features: python-rustpython = embedded Python, js-oxc = JS/TS syntax checking)
cargo build --release --target aarch64-apple-darwin # macOS ARM64
cargo build --release --target x86_64-apple-darwin # macOS Intel
cargo build --release --target aarch64-apple-ios # iOS (macOS host)
cargo build --release --target aarch64-linux-android # Android (needs NDK; static libffi is bundled — see vendor/README.md)
# Linux x86_64 cross-compile (requires cargo-zigbuild)
pip3 install cargo-zigbuild
cargo zigbuild --release --target x86_64-unknown-linux-gnu
# 2. Run tests (~500 fastshell tests; 687 across the workspace with aacode-rs)
cargo test --features git,python-rustpython
```
**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):
| 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)