Version: v2.0-beta.1

StreamSpace v2.0 uses a Control Plane + Agent architecture for multi-platform support. This page covers the v2.0 architecture alongside docs/ARCHITECTURE.md and docs/V2_ARCHITECTURE.md.

┌─────────────┐ ┌──────────────────────────────────┐
│ Web UI │────────▶│ Control Plane (API) │
│ (React) │ REST/WS│ • Agent Hub (WebSocket) │
└─────────────┘ │ • Command Dispatcher │
 │ • VNC Proxy (end-to-end) │
 │ • Multi-Tenancy (org-scoped) │
 └────────────┬─────────────────────┘
 │ WebSocket (wss://)
 ┌────────────┴────────────┐
 │ │
 ┌────▼─────┐ ┌────▼─────┐
 │ K8s Agent│ │Docker Agt│
 │ (~80%) │ │ (~60%) │
 └────┬─────┘ └────┬─────┘
 │ │
 ┌────▼────┐ ┌───▼────┐
 │ K8s │ │ Docker │
 │ Cluster │ │ Host │
 └─────────┘ └────────┘

• Agent Hub: WebSocket server managing agent connections
• Command Dispatcher: Routes commands to appropriate agents
• VNC Proxy: End-to-end VNC tunneling (<100ms latency)
• Multi-Tenancy: Org-scoped access control with JWT claims
• Observability: 3 Grafana dashboards, 12 Prometheus alerts
• API Documentation: OpenAPI 3.0 with Swagger UI at /api/docs

• K8s Agent (agents/k8s-agent/): Production-ready Kubernetes agent (~80% coverage)

  • Session lifecycle management (create, hibernate, terminate)
  • VNC tunnel management
  • Leader election for HA (3-10 replicas)
  • Automatic failover (<5s)

• Docker Agent (agents/docker-agent/): Production-ready Docker agent (~60% coverage)

  • Docker and Docker Compose support
  • HA backends: File, Redis, Swarm
  • Agent reconnection (~23s)

• React + TypeScript with Material-UI
• Real-time agent monitoring via WebSocket
• 98% test passing (189/191 tests)
• Admin dashboard with org-scoped views

1. Agent Registration: Agents connect to Control Plane via WebSocket and register their capabilities
2. User Action: UI/API creates session request with org context
3. Command Dispatch: Control Plane routes command to appropriate agent
4. Session Provisioning: Agent provisions session on target platform (K8s pod or Docker container)
5. VNC Streaming: VNC traffic tunneled through Control Plane to agent to session
6. Hibernation: Configurable idle timeout triggers scale-to-zero

• Control Plane: API latency, error rates, request volume
• Sessions: Active sessions, lifecycle, resources
• Agents: Heartbeat, command latency, capacity

• API Latency: Warning >800ms, Critical >2s
• Session Startup: Warning >30s, Critical >60s
• Agent Heartbeat: Warning >60s, Critical >120s
• Error Rate: Warning >1%, Critical >5%

Refer to Deployment-and-Operations for deployment guides and Roadmap-and-Releases for version history.