End-to-end demos and reference bindings for the rootshell WASM runtime:
the on-device sandbox that lets you compile CLI tools in any language that
targets WASI Preview 1 (C/C++ via clang/wasi-sdk, Rust, Go, TinyGo, Zig,
AssemblyScript, and so on) and run them on iPhone, iPad, and Vision Pro by
dropping the resulting .wasm into the rootshell directory.
Three reference implementations, same surface area:
| Demo | Language | Path | Builds with |
|---|---|---|---|
wasm-demo |
Rust | rust/ |
rustup target add wasm32-wasip1 |
wasm-demo-go |
Go | go/ |
Go 1.21+ (GOOS=wasip1 GOARCH=wasm) or TinyGo 0.31+ |
wasm-demo-swift |
Swift | swift/ |
Swift 6.3+ with the swift.org wasm SDK (wasm32-unknown-wasip1) |
All three exercise the same subcommands (hello, fs-write, fs-read,
fs-escape, tcp-client, tls-client, dns-query, tcp-listen,
bonjour, all)
and link against the same host-provided rootshell_socket_* and
rootshell_terminal_* ABIs. Use them as starting points for your own
ports.
A note on Swift binary size: the demo here deliberately avoids
import Foundation. Foundation works on WASI (URLs, FileHandle,
ProcessInfo, Data all behave), but it drags in roughly 50 MB of
extra wasm (ICU, the full NS object graph, the Swift concurrency
runtime). At that size, even hello takes several seconds to
instantiate on an iPhone or Vision Pro because the runtime has to
parse and validate every byte of the module before main runs. Sticking
to WASILibc for file I/O / stdio / environ / exit keeps the demo
around 3 MB with no measurable startup delay. Foundation is fine if
you genuinely need it (JSON, URL parsing, NSCalendar, etc.), but go in
knowing the cost.
# Rust
cd rust && ./build.sh
# -> dist/wasm-demo.wasm
# Go (standard)
cd go && ./build.sh
# -> dist/wasm-demo-go.wasm
# Go (TinyGo, smaller binary)
cd go && ./build.sh tinygo
# -> dist/wasm-demo-go-tinygo.wasm
# Swift (needs the SwiftWasm wasm32-unknown-wasi SDK, see swift/build.sh)
cd swift && ./build.sh
# -> dist/wasm-demo-swift.wasmGet the resulting .wasm onto the device by either:
-
Files app: drop it into the rootshell directory.
-
scp / sftp from the iOS local shell: the fastest iteration path. Open a local shell tab on the device and pull straight from your build machine. rootshell's
scpand interactivesftpclients are built in and land files in the same sandbox the WASM runtime reads from.$ scp you@build-host:wasm-demo/dist/wasm-demo.wasm . $ ./wasm-demo.wasm helloOr interactively:
$ sftp you@build-host sftp> get wasm-demo/dist/wasm-demo.wasm sftp> bye
Either way the file lands in the rootshell directory, which is the WASM sandbox root (see Filesystem sandbox). From a local shell tab:
$ ./wasm-demo.wasm hello
hello from wasm-demo
argv = ["./wasm-demo.wasm", "hello"]
HOME = /
PWD = /
$ ./wasm-demo.wasm all # full battery against real internet hostsThe WASM runtime is iOS / visionOS only. macOS uses a real native
shell with full fork/exec, so .wasm files there are just data; run the
underlying tool directly instead.
rootshell ships with a curated set of native tools (vim, ripgrep, curl,
bat, and so on), but the long tail is endless. The WASM runtime is the
escape hatch: pick any language that has a WASI Preview 1 target, build a
static .wasm, drop it on the device, run it. No jailbreak, no developer
account, no recompiling rootshell.
What you get on top of vanilla WASI:
- A filesystem preopen rooted at the rootshell document directory,
with
..-traversal blocked. No access to system paths. - A host-provided socket ABI (
rootshell_socket_*) that lets WASM programs do real BSD-style networking (TCP, UDP, TLS-on-TCP with host-side cert validation, DNS) through Apple's Network.framework. WASI Preview 2 sockets are not used. - A terminal raw/cooked switch (
rootshell_terminal_set_raw) so full-screen TUIs (vim/htop-style) work alongside line-oriented programs (rclone-style configurators) inside the same shell session. - WASI argv, environ, stdin/stdout/stderr, exit wired through to the shell tab. Same UX as any other built-in command.
The runtime exposes WASI Preview 1 file ops (path_open, fd_read,
fd_write, fd_close, path_create_directory, path_remove_directory,
path_unlink_file, path_rename, path_filestat_get,
path_filestat_set_times, fd_seek, fd_sync, and so on) over a single
preopened directory equal to the rootshell document directory (what
shows up in Files.app as the "rootshell" folder).
Path semantics inside the WASM process:
| Input | Resolves to |
|---|---|
foo |
dirfd + /foo (normal WASI openat) |
/foo |
sandbox root + /foo (virtual-absolute) |
~ |
sandbox root (= HOME) |
~/foo |
sandbox root + /foo |
../../etc/passwd |
denied. Path is canonicalised, then prefix-checked against the sandbox root. |
The host rejects paths containing a NUL byte, paths that resolve outside
the sandbox root, and any attempt to open a dirfd that wasn't itself
opened inside the sandbox. The fs-escape subcommand in both demos is
the negative test for this: it tries to open ../../outside.txt and
expects an EACCES.
Environment-wise the runtime sets HOME=/, PWD=/, and USER=mobile
inside the sandbox (so ~ expansion in app-level shells matches the
WASM view). argv[0] is the path the user typed.
Sockets bypass WASI Preview 1 entirely. WASI 1 has no socket support, and WASI Preview 2's sockets are not yet broadly available across toolchains, so rootshell exposes its own thin ABI that maps 1:1 onto BSD calls, and the host implements them with Network.framework.
All calls follow the same shape:
- Return
i32errno (0 = success, non-zero from the WASI errno set:EBADF=8,EACCES=2,EINVAL=28,ECONNREFUSED=14,ETIMEDOUT=73,ENETUNREACH=50,EINTR=27,EADDRINUSE=1,ENOSYS=52,EIO=29,ENOENT=44,EAGAIN=6,EISCONN=30,EMSGSIZE=35,ENOBUFS=42,EPIPE=64). - Take
i32socket fds. Note: this is a separate fd space from WASI fs. Fds returned byrootshell_socket_socketmust not be passed tofd_close, and vice versa. - Buffers are linear-memory offsets (
*const u8/*mut u8in Rust,unsafe.Pointerin Go). sockaddrlayout matches BSDsockaddr_in(family=2, port BE, then 4 bytes IP) andsockaddr_in6(family=30, port BE, flowinfo, 16 bytes IP, scope) byte-for-byte.familylives in the first byte (notsa_len/sa_family); the demos and host agree on a no-sa_lenlayout.- Every call is synchronous from the WASM program's perspective.
Internally the host parks the Worker thread on
Atomics.waituntil Network.framework delivers a result, but the WASM program just sees a blocking syscall return.
Constants:
#define AF_INET 2
#define AF_INET6 30
#define SOCK_STREAM 1
#define SOCK_DGRAM 2| Symbol | Maps to | Notes |
|---|---|---|
rootshell_socket_socket(domain, type, fd_out) -> errno |
socket(2) |
domain in {AF_INET, AF_INET6}, type in {SOCK_STREAM, SOCK_DGRAM}. |
rootshell_socket_bind(fd, addr, addrlen) -> errno |
bind(2) |
addr is a sockaddr_in / sockaddr_in6 blob. |
rootshell_socket_listen(fd, backlog) -> errno |
listen(2) |
Backing NWListener is started inside the broker. |
rootshell_socket_accept(fd, fd_out) -> errno |
accept(2) |
Blocks until an inbound connection arrives. Returns a new connected fd. |
rootshell_socket_connect(fd, addr, addrlen) -> errno |
connect(2) |
IP literal in the sockaddr; the host does not resolve DNS here. |
rootshell_socket_send(fd, buf, len, sent_out) -> errno |
send(2) |
Short writes possible; check sent_out. |
rootshell_socket_recv(fd, buf, len, recv_out) -> errno |
recv(2) |
Returns 0 in recv_out at EOF. |
rootshell_socket_shutdown(fd, how) -> errno |
shutdown(2) |
how in {SHUT_RD=0, SHUT_WR=1, SHUT_RDWR=2}. |
rootshell_socket_close(fd) -> errno |
close(2) |
Releases the underlying NWConnection / NWListener. |
rootshell_socket_getsockname(fd, addr_out, addrlen_io) -> errno |
getsockname(2) |
Local endpoint after bind/connect. |
rootshell_socket_getpeername(fd, addr_out, addrlen_io) -> errno |
getpeername(2) |
Remote endpoint of a connected socket. |
UDP uses the same socket / bind / close calls (with type = SOCK_DGRAM) plus:
| Symbol | Maps to |
|---|---|
rootshell_socket_sendto(fd, buf, len, addr, addrlen, sent_out) -> errno |
sendto(2) |
rootshell_socket_recvfrom(fd, buf, len, addr_out, addrlen_io, recv_out) -> errno |
recvfrom(2) |
UDP sockets are real BSD sockets on the host and behave like them:
- A socket is unconnected until
connect.sendtocan reach any destination, including a multicast group such as224.0.0.251:5353, and replies from any sender come back torecvfrom. bindbinds. Pass port 0 for an ephemeral port, or a fixed one to receive datagrams sent to it. Sockets setSO_REUSEADDRandSO_REUSEPORT, so a port the system also uses (5353) can be shared.- Each
recv/recvfromreturns one whole datagram. Bytes pastlenare discarded, as with BSD sockets. Up to 256 datagrams queue per socket; later ones drop until the program reads. addr_outis filled with the address the datagram came from; theaddrlen_ioin/out parameter tells the host how much space is available and gets overwritten with the actual length. Thedns-querydemo checks this against the resolver's address.- After
connect, the socket only receives from that peer, andsendgoes to it. shutdownwithSHUT_WRmakes later sends fail withEPIPE;SHUT_RDdiscards queued and later datagrams, and receives return 0.
| Symbol | Maps to |
|---|---|
rootshell_socket_set_recv_timeout(fd, timeout_ms) -> errno |
setsockopt(SO_RCVTIMEO) |
After this, a recv or recvfrom on fd that has waited timeout_ms
milliseconds without data returns EAGAIN. Pass 0 to wait forever again
(the default). Works on TCP and UDP sockets. The dns-query demos use
a 5-second limit so a lost reply doesn't hang them.
| Symbol | Behaviour |
|---|---|
rootshell_socket_bonjour_lookup(type, type_len, timeout_ms, out_buf, out_max, out_len) -> errno |
Browse local. for a service type and resolve each instance. |
type is a UTF-8 service type such as _ssh._tcp. The host browses
with the system's Bonjour stack, resolves every instance it finds to a
host name, port and addresses, and never connects to the service. It
returns once every instance has a port and at least one address and no
new answer has arrived for half a second, or when timeout_ms (at most 60000) passes,
whichever comes first.
out_buf receives one line per instance, tab-separated:
<instance name>\t<host>\t<port>\t<address>,<address>,...\n
For example iPhone\tiPhone.local.\t49152\t192.168.1.20,fe80::1c2b:3a4d:5e6f:7081%en0.
Only whole lines are written and out_len gets the byte count; a buffer
too small for even one line returns ENOBUFS. Nothing found in time
returns ETIMEDOUT.
iOS only lets an app browse service types it declares in
NSBonjourServices. rootshell declares _ssh._tcp, _rfb._tcp and
_remotepairing._tcp; any other type, or Local Network access turned
off for rootshell, returns EACCES. Open a request issue to add a type.
These avoid the round-trip through a sockaddr by handing the host the
hostname directly. Network.framework does DNS, happy-eyeballs,
VPN-aware routing, and (for TLS) handshake + cert validation. Use
these in preference to connect / sendto when you have a name rather
than an IP. They Just Work behind the iOS VPN and Tailscale stacks.
| Symbol | Behaviour |
|---|---|
rootshell_socket_connect_host(fd, host, host_len, port) -> errno |
TCP connect. host is a UTF-8 hostname or IP literal. |
rootshell_socket_tls_connect_host(fd, host, host_len, port) -> errno |
TLS-on-TCP. Sets up the TLS connection from scratch (no prior connect_host). After it returns 0, send / recv operate on the plaintext stream. SNI = host. Cert validation uses Apple's trust store. |
rootshell_socket_bind_host(fd, host, host_len, port) -> errno |
bind by interface name / IP literal. |
rootshell_socket_sendto_host(fd, buf, len, host, host_len, port, sent_out) -> errno |
UDP sendto by hostname, looked up with the system resolver. |
rootshell_socket_resolve_v4(host, host_len, out_buf, out_max, count_out) -> errno |
Explicit A-record resolution. out_buf receives count_out * 4 bytes packed back-to-back. |
rootshell_socket_resolve_v6(host, host_len, out_buf, out_max, count_out) -> errno |
Explicit AAAA-record resolution. 16 bytes per entry. |
For most uses you do not need to call resolve_*: pass the
hostname straight to connect_host / tls_connect_host and let
Network.framework's resolver handle it. The explicit resolvers exist
for tools that need to inspect or pick from the result set (DNS
diagnostics, multi-homed clients, custom happy-eyeballs).
- Raw sockets / ICMP. Entitlement-gated on iOS.
setsockopt/getsockopt. Knobs likeTCP_NODELAYandIP_MULTICAST_*are mostly N/A under Network.framework. Reasonable defaults are baked in, andSO_RCVTIMEOhas its own call (rootshell_socket_set_recv_timeout). Open a request issue if you need a specific knob.select/poll/epoll/kqueue. The broker is synchronous and one-fd-at-a-time inside a single call, and WASIpoll_oneoffonly takes clock subscriptions. To wait for an answer and then give up, set a receive time limit. For multiplexing, build it from threads (Go goroutines work; TinyGo's scheduler also works) or loops overrecvcalls with a short time limit.
Local shell input has two modes when a WASM program is running. The shell chooses based on a single bit owned by the WASM process, flippable at runtime:
i32 rootshell_terminal_set_raw(i32 enabled); // 0 = cooked, 1 = raw
i32 rootshell_terminal_is_tty(i32 fd); // 1 if fd 0/1/2 is on the terminalset_raw returns errno (0 on success). The flip is process-scoped:
when your WASM exits, the shell goes back to cooked behaviour
automatically.
The shell emulates POSIX termios ICANON | ECHO | ICRNL | ERASE:
| Behaviour | Detail |
|---|---|
ICANON |
stdin is line-buffered. Bytes accumulate in the shell until the user presses Enter, then the whole line + \n is delivered to the WASM in a single fd_read. |
ECHO |
Each typed printable byte is echoed back to the display. The WASM does not need to print what the user typed. |
ICRNL |
The terminal sends \r on Enter; cooked mode translates that to \n before delivery, so bufio.NewReader.ReadString('\n'), read_line, fgets, and friends all work as you'd expect on Linux. |
ERASE |
Backspace / DEL erases the previous byte from the buffer and the display. Bytes are not delivered to the WASM until Enter. |
Ctrl-C |
Cancels the WASM process (delivered as SIGINT-equivalent; the host fires cancel on the runtime). |
Ctrl-D |
On an empty line, delivers EOF (zero-byte read) to the WASM. On a non-empty line, ignored (matches Linux VEOF). |
Cooked mode is the right default for: line-oriented configurators
(rclone interactive setup), question/answer prompts, anything that
calls read_line / ReadString('\n') / fgets.
Every byte is forwarded to the WASM immediately, verbatim, without
echo and without CR->LF translation. No line buffering, no Ctrl-C
handling at the shell level; the program owns the keystroke stream.
Raw mode is the right choice for: full-screen TUIs (vim/less/htop style), keystroke-by-keystroke games, programs that draw their own prompts and need to see arrow keys / function keys / mouse escape sequences as they arrive.
If you flip into raw mode, you are responsible for handling
Ctrl-C yourself (it arrives as a 0x03 byte). Most TUI libraries
do this automatically.
You can flip back to cooked with rootshell_terminal_set_raw(0),
for example to drop into cooked for an interactive prompt and then
back to raw to redraw the screen.
Returns 1 if the given WASI fd (0, 1, 2 == stdin/stdout/stderr) is
attached to the terminal. Always 1 today, since the shell is the only
delivery mechanism, but useful for code that wants to fall back to
non-TTY behaviour when redirected. (./wasm-demo.wasm hello > file.txt is not currently supported by the shell driver; the
demo binary still returns 1 here because the host has no other way
to deliver stdout.)
Each subcommand exists to exercise one slice of the runtime:
| Command | Surface tested |
|---|---|
hello |
argv, environ, stdout, exit code |
fs-write <path> |
path_open + fd_write + fd_close inside the sandbox |
fs-read <path> |
path_open read + fd_read + EOF |
fs-escape ../../outside.txt |
sandbox rejects with EACCES (negative test) |
tcp-client <host> <port> |
socket / connect_host / send / recv / close against an HTTP server |
tls-client <host> <port> |
tls_connect_host + cert validation against an HTTPS server |
dns-query <name> [resolver] |
hand-built DNS/A query over UDP via sendto_host + recvfrom (also proves peer address is delivered) |
tcp-listen <port> |
bind / listen / accept + one-shot echo |
bonjour <type> [timeout_ms] |
bonjour_lookup: prints each instance's name, host, port and addresses |
all |
runs every self-contained subcommand plus dns-query, tcp-client, tls-client against real internet hosts |
tcp-listen needs a peer to be useful; it's driven by the in-app
wasm test self-test runner (which spins up a loopback client),
not by all.
The full source for all three bindings is the canonical reference for
the ABI. For Rust see rust/src/socket_shim.rs;
for Go see go/socket.go; for Swift see
swift/Sources/wasm-demo-swift/SocketShim.swift.
Anything that targets WASI Preview 1 will run. Known-good toolchains:
- Rust:
rustup target add wasm32-wasip1, thencargo build --target wasm32-wasip1 --release. - Go:
GOOS=wasip1 GOARCH=wasm go build(Go 1.21+). - TinyGo:
tinygo build -target=wasip1 -opt=z(much smaller binaries, occasional stdlib gaps). - Swift: install the official swift.org
wasmSDK withswift sdk install <artifactbundle url>(the 6.3.2 bundle targetswasm32-unknown-wasip1), thenswift build --swift-sdk swift-6.3.2-RELEASE_wasm -c release. Needs Swift 6.0+ for the@_extern(wasm, module:, name:)attribute used to import host functions, plus a matching host toolchain (use swiftly to keep them in sync). Skipimport Foundationunless you need it — see the size note above. - C / C++: wasi-sdk (
clang --target=wasm32-wasi). - Zig:
zig build-exe -target wasm32-wasi. - AssemblyScript, Grain, etc.: anything that emits a Preview 1 binary.
To use the rootshell socket / terminal ABIs from a new language, just declare the imports under the right module name:
- Module
rootshell_socket: allrootshell_socket_*functions. - Module
rootshell_terminal:rootshell_terminal_set_raw,rootshell_terminal_is_tty.
In Rust the imports default to module env and the host accepts that
as a fallback; in Go the //go:wasmimport directive requires an
explicit module name (see go/socket.go); in Swift
6.0+ the @_extern(wasm, module:, name:) attribute names the module
explicitly (see swift/Sources/wasm-demo-swift/SocketShim.swift).
Drop the resulting .wasm into the rootshell document directory (the
Files app "rootshell" folder, or scp / sftp it in directly from a
local shell tab) and invoke it by name. Working directory inside the
WASM matches the shell's pwd at launch.