Sturnkey

Sturnkey is a lightweight JavaScript runtime for CLI, daemon, and local web applications on WASI. It is built as a downstream extension of StarlingMonkey and is designed to run dynamic JavaScript with stock Wasmtime:

wasmtime sturnkey.wasm main.js

Sturnkey's system APIs are inspired by Deno's async-first design, but are independently specified. Sturnkey is not a Deno compatibility layer and does not provide Node.js or npm compatibility.

Status

Sturnkey is in early development. It currently loads JavaScript dynamically, supports the CLI asynchronous lifecycle, and exposes capability-based filesystem and asynchronous TCP client/listener APIs. HTTP server APIs and network hardening will follow in tested increments.

The repository also contains experimental JavaScript-only HTTP/1.1 helpers, a static file server, a server-rendered Web App, and a browser UI for the server-side JavaScript REPL. These are application proofs, not yet a stable HTTP framework.

An experimental SOCKS5 proxy demonstrates domain lookup, outbound TCP, bidirectional relay, and half-close entirely from dynamic JavaScript.

The sturnkey:runtime builtin provides command-line arguments and a Promise-based monotonic sleep() API. The sturnkey:fs builtin provides byte and UTF-8 file I/O plus basic directory operations inside Wasmtime preopens. The sturnkey:net builtin supports numeric-IPv4 TCP clients and foreground listeners over wasi:sockets. The sturnkey:io builtin provides asynchronous line input, raw text output, and terminal detection over WASI CLI streams.

Build

Prerequisites are CMake 3.27 or newer, a C++ toolchain, Rust, and Node.js. The build downloads StarlingMonkey's pinned build dependencies; it does not modify the upstream submodule.

git clone --recurse-submodules https://github.com/enbop/sturnkey.git
cd sturnkey
cmake --preset dev
cmake --build --preset dev --target sturnkey

The default result is build/dev/sturnkey.wasm. It is the primary runtime for CLI programs and foreground daemons and does not import wasi:http.

An additional compatibility build retains StarlingMonkey's WASI HTTP world, Fetch builtin, and incoming HTTP handler:

cmake --preset dev-http
cmake --build --preset dev-http --target sturnkey

That result is build/dev-http/sturnkey-http.wasm. It must be instantiated with Wasmtime's -S http flag, including when the script itself does not use HTTP. Sturnkey development and examples target the CLI-only artifact; the HTTP variant is currently an experimental upstream-compatible option.

CI builds and validates both artifacts on every pull request and push to main, runs the complete suite against sturnkey.wasm, and publishes both as workflow artifacts. Tags beginning with v build optimized versions and publish both in a GitHub release.

Run dynamic JavaScript

// main.js
import { sleep, version } from "sturnkey:runtime";

await sleep(100);
console.log(`Hello from Sturnkey ${version}`);

wasmtime --dir . build/dev/sturnkey.wasm main.js

Directory and network access remain Wasmtime capabilities and must be granted explicitly. For example, raw TCP applications use -S tcp and -S inherit-network; they do not require -S http.

Run the current checks with:

cmake --build --preset dev --target format-check
ctest --preset dev --output-on-failure
wasm-tools validate build/dev/sturnkey.wasm
wasm-tools validate build/dev-http/sturnkey-http.wasm

Design principles

• Keep application JavaScript dynamic; rebuilding the runtime must not be required for each application.
• Use Wasmtime capabilities for filesystem and network isolation.
• Keep the C++ layer limited to SpiderMonkey, Promise, resource, and WASI bridging.
• Build higher-level protocols and application helpers in JavaScript.
• Follow established Web APIs where they exist and document every Sturnkey API.
• Depend on a pinned upstream StarlingMonkey revision without patching it.

Repository layout

runtime/                 Sturnkey native builtins and CLI host bridge
examples/                Executable JavaScript examples
tests/                   Runtime and capability tests
vendor/StarlingMonkey/   Pinned upstream submodule

See UPSTREAM.md for dependency and update policy. See docs/ROADMAP.md for the staged implementation plan and acceptance criteria. See docs/api/runtime.md for the current JavaScript API. See docs/api/filesystem.md for the filesystem API and docs/api/network.md for TCP capabilities. See docs/api/io.md for standard streams and terminal detection. See docs/http.md for the experimental HTTP application layer. See docs/socks5.md for the SOCKS5 application proof. See examples/README.md for copy-and-paste example commands.

License

Apache-2.0 WITH LLVM-exception. See LICENSE and NOTICE.