Larva is a lightweight headless browser engine (HTML + DOM + JavaScriptCore,
no rendering) built on the Lava runtime. See docs/LARVA.md
for the goals, architecture decisions and roadmap.
The browser layer is at an early stage: the per-thread JSC VM pool is in the tree,
while the page lifecycle, the network stack with client profiles, the HTML parser
and the DOM are not. The roadmap table in docs/LARVA.md carries the status of each
stage. What builds and runs today is the Lava runtime below.
The underlying runtime is written in Odin on top of JavaScriptCore (JSC),
providing the event loop, native I/O transports, and core Web APIs (fetch,
URL, Web Streams, timers). See docs/ARCHITECTURE.md
for how the runtime pieces fit together.
- Odin (CI pins
dev-2026-11awith LLVM 18) - JavaScriptCore development headers and libraries
- SQLite development headers and libraries (for
node:sqlite) - OpenSSL development headers and libraries (for
fetchHTTPS/TLS). The roadmap replaces it with BoringSSL (stage 2); until that lands, OpenSSL is what links.
On Linux, the JSC package is exposed through pkg-config as javascriptcoregtk-6.0,
SQLite as sqlite3, and OpenSSL as openssl
(e.g. apt-get install libjavascriptcoregtk-6.0-dev libsqlite3-dev libssl-dev).
On macOS, JSC is provided by the JavaScriptCore framework and SQLite by the
system libsqlite3; OpenSSL comes from Homebrew (brew install openssl@3) and
scripts/build.sh adds its keg-only lib path to the link line.
On Windows, Lava keeps third-party native payloads out of git. Run
make bootstrap-windows-deps (or bash scripts/bootstrap-windows-deps.sh) to
fetch JavaScriptCore/WebKit and the SQLite amalgamation into the ignored .deps/
cache. scripts/build-sqlite-windows.sh then compiles SQLite into
build/sqlite3.lib; WebKit is linked from .deps/webkit/bun-webkit/lib.
Node 26+ (26.13.0 pinned in .nvmrc; oracle suites refuse an older major) and Bun are needed for the JavaScript gates — run bun install once.
They are dev-only (markdownlint-cli2, acorn/acorn-walk for the
prototype-pollution ratchet, fast-check for make test-property); bin/lava
links none of them. make check-js is an always-gate and now fails without them.
make buildRun it:
make eval SOURCE="console.log('hello from Lava')"
make run FILE=app.jsUseful project commands:
make help
make bootstrap-windows-deps
make check
make check-jsc
make check-native
make test
make test-lava
make test-sqlite-node
make test-sqlite-lava
make check-js
make check-md
make test-property
make test-mutation
make benchcmd/lava- command line entry point, and the Lava-only Odin testspkg/runtime- JavaScript runtime orchestration and native primitivespkg/runtime/js- embedded JavaScript:Buffer,fetch, streams,URL,httppkg/runtime/eventloop- native event-loop abstraction using io_uring/epoll on Linuxpkg/jsc- JavaScriptCore foreign declarations and the private-ABI probespkg/std/sqlite- SQLite bindingstests- oracle suites (node-compat,runtime,std,stdio), differential property tests (property) and the mutation manifestbench- node-vs-Lava benchmarks, andbench/jsc-vmfor JSC VM costsruntime/gates- gate integrity checks and the oracle case-count assertionsscripts- build, check and test-runner scriptsagents- review playbooks and specialist definitionsdocs-LARVA.md(goals and roadmap),ARCHITECTURE.md(the runtime),GLOBAL-STATE.md(page-isolation audit),lava/(I/O design notes)
Larva is licensed under the GNU Affero General Public License v3.0
(AGPL-3.0-only). If you modify Larva and let others use it over a network, the
AGPL requires you to offer them the source of your modified version.
A commercial licence is available for teams that cannot meet those terms, and it is also how the separately distributed extension modules are licensed. Contact the maintainer through the GitHub profile that owns this repository.
Third-party code and the licences of linked libraries are listed in NOTICE. Contributions are accepted under the terms in CONTRIBUTING.md.