Skip to content

feat(sandbox): add BoxLite VM runtime backend for hardware-level isolation#424

Closed
DorianZheng wants to merge 1 commit intoNVIDIA:mainfrom
DorianZheng:feat/boxlite-runtime-backend
Closed

feat(sandbox): add BoxLite VM runtime backend for hardware-level isolation#424
DorianZheng wants to merge 1 commit intoNVIDIA:mainfrom
DorianZheng:feat/boxlite-runtime-backend

Conversation

@DorianZheng
Copy link

Summary

Adds BoxLite as an optional VM-based runtime backend for OpenShell sandboxes, providing hardware-level isolation alongside the existing Linux kernel isolation (Landlock + seccomp + netns).

  • New runtime module with RuntimeKind enum dispatch — Process (default, existing behavior) and Boxlite (VM-based, feature-gated)
  • REST API integration — communicates with BoxLite server via HTTP, avoiding native dependency conflicts (sqlite version mismatch)
  • Zero impact on default builds — gated behind boxlite Cargo feature
  • Cross-platform isolation — fills the macOS gap where kernel isolation is currently a no-op

What changes

Component Process Backend (default) BoxLite Backend (new)
Filesystem isolation Landlock VM boundary
Syscall filtering seccomp VM boundary (own kernel)
Network isolation netns + veth VM boundary
macOS support no-op warning full isolation
Proxy / OPA / SSH unchanged unchanged

Usage

# Start BoxLite server (separately)
boxlite serve --port 8100

# Run sandbox with BoxLite backend
openshell-sandbox --runtime boxlite -- echo hello
# or via env var
OPENSHELL_RUNTIME=boxlite BOXLITE_URL=http://localhost:8100 openshell-sandbox -- echo hello

Files

New:

  • crates/openshell-sandbox/src/runtime/mod.rsRuntimeKind, SandboxedProcess enum, SpawnConfig
  • crates/openshell-sandbox/src/runtime/process_backend.rs — wraps existing ProcessHandle
  • crates/openshell-sandbox/src/runtime/boxlite_backend.rs — REST client for BoxLite API

Modified:

  • crates/openshell-sandbox/Cargo.tomlboxlite feature with reqwest + serde
  • crates/openshell-sandbox/src/lib.rs — runtime dispatch in run_sandbox()
  • crates/openshell-sandbox/src/main.rs--runtime CLI arg
  • crates/openshell-sandbox/src/process.rsProcessStatus::from_code() constructor

Closes #421

Test plan

  • cargo check -p openshell-sandbox (no feature) — compiles unchanged
  • cargo check -p openshell-sandbox --features boxlite — compiles with BoxLite
  • cargo test -p openshell-sandbox --features boxlite — 302 tests pass
  • cargo fmt -p openshell-sandbox -- --check — clean
  • Manual: openshell-sandbox --runtime boxlite -- echo hello with BoxLite server running

…ation

Add BoxLite as an optional sandbox runtime backend alongside the existing
Linux kernel isolation (Landlock + seccomp + netns). When enabled, the
agent runs inside a hardware-isolated lightweight VM instead of relying
on kernel primitives.

Architecture:
- New `runtime` module with `RuntimeKind` enum dispatch (Process | Boxlite)
- `SandboxedProcess` enum wraps either ProcessHandle or BoxliteProcess
- `ProcessBackend` wraps existing ProcessHandle::spawn unchanged
- `BoxliteBackend` talks to BoxLite REST API via HTTP (no native dep conflicts)
- Feature-gated behind `boxlite` Cargo feature (zero impact on default builds)

Key changes:
- `run_sandbox()` gains `runtime_kind` parameter for backend selection
- Network namespace creation skipped when backend provides own isolation
- CLI: `--runtime boxlite` or `OPENSHELL_RUNTIME=boxlite` env var
- `ProcessStatus::from_code()` constructor for BoxLite exit code mapping

Closes NVIDIA#421

Signed-off-by: dorianzheng <xingzhengde72@gmail.com>
@DorianZheng DorianZheng requested a review from a team as a code owner March 18, 2026 04:31
@github-actions
Copy link

Thank you for your interest in contributing to OpenShell, @DorianZheng.

This project uses a vouch system for first-time contributors. Before submitting a pull request, you need to be vouched by a maintainer.

To get vouched:

  1. Open a Vouch Request discussion.
  2. Describe what you want to change and why.
  3. Write in your own words — do not have an AI generate the request.
  4. A maintainer will comment /vouch if approved.
  5. Once vouched, open a new PR (preferred) or reopen this one after a few minutes.

See CONTRIBUTING.md for details.

@github-actions github-actions bot closed this Mar 18, 2026
@github-actions
Copy link

Thank you for your submission! We ask that you sign our Developer Certificate of Origin before we can accept your contribution. You can sign the DCO by adding a comment below using this text:


I have read the DCO document and I hereby sign the DCO.


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the DCO Assistant Lite bot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: Add BoxLite VM runtime backend for hardware-level sandbox isolation

1 participant