fastshell 0.3.7

Lightweight Bash + Python runtime SDK for mobile AI agents
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
# fastshell

[![Crates.io](https://img.shields.io/crates/v/fastshell.svg)](https://crates.io/crates/fastshell)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](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,
})?;

let result = sdk.execute("echo hello | grep h | wc -c");
assert_eq!(result.exit_code, 0);
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
r = subprocess.run("cat file.txt | grep hello | wc -l", shell=True, capture_output=True, text=True)

# 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:

```
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](https://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.

## 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):

| 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)