What

An external NVIDIA OpenShell compute driver that runs each agent in its own private E2B microVM.

Left: a laptop running the stock openshell CLI. Right: the live event feed from the E2B control plane.

How it works

laptop                    E2B control box (private)                E2B agent box (private, one per sandbox)
openshell CLI ═ tunnel 1 ═► gateway (NVIDIA)                        netns with loopback only
  (mTLS inside)             ↕ unix socket                           openshell-sandbox (NVIDIA, patched)
                            openshell-driver-e2b (this repo) ─E2B──► uid 1500, 0 capabilities, no_new_privs
                            supervisor (NVIDIA) ══ tunnel 2 ════════► └ the agent
                              policy + egress proxy → internet

• Driver (driver/, Rust): implements OpenShell's ComputeDriver gRPC API. Uses NVIDIA's crates at tag v0.1.2 for the boundary protocol (BoundaryConfig, SandboxRuntimeDescriptor, fence guarantees), so the security formats are not re-implemented. E2B calls go through driver/e2b-helper.mjs (official JS SDK), since E2B has no Rust SDK.
• Fence (templates/launch-sandbox.sh): network namespace with only loopback, PID namespace, uid 1500, zero capabilities, no_new_privs, DNS pointed at OpenShell's policy resolver.
• Tunnels: wstunnel through E2B's HTTPS port address. Private sandbox (allowPublicTraffic: false) + traffic token header, random secret upgrade path, --restrict-to one target, E2B certificate verification, OpenShell TLS inside, 10 s heartbeat.
• Secrets: the E2B API key, gateway JWTs and E2B traffic tokens stay in the control box. The agent box gets only its side of the session: the per-session TLS key and the gateway's public keys.
• Templates (Template SDK v2): openshell-workload, openshell-control, openshell-builder.

Try it

npm install
npm run setup              # openshell CLI + wstunnel into .bin/
npm run connect -- --new   # fresh private control box + tunnel, ~12 s; keep running
npm run demo               # create → isolation → default deny → policy → GET 200 / POST 403 / wget denied → audit → delete
npm run watch              # optional: live control-plane feed

Verified

• Live on E2B: sandbox Ready in ~13–17 s; curl GET 200, POST 403 (read-only rule), unlisted host and other programs denied, OCSF audit records. npm run demo asserts these results.
• Health monitor: killing a sandbox's tunnel flips it to Error (TunnelExited) within 5 s.
• Shutdown: SIGTERM with the gateway's watch open stops all supervisors, deletes the E2B boxes, and exits.
• cargo clippy (pedantic + nursery, unwrap/expect denied) clean; cargo test 3 passed; antislop / stopslop addressed.

Review

Two rounds of external review (Codex, gpt-6-astra) plus a self-review. Fixed in this PR:

• tunnels verify E2B's TLS certificate (wstunnel skips it by default)
• unsupported requests (other images, user namespaces, identities other than 1500) are rejected, not silently replaced
• create/delete run as driver-owned tasks: cancellation-safe, no duplicate creates, delete keeps its record until E2B confirms, failed rollbacks are retried
• race-free watch stream; health checks can't mistake a new sandbox for a dead one
• bounded shutdown; owner-checked state dirs with O_NOFOLLOW secret files
• self-review: the log watcher's cleanup could have killed E2B's envd (all E2B commands share its process group)

Limits (not production)

• Landlock v2 patch (patches/landlock-abi2.patch). E2B's guest kernel is 6.1 (Landlock ABI v2); OpenShell v0.1.x requires v3 (kernel ≥ 6.2) for truncate control. With this patch, read-only paths are not protected against truncate. Real fix: an E2B kernel ≥ 6.2 variant.
• Stop/Start (pause/resume) not implemented; driver state is in memory, so a driver restart deletes its boxes on the way down.
• One client certificate shared by the CLI and supervisors.
• The fence evidence records the template name (openshell-workload), not an immutable build ID, so a rebuilt template isn't distinguishable in the evidence. (Open review suggestion.)
• Boxes are created with a 1-hour timeout: run npm run connect -- --new shortly before use.