[v2.1] Docker Agent - VNC Tunnel & Streaming Support

[JoshuaAFerguson]

Epic: v2.1 Docker Agent Development
Component: Docker Agent - VNC Streaming
Assignee: Builder (Agent 2)
Milestone: v2.1
Estimated Effort: 8-12 hours

Overview

Implement VNC tunneling for Docker-based sessions to enable browser-based access to GUI applications.

Requirements

VNC Tunnel

• Establish VNC tunnel from agent to session container
• Use Docker port mapping (not Kubernetes port-forward)
• Send VNC tunnel status to Control Plane
• Handle VNC connection lifecycle
• Clean up tunnels on session termination

Architecture

User Browser → Control Plane VNC Proxy → Docker Agent VNC Tunnel → Container VNC Server

Implementation Approach

Similar to K8s agent but using Docker networking:

K8s Agent: Uses port-forward via Kubernetes API
Docker Agent: Uses Docker port mapping or docker exec

Files to Create

agents/docker-agent/
└── pkg/
    └── vnc/
        ├── tunnel.go         # VNC tunnel management
        └── handler.go        # VNC command handler

VNC Commands

1. initialize_vnc_tunnel - Create tunnel to container VNC port
2. vnc_ready - Notify Control Plane tunnel is ready
3. vnc_closed - Cleanup when browser disconnects

Docker Networking Options

Option A: Port Mapping (RECOMMENDED)

// Create container with VNC port mapped to random host port
containerConfig := &container.Config{
    Image: template.Image,
    ExposedPorts: nat.PortSet{
        "3000/tcp": struct{}{},
    },
}

hostConfig := &container.HostConfig{
    PortBindings: nat.PortMap{
        "3000/tcp": []nat.PortBinding{
            {HostIP: "0.0.0.0", HostPort: "0"}, // Random port
        },
    },
}

Option B: Docker Network Bridge

Connect agent container to same Docker network as session containers

Testing Checklist

• VNC tunnel created successfully
• Control Plane receives VNC ready notification
• VNC Proxy can connect to Docker agent tunnel
• Browser can access VNC stream
• Mouse/keyboard input works
• VNC tunnel cleaned up on session termination
• Multiple concurrent VNC tunnels work
• VNC reconnection after agent restart

Performance Targets

• Tunnel Creation: < 2 seconds (matching K8s agent)
• VNC Latency: < 100ms (local network)
• Concurrent Tunnels: 10+ simultaneous sessions

Success Criteria

• ✅ E2E VNC streaming works from browser to Docker container
• ✅ Performance meets targets
• ✅ VNC tunnels stable and reliable
• ✅ No resource leaks on tunnel cleanup

Depends On: #151 (Docker Agent Core Implementation)
Related: #131 (K8s Agent VNC RBAC - reference implementation)

[JoshuaAFerguson]

Closing as superseded by the architectural shift to Selkies-only streaming (#261, April 2026). VNC tunneling is no longer part of the platform. The Docker Agent uses the same Selkies HTTP proxy path (/api/v1/http/<session-id>/) as the K8s Agent — no per-agent tunneling required. If there's Docker-specific Selkies plumbing still missing, please open a fresh, narrower issue.