Hyperlight-js

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

• 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)

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"

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.

To build the project, run:

# Build the project
just build

To run the tests, run:

just test

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>

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

cargo run --example metrics 

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

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.