Lunatic is a universal runtime designed for fast, robust and scalable server-side applications. It's inspired by Erlang. Languages can target it when their toolchains emit compatible WebAssembly and provide bindings for the Lunatic host APIs they need. You can read more about the motivation behind Lunatic here.
Language bindings and ecosystem libraries are available for:
If you would like to see other languages supported or just follow the discussions around Lunatic, join our discord server.
- Creating, cancelling & waiting on processes
- Capability and resource isolation (least-privilege config defaults and attenuation are implemented; complete FD/network/process/queue accounting remains open)
- Process supervision (the native Supervisor automatically consumes acknowledged child monitor events and escalates restart exhaustion; guest-side supervisor trees and distributed supervision remain pending)
- Channel based message passing
- TCP networking
- Filesystem access
- Distributed nodes (two actual-Wasm guests complete 16 measured registry lookup → loopback mTLS QUIC → remote mailbox → reply rounds; multi-host operation, partitioned owner exit, and cross-node failure recovery remain unverified)
- Hot reload (the watch-equivalent path interrupts running Wasm, preserves compatible state, waits for acknowledgements, and commits or rolls back locally; the current 16-process evidence measures bounded live-path latency, but no portable latency target is established and the entrypoint-reentry contract and distributed reload remain unverified)
- OTP patterns (native GenServer/Supervisor/GenStatem/GenEvent adapters and an actual-Wasm OTP call/reply/timeout/stop contract are verified; high-level cross-language SDKs and distributed OTP remain pending)
Unchecked entries are active implementation areas, not unavailable concepts. The canonical evidence and known gaps are maintained in the core-values status; historical phase and benchmark reports do not override it.
- CORE_VALUES.md - Design principles and Erlang inspiration
- docs/core_values/status.md - Up-to-date implementation compliance review
- docs/security/AUDIT_LOGGING.md - How to capture and route audit log events
- docs/security/NODE_CONTROL_BEARER.md - Node-control bearer transport, rotation, and revocation contract
- docs/hot_reload/HOT_RELOAD_ARCHITECTURE.md - Hot reload system design
- docs/hot_reload/HOT_RELOAD_PREEMPTIVE.md - Historical preemptive hot reload design notes
- docs/benchmarks/PERFORMANCE_ANALYSIS.md - Historical component metrics and analysis
- docs/benchmarks/BENCHMARK_RESULTS.md - Historical benchmark measurements and their scope
- docs/benchmarks/BENCHMARK_SUITE.md - Benchmark suite guide and coverage boundaries
If you have rust (cargo) installed, you can build and install the lunatic runtime with:
cargo install lunatic-runtimeOn macOS you can use Homebrew too:
brew tap lunatic-solutions/lunatic
brew install lunaticWe also provide pre-built binaries for Windows, Linux and macOS on the
releases page, that you can include in your PATH.
And as always, you can also clone this repository and build it locally. The only dependency is a rust compiler:
# Clone the repository
git clone https://github.com/lunatic-solutions/lunatic.git
# Jump into the cloned folder
cd lunatic
# Build and install lunatic
cargo install --path .After installation, you can use the lunatic binary to run WASM modules.
To learn how to build modules, check out language-specific bindings:
Lunatic's design centers on lightweight isolated processes, comparable in role to green threads or go-routines in other runtimes. Low spawn cost, small memory overhead, and massive concurrency are design goals; current bounded live-Wasm scale/pressure evidence includes one warm-up plus five measured batches per population with measured spawn and mailbox throughput/rate, p50/p95/p99, 64KiB committed Wasm bytes per guest, and a single-baseline cumulative live-population RSS delta divided by guest count that is explicitly not allocator-attributable, while the remaining large-scale, multi-day/longitudinal, and multi-host gaps are recorded in the implementation status.
Some common use cases for processes are:
- HTTP request handling
- Long running requests, like WebSocket connections
- Long running background tasks, like email sending
- Calling untrusted libraries in an sandboxed environment
What makes the last use case possible are the sandboxing capabilities of WebAssembly. WebAssembly was originally developed to run in the browser and provides extremely strong sandboxing on multiple levels. Lunatic's processes inherit these properties.
Each process has its own stack, heap, and syscall capability context. A guest trap is contained to that process's Wasm instance; higher-level link and supervision behavior is tracked separately in the implementation status.
Code such as C can participate when compiled to compatible WebAssembly. Wasm memory isolation contains many guest memory faults, while safety still depends on the runtime, configured capabilities, host imports, and resource limits; it is not a blanket guarantee for arbitrary native vulnerabilities.
Per-process configuration provides configured filesystem preopens, compile/create/spawn capability flags, memory/table/fuel limits, and network-connection quotas. Untrusted configs deny privileged capabilities by default, and child configs cannot exceed their parent's represented authority. Enforcement coverage still varies by resource type; see the capability contract and implementation status.
Wasm execution uses Wasmtime's async support with fuel yielding and configured epoch deadlines on a work stealing async executor. The current process-global ticker advances only stores associated with the first-created engine; independently constructed later engines do not receive its epoch increments. Async host APIs avoid blocking an executor thread while they wait, but not every host operation is currently proven non-blocking and bounded; see the implementation status for the current boundary.
We intend to eventually make Lunatic completely compatible with WASI. Ideally, you could take existing code, compile it to WebAssembly and run on top of Lunatic; creating the best developer experience possible. We're not quite there yet.
The Rust host/runtime crates follow a coordinated release train. Version 0.14 intentionally changes
process delivery, spawning, mailbox backpressure, resource snapshots, and several embedding types;
host integrations upgrading from 0.13 must follow the
0.13 to 0.14 migration guide. Guest ABI compatibility and any
temporary legacy imports are called out separately in that guide. The new lunatic-otp-patterns
crate is independently versioned at 0.1.0 and requires the 0.14 runtime crates.
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.