Sandbox runtime adapters

Sandbox runtime adapters

Agent harnesses run semi-trusted tool code: shell, browsers, third-party SDKs. Celestial standardizes on a SandboxRuntimePort so operators can swap isolation backends without rewriting harness logic.

Why adapters

Different teams need different threat models, regions, and cost profiles:

• Managed sandboxes for fast onboarding (e.g. E2B).
• Stateful research sandboxes with desktop/browser affordances (e.g. Alibaba OpenSandbox — see historical ADR 014).
• Lightweight per-task isolation for CI (e.g. Microsandbox, smoivm — evaluation targets).

ADR 027 is the source of truth for the matrix and the port contract.

TypeScript stub

The portable interface and a default no-op implementation for tests live in @celestial/agent-host-ports (zero-dependency package). @celestial/shared re-exports the same symbols for gateway and tool bundles. Starflow Engine imports @celestial/agent-host-ports directly to avoid pulling the full shared graph into graph compilation.

E2B adapter (@celestial/sandbox-e2b)

Install the workspace package (or add it to your product bundle) and construct E2BSandboxRuntimePort, then pass it as sandboxRuntime on StarflowServer, WorkflowService, or RunGraphRequest (see packages/sandbox-e2b/README.md). Requires E2B_API_KEY in the environment unless you pass apiKey in the constructor options. Graph shell nodes set shellUseSandbox: true to route through the port.

Graph shellSandboxProvider + host sandboxRuntimes

Shell nodes can set shellSandboxProvider to a string key (for example "e2b"). The host passes sandboxRuntimes: { e2b: new E2BSandboxRuntimePort(...) } on WorkflowEngineOptions / RunGraphRequest, alongside optional strictSandboxProviders (unknown keys fail the run) and sandboxRuntimeFallbackKey (default "default" — the legacy sandboxRuntime option registers under that key when the map does not already define it). Values host, none, off, false disable managed sandbox for that node even if shellUseSandbox is true.

Related decisions

• ADR 027 — adapter matrix; supersedes single-vendor exclusivity from ADR 014.
• ADR 029 — how sandboxes compose with Starflow + Spacecraft verticals.

Companion surface

For private network access into customer environments before or during sandbox execution, see VPN adapters (ADR 028).