Architecture: How should the Sandbox Orchestrator communicate with Firecra...

Documentation for Sessions

🏗️ Architecture: How should the Sandbox Orchestrator communicate with Firecra...

Date: 2026-02-27
Time: 16:23:56 UTC
Session: gspace1-150.4
Agent: angular
Confidence: 90%
Status: ✅ Documented

📋 Decision Context

Question:

How should the Sandbox Orchestrator communicate with Firecracker VMs for xdotool/scrot commands?

Task: VM communication strategy for Firecracker orchestrator

🎯 Decision Made

Chosen:

SSH with per-session ephemeral ed25519 keypairs. VmExecutorService wraps all xdotool/scrot commands in ssh -i /var/lib/sandboxes/{sessionId}/id_rsa root@{vmIp} 'DISPLAY=:99 command'. Keys generated at VM creation, deleted at VM destruction.

Options Considered:

  1. SSH with ephemeral keys (chosen)
  2. Firecracker vsock (direct hypervisor)
  3. Serial console
  4. Custom gRPC agent (E2B approach)

💭 Reasoning

ROOT CAUSE: Firecracker VMs are isolated microVMs — no shared filesystem, no Docker exec, no container runtime. Need a network-based communication channel. SSH chosen because: (1) universally available in Ubuntu rootfs (just apt install openssh-server), (2) no custom agent code needed inside VM, (3) key-based auth is secure, (4) per-session ephemeral keys mean no key management burden. ALTERNATIVES REJECTED: Firecracker vsock (direct hypervisor channel, lower latency) — requires custom guest agent binary, more complex, defer to v2. Serial console — too slow for binary data (screenshots). gRPC custom agent — E2B approach but requires building/maintaining agent binary. TRADEOFF: SSH adds ~50-100ms per command. Acceptable because the Anthropic Computer Use observe-think-act loop takes 2-3 seconds per iteration regardless (Claude reasoning time dominates). FUTURE RISK: If screenshot frequency increases to <500ms, SSH becomes bottleneck → migrate to vsock. EARLY WARNING: Monitor sandbox_screenshot_duration_seconds Prometheus metric.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation