diff --git a/README.md b/README.md index c637dc2..b861ad4 100644 --- a/README.md +++ b/README.md @@ -4,30 +4,33 @@

Hyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within applications. It enables safe execution of untrusted code within micro virtual machines with very low latency and minimal overhead.
We are a Cloud Native Computing Foundation sandbox project.

-> Note: Hyperlight is a nascent project with an evolving API and no guaranteed support. Assistance is provided on a -> best-effort basis by the developers. - # Hyperlight Sandbox A multi-backend sandboxing framework for running untrusted code with controlled host capabilities. Built on [Hyperlight](https://github.com/hyperlight-dev/hyperlight). +Supported backends: + +- [Wasm Component Sandbox](#wasm-component-sandbox) (Python/Javascript or provide your own) +- [HyperlightJS Sandbox](#hyperlightjs-sandbox) +- [Nanvix Sandbox](#nanvix-sandbox) + ## Overview -hyperlight-sandbox provides a unified API across multiple isolation backends. All backends share a common capability model. A python SDK is provided. +hyperlight-sandbox provides a unified API across multiple isolation backends. All backends share a common capability model. A python and rust SDK is provided. -- **Secure code execution** -- Run untrusted code in isolated sandboxes +- **Secure code execution** -- Run untrusted code in hardware isolated sandboxes (KVM, MSHV, Hyper-v) - **Host tool dispatch** -- Register callables as tools; guest code invokes them by name with schema-validated arguments -- **Capability-based file I/O** -- Read-only `/input` directory, writable `/output` directory, strict path isolation -- **Snapshot / restore** -- Capture and rewind sandbox runtime state -- **Network allowlisting** -- Outbound HTTP is deny-by-default; allow specific domains and methods with `allow_domain()` +- **Capability-based file access** -- Read-only `/input` directory, writable `/output` directory, strict path isolation +- **Snapshot / restore** -- Capture and rewind sandbox runtime state making it re-useable +- **Network allow listing** -- Network traffic is off by default; allow specific domains and HTTP verbs with `allow_domain()` For a more in depth walkthrough, see the overview slide deck in `docs/end-user-overview-slides.md` (or run `just slides` to view in the browser). ### Use Cases -- **File Processing**: Process provided files in Python and return a summarized report +- **File Processing**: Process provided files and return a summarized report - **Code Mode**: Let an agent write a script that calls your tools directly, reducing token usage -- **Sandboxed Execution** as a library: drop into an existing app or library without building a custom runtime +- **Sandboxed Execution as a library**: drop into an existing app or library to provide plugins - **Agent Skills** combine scripts into multi-step workflows that run in isolation (future work) #### Agent Use Case @@ -51,6 +54,8 @@ flowchart TD ## Quick Start +Requires [KVM](https://help.ubuntu.com/community/KVM/Installation), [MSHV](https://github.com/rust-vmm/mshv) or [Hyper-v](https://learn.microsoft.com/en-us/windows-server/virtualization/hyper-v/get-started/Install-Hyper-V?tabs=powershell&pivots=windows-server) + Python SDK: ```shell @@ -78,7 +83,9 @@ print(result.stdout) ### Wasm Component Sandbox -Loads a Wasm component via [hyperlight-wasm](https://github.com/jsturtevant/hyperlight-wasm) and exposes the full capability surface through WIT-generated bindings. Supports the packaged Python guest and JavaScript guest. Use this for general-purpose workloads that need tools, file I/O, networking, and snapshots. +Loads a Wasm component via [hyperlight-wasm](https://github.com/hyperlight-dev/hyperlight-wasm) and exposes the full capability surface through WIT-generated bindings. Supports the packaged Python guest and JavaScript guest. Use this for general-purpose workloads that need tools, file I/O, networking, and snapshots. + +Build your own using the provided [WIT interface](src/wasm_sandbox/wit/hyperlight-sandbox.wit). See the [python](./src/wasm_sandbox/guests/python/) and [javascript](./src/wasm_sandbox/guests/javascript/) guests for examples. ```rust use hyperlight_sandbox::{Sandbox, ToolRegistry}; @@ -116,11 +123,11 @@ print(f"3 + 4 = {result}") } ``` -See `src/wasm_sandbox/examples/` for file I/O and network demos. +See [examples](./src/wasm_sandbox/examples/) for file I/O and network demos. ### HyperlightJS Sandbox -Runs JavaScript directly on the [HyperlightJS](https://github.com/hyperlight-dev/hyperlight-js) runtime without going through the Wasm component model. Injects `call_tool`, `read_file`, `write_file`, and `fetch` as globals. Supports snapshots, file I/O, and network allowlists. A simpler runtime path when the workload is JavaScript-only. +Runs JavaScript directly on the [HyperlightJS](https://github.com/hyperlight-dev/hyperlight-js) runtime without going through the Wasm component model. Injects `call_tool`, `read_file`, `write_file`, and `fetch` as globals. Supports snapshots, file I/O, and network allowlists. A simpler runtime path when the workload is JavaScript-only and need a smaller footprint. ```rust use hyperlight_javascript_sandbox::HyperlightJs; @@ -156,7 +163,7 @@ console.log('10 + 20 = ' + sum); } ``` -See `src/javascript_sandbox/examples/` for file I/O and network demos. +See [examples](./src/javascript_sandbox/examples/) for file I/O and network demos. ### Nanvix Sandbox diff --git a/examples/Justfile b/examples/Justfile index e716bb8..6054b82 100644 --- a/examples/Justfile +++ b/examples/Justfile @@ -11,8 +11,8 @@ integration-agent-framework-devui-deps: copilot-sdk-example: integration-copilot-sdk-deps uv run python {{repo-root}}/examples/copilot-sdk/copilot_sdk_tools.py -agent-framework-example: integration-agent-framework-deps - uv run python {{repo-root}}/examples/agent-framework/copilot_agent.py --no-wait +agent-framework-example wait="--no-wait": integration-agent-framework-deps + uv run python {{repo-root}}/examples/agent-framework/copilot_agent.py {{ wait }} agent-framework-example-interactive: integration-agent-framework-deps uv run python {{repo-root}}/examples/agent-framework/copilot_agent.py --interactive diff --git a/examples/agent-framework/copilot_agent.py b/examples/agent-framework/copilot_agent.py index 25a18c9..ed77b4e 100644 --- a/examples/agent-framework/copilot_agent.py +++ b/examples/agent-framework/copilot_agent.py @@ -73,9 +73,10 @@ DEFAULT_PROMPTS = [ "Fetch all users, find admins, multiply 6*7, and print the users, admins, and multiplication result. Use one execute_code call.", - "Use execute_code and the python functions http_get/http_post(these are NOT a tools. use like `resp = http_get(\"https://example\")`) to try reading /input/secrets.txt (it doesn't exist — handle the error), then read /input/team.json which does exist, parse it, and print each team member's name and role.", + "Use execute_code and to try reading /input/secrets.txt (it doesn't exist — handle the error), then read /input/team.json which does exist, parse it, and print each team member's name and role.", ( "Use execute_code to demonstrate the network allowlist. In a single code block:\n" + 'Use plain python functions http_get/http_post(these are NOT a tools. use like `resp = http_get("https://example")`) \n' "1. Use http_get to fetch https://httpbin.org/get — this should succeed (GET is allowed)\n" "2. Try http_post to https://httpbin.org/post — this should FAIL (only GET is allowed for httpbin.org)\n" "3. Try http_get to https://github.com — this should FAIL (github.com is not in the allowlist at all)\n"