feat(agents-runtime): Sandbox primitive + Docker/E2B providers + sandbox profile picker

[msfstef]

Summary

Adds the Sandbox primitive to the agents runtime — a pluggable abstraction that isolates the filesystem, process, and network operations performed by LLM-driven tool calls — and wires it end-to-end through the runtime, agents-server, desktop, and new-session UI.

The primitive

@electric-ax/agents-runtime/sandbox exposes a deliberately small Sandbox interface: exec, FS methods (readFile/writeFile/mkdir/readdir/exists/remove/stat), fetch (egresses through the sandbox's own network), and dispose. SandboxError carries a policy | runtime | unavailable kind. Containment is documented per concern rather than promised uniformly — writes contained on every provider; reads contained on unrestricted/docker; in-workspace symlink escapes rejected on unrestricted. name is a free-form provider id for logs, not a capability discriminator.

Providers

• unrestrictedSandbox — in-process pass-through over node:fs / child_process; the built-in default. A single-tenant, trusted-code default: the tool layer contains reads/writes to the workspace and rejects symlink escapes, but it shares the host FS/PID namespace and is not a containment boundary.
• dockerSandbox — hardened container isolation via dockerode (optional peer dep): CapDrop ALL, no-new-privileges, no docker socket, pids/mem/cpu limits. deny-all ⇒ NetworkMode=none (the hard network boundary); any other policy gets a bridge, where the allowlist + SSRF guard are fetch-tool-only surface protection, not an exec/bash egress boundary. Exported under /sandbox/docker so callers needing only unrestricted don't pull dockerode.
• remoteSandbox({provider: 'e2b'}) — first-class adapter for E2B's npm SDK (optional peer dep): reattaches to a shared workspace by key and defers lifecycle to the platform (see below). The RemoteSandboxClient interface makes adding Vercel/Daytona/etc. mechanical.

An earlier iteration shipped a nativeSandbox provider (Seatbelt/bubblewrap via @anthropic-ai/sandbox-runtime). It was removed in favour of Docker as the hardened-isolation path; the dependency is gone.

Lifecycle & identity

resolveSandboxIdentity derives three orthogonal facts from an entity's sandbox config + the live wake:

• Identity — an explicit cross-entity key, or a scope shorthand ('entity' default ⇒ entityUrl; 'wake' ⇒ entityUrl#wakeId for full per-wake isolation). "Full isolation" is just a unique key, never a separate code path.
• Durability (persistent) — selects the owner's idle teardown: preserve (stop/suspend, reattachable) vs wipe (remove/kill).
• Ownership (owner) — an owner creates and governs teardown; a non-owner (an inherit spawn) only attaches to an already-live sandbox and never conjures a fresh one.

Per-key locked, refcounted, debounced teardown with deterministic container/workspace naming so a cold-started host reattaches by key. processWake constructs the sandbox once per wake-session and disposes it in the outer finally (handlers must not call dispose()).

Sandbox profiles (advertise / validate / pick)

• Runtimes register named SandboxProfiles (name, label, description?, remote?, local factory). Built-ins: local (always), docker (only when the Docker daemon is reachable), and e2b (only when E2B_API_KEY is set and the optional e2b dep is installed) — so the UI never offers a non-functional choice.
• The runtime advertises the descriptive fields (not the factory closures) to the agents-server via runner registration. New migration 0010_sandbox_profiles adds runners.sandbox_profiles and entities.sandbox.
• Spawn requests carry the sandbox selection; the server validates the chosen profile against the target runner's advertised set (or, for unpinned dispatch, a tenant-wide check) and rejects unserviceable choices up front.
• The new-session UI reads the selected runner's advertised profiles and renders a picker; the sidebar surfaces per-session runner/sandbox badges and can group sessions by runner.

E2B remote provider — shareable, persistent, desktop-ready

remoteSandbox({provider: 'e2b'}) is a first-class shareable provider, mirroring how the Docker provider handles shared/persistent containers:

• Reattach by key. A shared sandbox is tagged with sandboxKey (e2b metadata); a wake looks it up via list + connect (which auto-resumes a paused VM) and only creates one when none is alive — so collaborators and later wakes, even on a freshly cold-started host, converge on the same workspace. A cross-host create race resolves deterministically (oldest wins). Private (per-entity) sandboxes are created fresh per wake.
• Platform-deferred lifecycle. Shared sandboxes are created with lifecycle: { onTimeout: 'pause' } and kept alive by a setTimeout heartbeat while a wake holds them (e2b's timeout is absolute, not idle, so activity doesn't refresh it). dispose() just stops the heartbeat — the platform auto-suspends the VM on idle (filesystem + memory preserved, reattachable for e2b's paused-retention window) with no explicit teardown and no cross-host refcount. Private sandboxes still kill() on dispose.
• Co-location guard relaxed for remote. A per-profile remote flag flows runtime → runner advertisement → server. A shared local sandbox still requires its collaborators to be pinned to a single runner (the container lives on one host); a shared remote sandbox is reachable from any runner, so the single-runner guard is skipped for it.
• Desktop. The Electron app offers the e2b profile gated on an E2B_API_KEY credential (stored alongside the Anthropic/OpenAI/Brave keys and mirrored into the runtime env on save), and externalizes the optional e2b dep from the Electron main bundle. The new-session picker keeps an explicit profile choice across runner re-advertisement and hides the working-directory control for remote profiles. Horton reports and reads AGENTS.md from the sandbox's own working directory (/work in the VM) rather than a host path, so the model never sees paths its tools can't reach.

Tool refactor + hardening (folded in)

• All tool factories (createFetchUrlTool, read/write/edit, bash) now require a Sandbox parameter and route through it.
• bash no longer forwards process.env to children — removes the trivial env-dump leak of secrets like $ANTHROPIC_API_KEY. (The host-sharing unrestricted provider still can't fully contain secrets, e.g. via /proc/<ppid>/environ; use docker/remote for untrusted or multi-tenant entities.)
• read/write/edit reject symlink escapes from the workspace — enforced in the sandbox (unrestricted.resolveWithin, the CVE-2025-53109/53110-shape defense) and surfaced through the tools.
• docker exec polls inspect() until the exec is reaped, so a cleanly-exited command never returns a transient null exit code.
• the boot orphan sweep (sweepOrphanedDockerSandboxes) reclaims only exited ephemeral leftovers — it never force-removes a running container (possible live sibling on a shared daemon) or a persistent one (meant to be reattached by key).
• the docker fetch SSRF guard canonicalizes encoded IP literals (decimal/hex integer, ::ffff:-mapped, bracketed IPv6) so they can't bypass the private/link-local/metadata check.

Built-in entities (Horton, Worker) default to unrestrictedSandbox via chooseDefaultSandbox(workingDirectory). Stronger isolation is opt-in by selecting the docker/e2b profile or constructing dockerSandbox / remoteSandbox directly.

What this primitive is and is not

Targets host isolation for LLM-driven tool calls (cwd escape, env-var exfil, arbitrary network egress, symlink traversal). It does not address prompt-injection-driven misuse of otherwise-legitimate tools.

Provider-specific limitations (documented in the interface, not promised uniformly):

• unrestrictedSandbox is not a containment boundary — it shares the host FS/PID namespace. Tool-layer policy (workspace + symlink containment, host-env scrubbing) shrinks the blast radius but does not stop host-level reads (e.g. /proc) or SSRF from fetch_url.
• docker only hard-enforces deny-all (NetworkMode=none) and allow-all; allowlist is enforced host-side at the fetch tool only, and code run via exec/bash has direct bridge egress.
• sandbox.fetch() on remoteSandbox runs an HTTP client inside the VM via exec, so egress is governed by the VM's network controls.
• e2b shared sandboxes assume sequential collaboration (parent → subagent): the provider offers no cross-host coordination, and pausing disconnects any other live client.

Test plan

• Cross-provider conformance suite pins the Sandbox contract across unrestricted / remote (in-memory fake of the RemoteSandboxClient SDK contract) / docker (gated on daemon availability).

• Per-provider suites: docker lifecycle + keyed reattach + scoped orphan sweep (running/persistent preserved, exited-ephemeral reclaimed); unrestricted containment + tool-layer symlink safety; net-policy SSRF incl. encoded-literal canonicalization; profiles; tool-refactor.

• E2B (mock-based, no live account in CI): reattach-by-key, keep-alive heartbeat, suspend-vs-kill dispose — sandbox-remote.test.ts.

• Server-side spawn validation (electric-agents-sandbox-spawn.test.ts) incl. a shared remote profile bypassing the single-runner guard while a shared local one still requires pinning; runners-router.test.ts round-trips the remote flag.

• Verified locally: agents-runtime (724 tests) + agents-server + agents suites green; all packages typecheck clean; docker integration suite (incl. new exec-reap + scoped-sweep tests) green against a live daemon.

• CI matrix exercises the Docker path on Linux

• Manual smoke test of remoteSandbox({provider: 'e2b'}) against a real E2B account (verified on desktop: shared sandbox resolves to remote:e2b at /work, reattaches across wakes)

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 73.09021% with 701 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.77%. Comparing base (b2ddd59) to head (b0b85e8).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/agents-runtime/src/sandbox/remote/e2b.ts	40.42%	168 Missing ⚠️
packages/agents-runtime/src/sandbox/docker.ts	88.30%	84 Missing ⚠️
...-server-ui/src/components/views/NewSessionView.tsx	0.00%	83 Missing ⚠️
...s-server-ui/src/components/EntityRuntimeBadges.tsx	0.00%	42 Missing ⚠️
packages/agents-runtime/src/process-wake.ts	40.57%	41 Missing ⚠️
...gents-server-ui/src/components/SidebarViewMenu.tsx	0.00%	35 Missing ⚠️
...ackages/agents-runtime/src/sandbox/unrestricted.ts	87.54%	33 Missing ⚠️
packages/agents-runtime/src/sandbox/docker/fs.ts	88.84%	31 Missing ⚠️
packages/agents-runtime/src/sandbox/remote.ts	87.02%	24 Missing ⚠️
packages/agents/src/bootstrap.ts	45.45%	24 Missing ⚠️
... and 18 more

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4369       +/-   ##
===========================================
- Coverage   85.41%   60.77%   -24.65%     
===========================================
  Files           2      330      +328     
  Lines          48    34902    +34854     
  Branches       11     9624     +9613     
===========================================
+ Hits           41    21212    +21171     
- Misses          7    13672    +13665     
- Partials        0       18       +18     

Flag	Coverage Δ
packages/agents	69.69% <49.12%> (?)
packages/agents-mcp	77.54% <ø> (?)
packages/agents-mobile	85.41% <ø> (ø)
packages/agents-runtime	81.99% <81.25%> (?)
packages/agents-server	75.51% <78.66%> (?)
packages/agents-server-ui	6.18% <18.56%> (?)
packages/electric-ax	46.33% <ø> (?)
packages/experimental	87.73% <ø> (?)
packages/react-hooks	86.48% <ø> (?)
packages/start	82.83% <ø> (?)
packages/typescript-client	94.39% <ø> (?)
packages/y-electric	56.05% <ø> (?)
typescript	60.77% <73.09%> (-24.65%)	⬇️
unit-tests	60.77% <73.09%> (-24.65%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Electric Agents Desktop Builds

Build artifacts for commit 6f1b638.

Platform	Status	Artifact
macOS Apple Silicon	Passed	DMG
macOS Intel	Passed	DMG
Windows x64	Passed	Installer
Linux x64	Passed	AppImage / deb

Workflow run

[netlify]

✅ Deploy Preview for electric-next ready!

Name	Link
🔨 Latest commit	b0b85e8
🔍 Latest deploy log	https://app.netlify.com/projects/electric-next/deploys/6a197dfbc7d4b00008614377
😎 Deploy Preview	https://deploy-preview-4369--electric-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[claude]

Claude Code Review

Summary

Iteration 10 picks up the two new commits (25b339b0e, 6f1b6388a) that landed after iteration 9 (2026-06-02) — they close out the one Important finding and all four carried-forward Suggestions from that review. No new issues introduced. The PR is in good shape.

What is Working Well

• IPv6 ULA SSRF false-positive fixed (packages/agents-runtime/src/sandbox/docker/net-policy.ts:135-141). The check now requires the colon (regex anchored as ^f[cd][0-9a-f] plus a zero-to-two hex-digit run plus :), so fc2.com, fda.gov, fdrive.com, fcdomain.com, fc-bayern.com (all popular public hostnames) correctly pass while fc00::1, fd00::1, fdab:1234::1 are still flagged as ULA. The zero-to-two repetition cleanly covers 1- to 4-character first hextets across the entire fc00::/7 range (fc::, fc00::, fcff::, fdab::). Regression tests in sandbox-docker-net-policy.test.ts cover both directions.
• assertAbsolutePosixWorkingDirectory turns the implicit invariant explicit (packages/agents-runtime/src/sandbox/path-containment.ts:23-33), and the remote provider now calls it at construction (packages/agents-runtime/src/sandbox/remote.ts:92). Docker keeps its existing inline startsWith("/") guard; both reject relative workingDirectory consistently, just via slightly different idioms.
• applyInheritedSandbox precedence is now documented (packages/agents-server/src/routing/sandbox.ts:78-83) — clearly states that inherit: true takes the parent identity AND durability wholesale, sibling persistent is intentionally ignored, and the schema permits the combination because precedence is resolved here.
• Doc-comment drift fixed: NewSessionView.tsx:207-210 now mentions the explicit-user-choice branch, and the sandbox-profiles comment at :241-243 accurately says order is preserved (no longer sorted).
• EntityTimeline.tsx:1526-1528 collapses the three sibling <Text> nodes into a single template literal — fewer nodes, same visual.

Issues Found

Critical (Must Fix)

None.

Important (Should Fix)

None.

Suggestions (Nice to Have)

None at this iteration. The DNS-to-private-IP SSRF gap documented in net-policy.ts:114-118 remains a known limitation (closing it would need host-side resolution + per-hop IP pinning); still worth filing as a tracked follow-up so the gap does not get lost as more sandbox providers land.

Issue Conformance

No linked issue. PR description, conversation, and code stay in sync — samwillis 2026-05-29 post-rebase notes match what is actually on disk, and the two latest commits each map to a previous-review finding with no scope creep.

Previous Review Status

All five iteration-9 items addressed:

• Important — IPv6 ULA false-positive → fixed in 25b339b0e with regression tests.
• Suggestion — applyInheritedSandbox silent overrides → resolved by documentation note in 6f1b6388a.
• Suggestion — implicit POSIX-absolute invariant on workingDirectory → resolved by assertAbsolutePosixWorkingDirectory + remote provider call site in 6f1b6388a (docker already guarded inline).
• Suggestion — stale NewSessionView doc-comment → refreshed in 6f1b6388a.
• Suggestion — three-sibling <Text> in EntityTimeline → collapsed to a single <Text> in 6f1b6388a.

---

Review iteration: 10 | 2026-06-02

[github-actions]

Electric Agents Mobile Build

Android preview build for commit 6f1b638.

Platform	Profile	Status	Build
Android	preview	Passed	EAS build

Workflow run

[balegas]

Keen to start using this.

[samwillis]

Rebased this branch onto latest origin/main and resolved the conflicts.

What changed from the rebase forward:

• Kept the new desktop main-process refactor from main rather than reintroducing the older monolithic main.ts/preload.ts code.
• Ported the sandbox branch's E2B API key support into the refactored desktop credential modules (shared/types + credentials/api-keys) so E2B_API_KEY still feeds the bundled runtime.
• Merged the sandbox/runner controls into the new two-row Horton composer layout from main, with runner/sandbox/working-directory controls on the second row.
• Restored the Horton sandbox picker for single-profile runners so the active sandbox is still visible/selectable instead of collapsing to a passive label.
• Tightened runtime metadata UI spacing in the entity header and timeline so the new runner/sandbox badges align with existing controls and status markers.
• Fixed the new-session navigation race where sandbox profiles did not appear until refresh by allowing the desktop runner default to win when its id arrives after the runner list, while preserving explicit user runner choices.
• Fixed the follow-up Select update loop by making runner selection resolve to one stable preferred id and avoiding empty controlled Select values for sandbox profile selects.

Validation run locally after the conflict fixes / follow-ups:

• pnpm --filter @electric-ax/agents-desktop typecheck
• pnpm --filter @electric-ax/agents-server-ui typecheck

Note: these commands need Node 24 here (nvm use 24.15.0); Node 18 trips the repo engine guard before typechecking.