Hyperlight-js

Provides a capability to run JavaScript inside of Hyperlight using quickjs as the JavaScript engine.

Documentation

• Custom guest runtimes - Extend with native modules and build and embed a custom guest using cargo-hyperlight

• Execution Monitors - Timeout and resource limit enforcement for handler execution

• Persistent snapshots - Save and restore sandbox state across processes

• Observability - Metrics and tracing

• Crashdumps - Creating and analyzing guest crash dumps

• Debugging the guest runtime - Debugging the guest runtime using GDB or LLDB

• JS Host API - Node.js bindings (includes user modules and host functions)

Build prerequisites

1. Install Rust
2. Install just. - cargo install just.
3. Install clang:

For Windows see here.

For Ubuntu:

    wget https://apt.llvm.org/llvm.sh 
    chmod +x ./llvm.sh
    sudo ./llvm.sh 18 all
    sudo ln -s /usr/lib/llvm-18/bin/clang-cl /usr/bin/clang-cl
    sudo ln -s /usr/lib/llvm-18/bin/llvm-lib /usr/bin/llvm-lib

For Azure Linux:

    sudo dnf remove clang -y|| true
    sudo dnf install clang18 -y
    sudo dnf install clang18-tools-extra -y

For macOS:

    xcode-select --install

cargo-hyperlight 0.1.14 searches PATH for llvm-ar; otherwise it may find Apple's incompatible archiver. Add a provisioned compatible LLVM installation to PATH, or add the active Rust toolchain's LLVM directory:

    export PATH="$(rustc --print sysroot)/lib/rustlib/$(rustc -vV | sed -n 's/^host: //p')/bin:$PATH"

    $hostTriple = (rustc -vV | Select-String '^host: ').Line.Substring(6)
    $env:Path = "$(rustc --print sysroot)\lib\rustlib\$hostTriple\bin;$env:Path"

Supported platforms

Host OS	Architecture	Hypervisor
Linux	x86_64	KVM or MSHV
Linux	aarch64	KVM
Windows	x86_64	Windows Hypervisor Platform (WHP)
Windows	aarch64	Windows Hypervisor Platform (WHP)
macOS	aarch64	Hypervisor.framework

The guest runs on the same architecture as the host, so an aarch64 host builds and runs an aarch64-hyperlight-none guest.

Note that MSHV is x86_64-only in practice: hyperlight-host compiles an aarch64 MSHV backend, but it is a stub whose hypervisor detection always reports absent.

Building

To build the project, run:

# Build the project
just build

Testing

To run the tests, run:

just test

Use just test-all to also run monitor and Node.js binding tests.

Guest Memory

SandboxBuilder::with_guest_scratch_size(bytes) controls the shared writable-memory budget for the guest heap, stack, transport pools, page tables, and copy-on-write pages. The default and minimum are 5 MiB; smaller requests are clamped to that minimum. Increase scratch for allocation-heavy handlers or larger transport pools. This budget is not a JavaScript-only heap limit or a total host-process memory limit.

Exhaustion aborts the guest with GuestAborted(MallocFailed, ...) and poisons the sandbox. Restore a snapshot or build a replacement before executing again. Node.js uses SandboxBuilder.setScratchSize(bytes) and reports ERR_GUEST_ABORT.

Running the examples

run_handler example

The run_handler example demonstrates how to process a json formatted event using a JavaScript handler function.

cargo run --example run_handler 

Once you see Enter the name of the example to run or 'exit' to quit: you can enter the name of the example you want to run, valid names are the names of directories in src/hyperlight-js/examples/data (e.g., echo, fibonacci, regex) or exit to quit.

Alternatively you can pass the name of the sample that you want to run on the command line:

cargo run --example run_handler <name_of_sample>

Metrics example

The metrics example demonstrates how to use the prometheus to collect metrics from the guest.

cargo run --example metrics 

Tracing examples

The tracing example demonstrates how to use to configure tracing subscribers

• tracing_forest subscriber

  cargo run --example tracing forest
  

• fmt subscriber

  cargo run --example tracing fmt
  

Debugging the guest runtime hyperlight-js-runtime

Hyperlight-js supports debugging the guest runtime using GDB or LLDB through the gdb feature. For instructions on how to set up debugging, see the Debugging the guest runtime guide.