{"id":47727397,"url":"https://github.com/hyperlight-dev/hyperlight-sandbox","last_synced_at":"2026-04-07T05:03:15.590Z","repository":{"id":348204918,"uuid":"1196690580","full_name":"hyperlight-dev/hyperlight-sandbox","owner":"hyperlight-dev","description":"A multi-backend sandboxing framework for running untrusted code with controlled host capabilities built on Hyperlight.","archived":false,"fork":false,"pushed_at":"2026-03-31T07:38:17.000Z","size":502,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T09:28:45.588Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperlight-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T00:18:33.000Z","updated_at":"2026-03-31T06:47:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyperlight-dev/hyperlight-sandbox","commit_stats":null,"previous_names":["hyperlight-dev/hyperlight-sandbox"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hyperlight-dev/hyperlight-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperlight-dev","download_url":"https://codeload.github.com/hyperlight-dev/hyperlight-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperlight-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31316008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T20:52:27.962Z","updated_at":"2026-04-02T20:52:28.805Z","avatar_url":"https://github.com/hyperlight-dev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003ch1\u003eHyperlight\u003c/h1\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/hyperlight-dev/hyperlight/refs/heads/main/docs/assets/hyperlight-logo.png\" width=\"150px\" alt=\"hyperlight logo\"/\u003e\n    \u003cp\u003e\u003cstrong\u003eHyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within applications. It enables safe execution of untrusted code within \u003ci\u003emicro virtual machines\u003c/i\u003e with very low latency and minimal overhead.\u003c/strong\u003e \u003cbr\u003e We are a \u003ca href=\"https://cncf.io/\"\u003eCloud Native Computing Foundation\u003c/a\u003e sandbox project. \u003c/p\u003e\n\u003c/div\u003e\n\n\u003e Note: Hyperlight is a nascent project with an evolving API and no guaranteed support. Assistance is provided on a\n\u003e best-effort basis by the developers.\n\n# Hyperlight Sandbox\n\nA multi-backend sandboxing framework for running untrusted code with controlled host capabilities. Built on [Hyperlight](https://github.com/hyperlight-dev/hyperlight).\n\n## Overview\n\nhyperlight-sandbox provides a unified API across multiple isolation backends. All backends share a common capability model.  A python SDK is provided.\n\n- **Secure code execution** -- Run untrusted code in isolated sandboxes\n- **Host tool dispatch** -- Register callables as tools; guest code invokes them by name with schema-validated arguments\n- **Capability-based file I/O** -- Read-only `/input` directory, writable `/output` directory, strict path isolation\n- **Snapshot / restore** -- Capture and rewind sandbox runtime state\n- **Network allowlisting** -- Outbound HTTP is deny-by-default; allow specific domains and methods with `allow_domain()`\n\nFor 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).\n\n### Use Cases\n\n- **File Processing**: Process provided files in Python and return a summarized report\n- **Code Mode**: Let an agent write a script that calls your tools directly, reducing token usage\n- **Sandboxed Execution** as a library: drop into an existing app or library without building a custom runtime\n- **Agent Skills** combine scripts into multi-step workflows that run in isolation (future work)\n\n#### Agent Use Case\n\n```mermaid\nflowchart TD\n    A[Copilot Agent]\n    subgraph SB[Hypervisor Sandbox]\n        C[Run sandbox code]\n        D[Tool call fetch_data]\n        E[Tool call compute]\n        C --\u003e D\n        C --\u003e E\n    end\n    A --\u003e C\n    D --\u003e G[Host fetch via external service]\n    E --\u003e H[Host compute returns result]\n    SB --\u003e R[Result returned to agent]\n    R --\u003e A\n```\n\n## Quick Start\n\nPython SDK:\n\n```shell\nuv pip install \"hyperlight-sandbox[wasm,python_guest]\"\n```\n\nAnd to use it:\n\n```python\nfrom hyperlight_sandbox import Sandbox\n\nsandbox = Sandbox(backend=\"wasm\", module=\"python_guest.path\")\nsandbox.register_tool(\"add\", lambda a=0, b=0: a + b)\nsandbox.allow_domain(\"https://httpbin.org\")\n\nresult = sandbox.run(\"\"\"\ntotal = call_tool('add', a=3, b=4)\nresp = http_get('https://httpbin.org/get')\nprint(f\"3 + 4 = {total}, HTTP status: {resp['status']}\")\n\"\"\")\nprint(result.stdout)\n```\n\n## Sandbox Backends\n\n### Wasm Component Sandbox\n\nLoads 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.\n\n```rust\nuse hyperlight_sandbox::{Sandbox, ToolRegistry};\nuse hyperlight_wasm_sandbox::Wasm;\nuse serde::Deserialize;\n\n#[derive(Deserialize)]\nstruct MathArgs { a: f64, b: f64 }\n\nfn main() {\n    let mut tools = ToolRegistry::new();\n    tools.register_typed::\u003cMathArgs, _\u003e(\"add\", |args| {\n        Ok(serde_json::json!(args.a + args.b))\n    });\n\n    let mut sandbox = Sandbox::builder()\n        .guest(Wasm)\n        .module_path(\"guests/python/python-sandbox.aot\")\n        .with_tools(tools)\n        .build()\n        .expect(\"failed to create sandbox\");\n\n    let result = sandbox.run(r#\"\nresult = call_tool('add', a=3, b=4)\nprint(f\"3 + 4 = {result}\")\n\"#).unwrap();\n    print!(\"{}\", result.stdout);\n\n    // Snapshot and restore interpreter state\n    let snap = sandbox.snapshot().unwrap();\n    sandbox.run(\"print('hello world')\").unwrap();\n    sandbox.restore(\u0026snap).unwrap();\n    //fresh env\n    sandbox.run(\"print('hello world 2!')\").unwrap();\n}\n```\n\nSee `src/wasm_sandbox/examples/` for file I/O and network demos.\n\n### HyperlightJS Sandbox\n\nRuns 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.\n\n```rust\nuse hyperlight_javascript_sandbox::HyperlightJs;\nuse hyperlight_sandbox::{Sandbox, ToolRegistry};\nuse serde::Deserialize;\n\n#[derive(Deserialize)]\nstruct MathArgs { a: f64, b: f64 }\n\nfn main() {\n    let mut tools = ToolRegistry::new();\n    tools.register_typed::\u003cMathArgs, _\u003e(\"add\", |args| {\n        Ok(serde_json::json!(args.a + args.b))\n    });\n\n    let mut sandbox = Sandbox::builder()\n        .guest(HyperlightJs)\n        .with_tools(tools)\n        .build()\n        .expect(\"failed to create sandbox\");\n\n    let result = sandbox.run(r#\"\nconst sum = call_tool('add', { a: 10, b: 20 });\nconsole.log('10 + 20 = ' + sum);\n\"#).unwrap();\n    print!(\"{}\", result.stdout);\n\n    // Snapshot and restore\n    let snap = sandbox.snapshot().unwrap();\n    sandbox.run(\"globalThis.counter = 100;\").unwrap();\n    sandbox.restore(\u0026snap).unwrap();\n    // fresh env counter is undefined again!\n}\n```\n\nSee `src/javascript_sandbox/examples/` for file I/O and network demos.\n\n### Nanvix Sandbox\n\nA microkernel-based backend built on [hyperlight-nanvix](https://github.com/hyperlight-dev/hyperlight-nanvix) that runs JavaScript or Python inside a Nanvix VM. Currently limited to basic code execution with stdout capture -- no host tools, file I/O, networking, or snapshot support yet.\n\n```rust\nuse hyperlight_nanvix_sandbox::{NanvixJavaScript, NanvixPython};\nuse hyperlight_sandbox::Sandbox;\n\nfn main() {\n    // JavaScript\n    let mut js = Sandbox::builder()\n        .guest(NanvixJavaScript)\n        .build()\n        .expect(\"failed to create JS sandbox\");\n\n    let result = js.run(r#\"console.log(\"Hello from Nanvix JS!\");\"#).unwrap();\n    print!(\"{}\", result.stdout);\n\n    // Python\n    let mut py = Sandbox::builder()\n        .guest(NanvixPython)\n        .build()\n        .expect(\"failed to create Python sandbox\");\n\n    let result = py.run(r#\"print(\"Hello from Nanvix Python!\")\"#).unwrap();\n    print!(\"{}\", result.stdout);\n}\n```\n\n## Building\n\nTool requirements:\n\n- just\n- uv\n- npm\n\n```bash\n# Build everything (Rust backends, Wasm guests, Python SDK)\njust build-all\n\n# Run the example suite\njust examples\n```\n\nOther useful commands:\n\n```bash\njust build-all         # Build all Rust backends, Wasm guests, and Python SDK\njust test              # Run full test suite (Rust + Python)\njust lint              # Lint Rust and Python code\njust fmt               # Format all code\n```\n\n## Join our Community\n\nPlease review the [CONTRIBUTING.md](./CONTRIBUTING.md) file for more information on how to contribute to\nHyperlight.\n\nThis project holds fortnightly community meetings to discuss the project's progress, roadmap, and any other topics of interest. The meetings are open to everyone, and we encourage you to join us.\n\n- **When**: Every other Wednesday 09:00 (PST/PDT) [Convert to your local time](https://dateful.com/convert/pst-pdt-pacific-time?t=09)\n- **Where**: Zoom! - Agenda and information on how to join can be found in the [Hyperlight Community Meeting Notes](https://hackmd.io/blCrncfOSEuqSbRVT9KYkg#Agenda). Please log into hackmd to edit!\n\n## Chat with us on the CNCF Slack\n\nThe Hyperlight project Slack is hosted in the CNCF Slack #hyperlight. To join the Slack, [join the CNCF Slack](https://www.cncf.io/membership-faq/#how-do-i-join-cncfs-slack), and join the #hyperlight channel.\n\n## More Information\n\nFor more information, please refer to the [docs directory](./docs/) and the [end-user overview slides](./docs/end-user-overview-slides.md).\n\n## Code of Conduct\n\nSee the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).\n\n[wsl2]: https://docs.microsoft.com/en-us/windows/wsl/install\n\n[kvm]: https://help.ubuntu.com/community/KVM/Installation\n\n[whp]: https://devblogs.microsoft.com/visualstudio/hyper-v-android-emulator-support/#1-enable-hyper-v-and-the-windows-hypervisor-platform\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperlight-dev%2Fhyperlight-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperlight-dev%2Fhyperlight-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperlight-dev%2Fhyperlight-sandbox/lists"}