Repository navigation
feat(sandbox): add sandbox-initiated supervisor connections with legacy compatibility #4652
Description
User Story
The requesting OpenShell operator needs the sandbox-initiated connection prerequisite to the shared-supervisor prototype in #4429 to apply across the first-party Sandbox Protocol drivers. Newly provisioned sandboxes should dial their supervisor while existing running sandboxes continue working through upgrade.
Problem Statement
The supervisor currently initiates connections to runtime listeners. Reversing only Kubernetes leaves Docker, Podman, and VM with different connection lifecycles and prevents reviewing the transport prerequisite consistently across drivers.
Proposed Design
Keep the existing TLS/gRPC roles and authenticated Sandbox Protocol, reversing only connection establishment. Kubernetes uses TCP, Docker and Podman use protected Unix sockets without enabling workload networking, and VM guests use vsock to the host supervisor. MXC does not use this Sandbox Protocol connection and requires no transport change. Operator-registered external backends retain their existing endpoint contract.
Preserve legacy transport descriptors. Kubernetes records the generation's direction, treats missing metadata as legacy, and migrates only when both Pods are replaced on stop/start or gateway recovery. Existing Docker containers retain their saved direction through restart; Podman restart metadata defaults to legacy when absent. New VM boots use runtime-initiated vsock. New modes require compatible gateway, supervisor, and runtime binaries; rollback to old binaries after selecting a new mode is unsupported.
Acceptance Criteria
- New dedicated Kubernetes, Docker, Podman, and VM sandboxes initiate their protected supervisor connection.
- Running legacy generations are not migrated by reconciliation. Existing Docker and Podman container restarts preserve their direction; Kubernetes generation replacement migrates automatically.
- Connections authenticate the exact runtime generation and retain supervisor bearer authorization. A connection alone cannot acquire ownership or displace an active session.
- Docker/Podman socket storage is writable separately from read-only bootstrap credentials; workload networking remains disabled. Kubernetes permits only the paired control flow. VM control uses vsock without a guest NIC.
- Reconnection retains the current recovery contract, does not replay workload launches or commands, and fails closed on enforcement loss.
- Existing conformance/E2E paths validate the affected drivers; existing tests receive only necessary fixture updates, with no new unit tests.
- Crate implementation notes and relevant operator skill guidance describe compatibility and transport behavior.
Suggested UX
Existing create, exec, stop, and start commands remain unchanged. The transport is selected by the driver and requires no workload-policy field or rollout flag.
Alternatives Considered
- Reversing live connections in place: risks disrupting running workloads.
- Rewriting the RPC protocol at the same time: expands this prerequisite unnecessarily.
- Adding TCP networking to Docker/Podman or VM workloads: weakens existing isolation and is unnecessary.
Activity