[REQ-005] Live Terminal & Sandboxed Code Execution

[pv-dsgn]

Requirement

REQ-005: Live terminal - visitor can initiate a sandboxed container session for any repo tagged as "runnable" by the developer

Acceptance Criteria

• Container spins up in < 4s p95
• Session is isolated (no internet egress, no access to other containers)
• Auto-terminates after 15 minutes of inactivity
• Visitor can run commands in sandboxed environment
• WebSocket connection for real-time terminal I/O
• Graceful disconnection handling

Technical Details

• Sandbox provider: E2B or Firecracker (evaluate both)
• Environment isolation: Linux containers with network restrictions
• Session management and timeout handling
• Terminal emulation (xterm.js or similar)
• Resource limits per container (CPU, memory, disk)
• Cost tracking and rate limiting

Infrastructure Requirements

• Container orchestration setup
• Session state management
• Cost monitoring (sandbox execution is highest infrastructure cost)

Design Considerations

• Loading state with progress indicators ("Pulling repo… Installing dependencies…")
• Error fallback to code preview modal on build failures
• Mobile: degrades to "view code" modal on screens < 768px