sandbox-runtime — Architecture

The @mnemose/sandbox-runtime package defines the in-flight sandbox object model and its compute backends. A Sandbox exposes five facets (shell, filesystem, network, tools, services) and supports multi-persona operation via Sandbox.forPersona.

Responsibilities

• Define the Sandbox interface and the five facet ports (ShellFacet, FilesystemFacet, NetworkFacet, ToolsFacet, ServiceRegistry)
• Provide compute backends that implement the facets: kernel-backend (remote agent-kernel) and local-namespace-backend (local process sandbox). Remote MicroVM / libkrun execution is implemented as an ExecutionTargetAdapter in @mnemose/sandbox-execution and selected by SandboxDO when backendKind is microvm or MICROVM_RUNNER_URL is set.
• Provide assemble.ts — composition root that wires facets into a Sandbox from a sandbox spec + persona grants
• Provide the service-registry for named platform service bindings

Key Components

File / Dir	Role
src/index.ts	Public type exports — Sandbox, facet interfaces, persona grants
src/assemble.ts	Composition root — builds a Sandbox from spec + persona grants
src/runtime-sandbox.ts	Runtime sandbox implementation
src/compute/kernel-backend.ts	Compute backend delegating to a remote agent-kernel over the broker
src/compute/local-namespace-backend.ts	Compute backend for a local-namespaced process sandbox
src/network-facet.ts	Egress policy enforcement (guardedFetch, createEgressAgent)
src/service-registry.ts	Named platform service registry (register + resolve)
src/persona-view.ts	Persona-scoped view over a sandbox

Dependencies

• @mnemose/domain — SandboxId, TenantId, SandboxNetworkPolicy, persona grant types
• @mnemose/kernel-protocol — JSON-RPC schemas used by kernel-backend

Data Flow

agent loop / persona
  ↓ assemble(spec, grants) → Sandbox
  ↓ sandbox.shell.exec(cmd) / sandbox.fs.read(path) / sandbox.network.fetch(url)
  ↓ kernel-backend → kernel-broker → agent-kernel (JSON-RPC)
  ↓ local-namespace-backend → local process (namespaced)

Facets

• Shell (ShellFacet) — execute commands, open interactive PTY sessions
• Filesystem (FilesystemFacet) — read/write/list files, glob patterns
• Network (NetworkFacet) — check egress policy, validate outbound connections
• Tools (ToolsFacet) — list available MCP servers
• Services (ServiceRegistry) — register and resolve platform services